socrata_query
Query rows from allowlisted Socrata open-data portals using SODA API. Supports SoQL filters, pagination, and exact total counts for state spend and vendor datasets.
Instructions
Query rows from an allowlisted Socrata/SODA open-data portal (keyless; ~a dozen US state portals + USAC E-rate on one identical API — state spend/checkbook/contract/vendor-payment datasets). Input domain (curated allowlist enum — the SSRF host guard), datasetId (4x4, from socrata_discover_datasets), optional SoQL select/where/order/q, limit (≤1000, def 100), offset, withTotal (def true). HONESTY: SODA's row response has no total, so a count(*) companion supplies an exact totalAvailable; if it fails the rows still return with totalAvailable:null + a note (hasMore is then inferred from page-fill, never a false complete). Genuine-empty ⇒ complete:true/total:0; an outage/400/404 THROWS (never a fake empty). Value fields are strings.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Optional SoQL $q full-text search across the row. | |
| limit | No | Rows per page ($limit), 1..1000, default 100. | |
| order | No | Optional SoQL $order, e.g. 'amount DESC'. | |
| where | No | Optional SoQL $where filter, e.g. "fiscal_year='2024' AND amount>1000". A bad column ⇒ upstream HTTP 400 ⇒ invalid_input (surfaced, never silent). | |
| domain | Yes | Which allowlisted Socrata portal to query (curated .gov hosts + USAC E-rate .org; the SSRF host allowlist — no free host). e.g. data.ny.gov, data.texas.gov, data.wa.gov, opendata.usac.org. | |
| offset | No | 0-based row offset ($offset) for pagination, default 0. | |
| select | No | Optional SoQL $select (column projection / aggregate), e.g. 'agency,SUM(amount)'. | |
| datasetId | Yes | The dataset's Socrata 4x4 id, e.g. 'kwxv-fwze' (from socrata_discover_datasets). Exactly [a-z0-9]{4}-[a-z0-9]{4} (9 chars; no surrounding whitespace). | |
| withTotal | No | true (default) ⇒ issue a count(*) companion query so totalAvailable is exact. false ⇒ skip it (one fewer request); totalAvailable is null and a note discloses results may be truncated at $limit. |