Skip to main content
Human guide: work with your agent → Inspect one Socrata Open Data action before starting provider-backed work. Your first result is a verified input and output contract.

​
Provider-specific requirements

Query any Socrata-hosted government open-data portal. Free, keyless, and the same query grammar everywhere.

​
What this covers

Socrata powers a large share of US city, county, and state open-data portals. Common dataset families:
  • Building permits and construction approvals
  • Business licenses and registrations
  • Restaurant and food-safety inspections
  • Code enforcement and property violations
  • 311 service requests
Coverage is per-portal, not national. There is no single “US building permits” dataset — each city publishes its own. Confirm a metro is on Socrata before promising coverage for it.

​
Order of operations

  1. socrata_discover_datasets — search the cross-domain catalog by keyword. Returns the 4x4 id, the hosting domain, and the column list for each match.
  2. socrata_describe_dataset — read the exact column names and types before writing SoQL. Column names are per-dataset and rarely what you would guess: NYC DOB permits uses bin__, job__, and permittee_s_business_name.
  3. socrata_query_dataset — run the query.
Skipping step 2 is the most common way to waste calls. A wrong column name returns a 400 (query.soql.no-such-column), not an empty result.

​
Addressing

Every dataset-scoped call needs both datasetId and domain:
The domain is a routing input — it selects the host, and is not forwarded as a query parameter. Passing a 4x4 without its domain is rejected at validation.

​
SoQL notes

  • $select=count(*) is the cheapest way to size a dataset before pulling it.
  • $where uses SQL-ish syntax with single-quoted literals: borough='BRONX' AND issuance_date > '2026-01-01'.
  • $limit is capped at 50,000 per request. Socrata itself will happily stream a 270 MB response to an uncapped request. The cap fails loudly instead so you paginate deliberately.
  • $order defaults to :id when unset. Do not remove it when paginating — Socrata’s row order is otherwise unstable across pages, which silently duplicates and drops rows.

​
Joining to accounts

Most of these datasets key on address, not on a company identifier. Address normalization is the main correctness risk. expect meaningful match loss when joining raw address strings to a CRM. Where a dataset exposes a parcel or building identifier (NYC’s bin__, or bbl), prefer it over the address. Owner and contractor business names are present in permit data and are usable for fuzzy company matching, with the usual legal-suffix caveats.

​
Not every portal is Socrata

Some government portals run CKAN or ArcGIS instead and will not respond to these endpoints. data.ca.gov, for example, is CKAN and returns an entirely different payload shape. Use socrata_discover_datasets to confirm a dataset is on the Socrata network before building against it.

​
API version and credentials

This connector uses keyless SODA 2.1. Upstream now identifies SODA 3.0 as the latest API. its query endpoint requires authentication or an application token. Do not substitute SODA 3.0 paths into these tools. There is no managed credential environment variable for this connector, and optional upstream X-App-Token headers are not currently exposed by it.

​
Find an applicable action

Confirm your effective workspace, then search the live catalog:
Search returns candidates. Check the returned provider and operation rather than selecting a similar title automatically.

​
Inspect the selected contract

Replace <returned-tool-id> with the identifier returned by discovery:
These commands do not execute the selected provider action. Read its required inputs, supported access mode, pricing unit, outputs, and limits. A connection does not establish that every action supports BYOK. Follow the provider-specific requirements above and the live action contract.

​
Prepare one reviewed input

Use one authorized record that matches the inspected schema. Preserve its source identity and define the result you will accept. Open the action reference for its payload and response shape. Provider-backed execution can incur usage or external effects. For reusable logic, follow Write Plays. For direct-call recovery, use Tool execution recovery.
Continue only when the workspace, provider, required fields, acceptance rule, and applicable price are understood. Keep unavailable access separate from no-result evidence.