canonical: https://jentic.com/apis/dev.socrata.com/socrata

# Dev Socrata Socrata Open Data API (SODA)

Jentic publishes the only available OpenAPI specification for the Socrata Open Data API (SODA), keeping it validated and agent-ready. SODA exposes the open government datasets hosted on Socrata-powered portals, with per-portal domains like data.cityofnewyork.us and data.ct.gov. The seven endpoints support SoQL queries, CSV and GeoJSON exports, dataset metadata lookups, and a catalog discovery endpoint, so an agent can find a dataset, inspect its schema, and pull filtered or aggregated rows without scraping HTML. Authentication ranges from anonymous reads to app-token, basic, and OAuth 2.0 for write operations and private datasets.

## For AI agents

Discover and query open government datasets across Socrata-powered portals via 7 SODA endpoints with SoQL filtering, aggregation, and GeoJSON or CSV export.

## Scope

Does not write to or publish new datasets, manage Socrata portal admin, or model proprietary data - use for querying, exporting, and discovering open datasets on Socrata-powered portals only.

## Capabilities

- Discover datasets across portals via GET `/api/catalog/v1` with keyword and category filters
- Run SoQL filters and aggregations via GET or POST `/api/v3/views/{datasetId}/query.json`
- Export query results as CSV via GET `/api/v3/views/{datasetId}/export.csv`
- Retrieve full dataset rows in JSON or GeoJSON via `/resource/{datasetId}.json` and `/resource/{datasetId}.geojson`
- Pull dataset metadata, schema, and update timestamps via GET `/api/views/metadata/v1/{datasetId}`
- Authenticate with an X-App-Token header for higher rate limits or with basic auth and OAuth 2.0 for private datasets and write operations

## Use cases

### Open data exploration and reporting

Analysts and AI agents can find a relevant open dataset on any Socrata-powered portal by hitting GET `/api/catalog/v1`, then read its schema via `/api/views/metadata/v1/{datasetId}` and run a SoQL query through `/api/v3/views/{datasetId}/query.json` to get exactly the slice they need. Because the same shape works across hundreds of city, state, and federal portals, one pipeline covers many sources.

Example prompt: GET `/api/catalog/v1`?q=motor%20vehicle%20crashes on data.cityofnewyork.us, pick the top dataset, then POST `/api/v3/views/{datasetId}/query.json` with a SoQL aggregating crashes by borough.

### Civic dashboards and embedded maps

Build civic dashboards by pulling fresh data from `/resource/{datasetId}.json` for tabular views and `/resource/{datasetId}.geojson` for map layers. The metadata endpoint exposes the dataset's last-updated timestamp, so a dashboard can show data freshness without scraping. This is the standard way municipalities expose machine-readable open data, so the same code reuses across cities.

Example prompt: GET `/resource/erm2-nwe9.geojson`?$where=created_date>'2026-01-01' to fetch recent 311 service requests for a city map layer.

### Bulk data export to a warehouse

Pull entire datasets or filtered subsets to CSV via GET `/api/v3/views/{datasetId}/export.csv` for loading into a data warehouse or notebook. SoQL parameters let you constrain the export to recent rows or specific columns, keeping the payload small. Because the URL is stable, the same export can be scheduled and re-run incrementally.

Example prompt: GET `/api/v3/views/abcd-1234/export.csv`?$where=updated_at>'2026-06-01'&$limit=50000 to incrementally export new rows into a warehouse.

### Agent-driven civic insight

An AI agent answering questions like 'how many 311 noise complaints were filed in Brooklyn last month?' can call SODA through Jentic. Jentic resolves the dataset, returns the SoQL query operation schema, and executes it with the agent's filter - no API key juggling, no scraping, just a structured answer pulled from the canonical open data portal.

