Developer reference

HTTP API

Search and inspect datasets with JSON endpoints, then stream a filtered selection as CSV.

https://iamodi.com

Endpoints

POST endpoints accept JSON with content-type: application/json.

Endpoint	Body / query	Returns
POST`/v1/search`	`query`, `sources?`, `limit?`, `offset?`	Ranked datasets and suggested filters.
POST`/list-sources`	None	Sources, dataset counts and freshness.
POST`/source-catalog`	`src`, `offset?`, `limit?`	One source's datasets.
POST`/inspect-dataset`	`src`, `dataflowID`, `max_examples?`	Dimensions and sample values.
POST`/dimension-values`	`src`, `dataflowID`, `dimension`, `query?`, pagination	Codes and labels for one dimension.
POST`/search-for-tag`	`src`, `dataflowID`, `tag` or `tags`	Matching codes across dimensions.
POST`/dataflow-url`	`src`, `dataflowID`	The provider's dataset page.
POST`/request-url`	`src`, `dataflowID`, `filters?`	The provider URL for a selection.
GET`/dataset.csv`	Query parameters	Filtered CSV.

Search example

curl -X POST https://iamodi.com/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":"unemployment Spain","limit":3}'

Filters

filters maps a dimension ID to one code, several codes, or a regular-expression pattern. Use the exact IDs and codes returned by /inspect-dataset.

Example	Selects
`{"geo":"ES"}`	One value
`{"geo":["ES","FR"]}`	Several values
`{"geo":"re:^ES\\d{3}$"}`	Codes or labels matching the expression after `re:`

Omitted dimensions are unfiltered. Unknown dimensions and codes return an error rather than silently widening the result.

CSV downloads

GET /dataset.csv requires src and dataflowID. Pass filters as URL-encoded JSON. Optional limit caps rows; check=1 validates the request without starting a download.

curl -G https://iamodi.com/dataset.csv \
  --data-urlencode src=ESTAT \
  --data-urlencode dataflowID=UNE_RT_A \
  --data-urlencode 'filters={"geo":["ES","FR"],"sex":"T"}' \
  -o data.csv

Large selections may be rejected by the provider. Add filters or use the returned provider_url.

Errors and limits

Status	Meaning
`400`	Invalid request, dimension or code.
`404`	Source or dataset not found.
`413`	Selection is too large; narrow the filters.
`429`	Rate limit or download capacity reached; retry shortly.
`502` / `504`	The upstream provider failed or timed out.
`503`	ODI is at capacity; retry shortly.

Keep automated use modest. JSON endpoints allow roughly 120 requests per minute per IP; CSV downloads have tighter concurrency limits.