Example prompt: Through Jentic, search 'query a Socrata dataset', load the SODA query.json operation, and execute with $select=count(*) and a $where clause for borough and date range.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/catalog/v1` | Discover datasets on a Socrata portal |
| GET | `/api/v3/views/{datasetId}/query.json` | Run a SoQL query (read) |
| POST | `/api/v3/views/{datasetId}/query.json` | Run a SoQL query with a JSON body for complex queries |
| GET | `/api/v3/views/{datasetId}/export.csv` | Export query results as CSV |
| GET | `/resource/{datasetId}.json` | Read dataset rows as JSON |
| GET | `/resource/{datasetId}.geojson` | Read dataset rows as GeoJSON |
| GET | `/api/views/metadata/v1/{datasetId}` | Read dataset metadata and schema |

## Key resources

- **Catalog Discovery** — Find datasets across a portal via GET `/api/catalog/v1` with keyword, tag, and category filters.
- **Query (SoQL)** — Run SoQL filters and aggregations via GET or POST `/api/v3/views/{datasetId}/query.json.`
- **Resource Read** — Pull dataset rows via `/resource/{datasetId}.json` and `/resource/{datasetId}.geojson.`
- **Metadata** — Inspect schema, owner, and freshness via GET `/api/views/metadata/v1/{datasetId}.`
- **Export** — Stream CSV exports via GET `/api/v3/views/{datasetId}/export.csv.`

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 63 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 64 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/dev.socrata.com/socrata/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Socrata Open Data API by hand means choosing between its app token, basic, and OAuth 2.0 auth, pointing calls at the right portal domain (https://{domain}), and building the catalog, SoQL query, export, and metadata calls yourself. Through Jentic you install once, import the Socrata Open Data API from the API Directory, store the app token once, and your agent calls it.
- **Permission scoping:** Socrata puts the dataset id in the URL path (`/api/v3/views/{datasetId}/query.json`), and the operations here are read-only queries, exports, and metadata reads, so a rule can pin your agent to querying and exporting datasets with no ability to publish or administer the portal.
- **Credential handling:** Your Socrata app token, basic credentials, or OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'query open data on traffic crashes' or 'export a dataset as CSV', and Jentic returns the matching SODA operation with its dataset and SoQL parameter shapes so the agent calls the right endpoint without reading the docs.

## Related APIs

- **data.gov** — Federal open data catalog spanning hundreds of agencies.
- **NYT Article Search** — Searchable archive of news articles for narrative context around data.
- **Google BigQuery** — Cloud data warehouse with public datasets for SQL-based analysis.

## FAQ

### Why is there no official OpenAPI spec for the Socrata Open Data API?

Socrata does not publish an OpenAPI specification for SODA. Jentic generates and maintains this spec so that AI agents and developers can call SODA via structured tooling. It is validated against live Socrata portals and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Socrata SODA API use?

Public dataset reads are anonymous, but for higher rate limits Socrata expects an X-App-Token header issued from your Socrata profile. Write operations and private datasets require HTTP basic auth, and third-party apps can use OAuth 2.0 against the portal's `/oauth/authorize` and `/oauth/access_token` endpoints. Through Jentic, app tokens and OAuth tokens are vaulted and attached at request time.

### Can I run a SoQL aggregation query with the Socrata API?

Yes. POST `/api/v3/views/{datasetId}/query.json` with a SoQL body using $select with count, sum, or avg and $group to aggregate, plus $where for filters. Use the GET form for simpler queries that fit in a URL. The same dataset can also be queried via `/resource/{datasetId}.json` with $select, $where, and $group parameters.

### How do I find datasets on a specific Socrata portal?

Call GET `/api/catalog/v1` against the portal's domain (e.g., data.cityofnewyork.us). Pass q for keywords, categories for category filters, and tags for tag filters. The response includes dataset ids you can plug into `/api/v3/views/{datasetId}/query.json` or `/resource/{datasetId}.json.`

### What are the rate limits for the Socrata SODA API?

Anonymous requests share a low per-IP throttle. Sending an X-App-Token gives an application-scoped quota that is sufficient for most production use. Treat HTTP 429 as a signal to back off and consider registering an app token if you have not already.

### How do I export a dataset to CSV through Jentic?

Through Jentic, search 'export a Socrata dataset to CSV', load the `/api/v3/views/{datasetId}/export.csv` operation, and execute it with the dataset id and any SoQL filter parameters. Stream the response into your warehouse loader.

### Can I limit what my agent is allowed to do with the Socrata Open Data API?

Yes. Because you run Jentic One yourself, your own rules decide which SODA operations and credentials the agent may use, and every operation here is read-only: catalog discovery via GET `/api/catalog/v1`, SoQL queries via `/api/v3/views/{datasetId}/query.json`, CSV exports via export.csv, resource reads, and metadata lookups. Since the dataset id lives in the URL path, you can pin the agent to querying, exporting, and inspecting specific datasets with no ability to publish data or administer the portal. Your Socrata app token, basic, or OAuth credentials are attached only at execution time and never reach the agent's prompt or logs.