OpenAPI specification

Full parameter and response reference for the three Tabular Data Endpoints.

Query these endpoints with curl or an API client, using your HDX token:

curl -H "Authorization: <your-api-token>" \  "https://data.humdata.org/api/3/action/datastore_search?resource_id=<resource-id>&limit=5"

For a GUI, import the OpenAPI spec into Postman, Insomnia, Bruno, or Scalar and set an Authorization header. Get your token at data.humdata.org → profile → Manage API tokens.

Get DataStore resource metadata

get

Retrieve field definitions, type information, and size/count metadata for a DataStore resource.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

HDX API token. Required for all Tabular Data Endpoint requests, including public resources.

Query parameters

resource_idstringRequired

The id or alias of the DataStore resource to describe. Required.

Responses

200

Successful response.

application/json

helpstringRequired

URL to the API documentation for this action.

successbooleanRequired

Whether the request succeeded.

403

Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.

application/json

404

Not Found — the resource_id does not exist in the DataStore.

application/json

409

Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).

application/json

429

Too Many Requests — rate limit exceeded.

application/json

500

Internal Server Error — unexpected server-side failure.

application/json

get/datastore_info

HTTPcURLJavaScriptPython

GET /api/3/action/datastore_info?resource_id=text HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Accept: */*

{
  "help": "text",
  "success": true,
  "result": {
    "meta": {
      "aliases": [
        "text"
      ],
      "count": 1,
      "db_size": 1,
      "id": "text",
      "idx_size": 1,
      "size": 1,
      "table_type": "BASE TABLE"
    },
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  }
}

Get DataStore resource metadata (POST)

post

Identical to the GET form.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

HDX API token. Required for all Tabular Data Endpoint requests, including public resources.

Body

application/json

resource_idstringRequired

The id or alias of the DataStore resource to describe. Required.

Responses

200

Successful response.

application/json

helpstringRequired

URL to the API documentation for this action.

successbooleanRequired

Whether the request succeeded.

403

Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.

application/json

404

Not Found — the resource_id does not exist in the DataStore.

application/json

409

Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).

application/json

429

Too Many Requests — rate limit exceeded.

application/json

500

Internal Server Error — unexpected server-side failure.

application/json

post/datastore_info

HTTPcURLJavaScriptPython

POST /api/3/action/datastore_info HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "resource_id": "text"
}

{
  "help": "text",
  "success": true,
  "result": {
    "meta": {
      "aliases": [
        "text"
      ],
      "count": 1,
      "db_size": 1,
      "id": "text",
      "idx_size": 1,
      "size": 1,
      "table_type": "BASE TABLE"
    },
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  }
}

Search a DataStore resource

get

Query rows from a DataStore resource with optional filtering, full-text search, sorting, and pagination.

Pass parameters as query string arguments (GET) or as a JSON body (POST).

Authorizations

ApiKeyAuth

AuthorizationstringRequired

HDX API token. Required for all Tabular Data Endpoint requests, including public resources.

Query parameters

resource_idstringRequired

The id or alias of the resource to search. Required.

qany of · nullableOptional

Full-text search query. Pass a string to search across all fields, or a dictionary of {field: query} to target specific fields. Note: behavior differs subtly from filters — q uses full-text ranking while filters performs exact matching.

Default: null

stringOptional

or

full_textstring · nullableOptional

Full-text search query applied across all fields. Similar to q with a string value, but always searches all fields. Cannot be combined with q.

Default: null

distinctboolean · nullableOptional

Return only unique rows. Defaults to false.

Default: false

plainboolean · nullableOptional

Treat the q query as plain text (no special FTS operators). Set to false to use PostgreSQL tsquery syntax. Defaults to true.

Default: true

languagestring · nullableOptional

Language used for full-text search stemming. Defaults to english.

Default: english

limitinteger · nullableOptional

Maximum number of rows to return. Defaults to 100.

Default: 100

offsetinteger · nullableOptional

Number of rows to skip before returning results. Used for pagination.

Default: null

fieldsany of · nullableOptional

Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields.

Default: null

string[]Optional

or

stringOptional

sortstring · nullableOptional

Comma-separated list of fields to sort by, with optional asc/desc direction. Example: "fieldname1 asc, fieldname2 desc".

Default: null

include_totalboolean · nullableOptional

Include the total number of matching rows in the response. Defaults to true.

Default: true

total_estimation_thresholdinteger · nullableOptional

When include_total is true and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to null (default) to always return an exact count.

Default: null

records_formatstring · enum · nullableOptional

Format for the returned records. objects returns a list of dicts, lists returns a list of lists, csv and tsv return delimited strings. Defaults to objects.

Default: objectsPossible values:

Responses

200

Successful response.

application/json

helpstringRequired

URL to the API documentation for this action.

successbooleanRequired

Whether the request succeeded.

403

Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.

application/json

404

Not Found — the resource_id does not exist in the DataStore.

application/json

409

Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).

application/json

429

Too Many Requests — rate limit exceeded.

application/json

500

Internal Server Error — unexpected server-side failure.

application/json

get/datastore_search

HTTPcURLJavaScriptPython

GET /api/3/action/datastore_search?resource_id=text HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Accept: */*

{
  "help": "text",
  "success": true,
  "result": {
    "resource_id": "text",
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "offset": 1,
    "limit": 1,
    "filters": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "include_total": true,
    "records_format": "text",
    "total": 1,
    "total_was_estimated": true,
    "total_estimation_threshold": 1,
    "records": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "_links": {
      "start": "text",
      "next": "text"
    }
  }
}

Search a DataStore resource (POST)

post

Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for large filters or fields payloads.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

HDX API token. Required for all Tabular Data Endpoint requests, including public resources.

Body

application/json

resource_idstringRequired

The id or alias of the resource to search. Required.

qany of · nullableOptional

Full-text search query. Pass a string to search across all fields, or a dictionary of {field: query} to target specific fields. Note: behavior differs subtly from filters — q uses full-text ranking while filters performs exact matching.

Default: null

stringOptional

or

full_textstring · nullableOptional

Full-text search query applied across all fields. Similar to q with a string value, but always searches all fields. Cannot be combined with q.

Default: null

distinctboolean · nullableOptional

Return only unique rows. Defaults to false.

Default: false

plainboolean · nullableOptional

Treat the q query as plain text (no special FTS operators). Set to false to use PostgreSQL tsquery syntax. Defaults to true.

Default: true

languagestring · nullableOptional

Language used for full-text search stemming. Defaults to english.

Default: english

limitinteger · nullableOptional

Maximum number of rows to return. Defaults to 100.

Default: 100

offsetinteger · nullableOptional

Number of rows to skip before returning results. Used for pagination.

Default: null

fieldsany of · nullableOptional

Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields.

Default: null

string[]Optional

or

stringOptional

sortstring · nullableOptional

Comma-separated list of fields to sort by, with optional asc/desc direction. Example: "fieldname1 asc, fieldname2 desc".

Default: null

include_totalboolean · nullableOptional

Include the total number of matching rows in the response. Defaults to true.

Default: true

total_estimation_thresholdinteger · nullableOptional

When include_total is true and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to null (default) to always return an exact count.

Default: null

records_formatstring · enum · nullableOptional

Format for the returned records. objects returns a list of dicts, lists returns a list of lists, csv and tsv return delimited strings. Defaults to objects.

Default: objectsPossible values:

Responses

200

Successful response.

application/json

helpstringRequired

URL to the API documentation for this action.

successbooleanRequired

Whether the request succeeded.

403

Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.

application/json

404

Not Found — the resource_id does not exist in the DataStore.

application/json

409

Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).

application/json

429

Too Many Requests — rate limit exceeded.

application/json

500

Internal Server Error — unexpected server-side failure.

application/json

post/datastore_search

HTTPcURLJavaScriptPython

POST /api/3/action/datastore_search HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 286

{
  "resource_id": "text",
  "filters": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "q": "text",
  "full_text": "text",
  "distinct": false,
  "plain": true,
  "language": "english",
  "limit": 100,
  "offset": 1,
  "fields": [
    "text"
  ],
  "sort": "text",
  "include_total": true,
  "total_estimation_threshold": 1,
  "records_format": "objects"
}

{
  "help": "text",
  "success": true,
  "result": {
    "resource_id": "text",
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "offset": 1,
    "limit": 1,
    "filters": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "include_total": true,
    "records_format": "text",
    "total": 1,
    "total_was_estimated": true,
    "total_estimation_threshold": 1,
    "records": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "_links": {
      "start": "text",
      "next": "text"
    }
  }
}

Query a DataStore resource with SQL

get

Execute a SQL SELECT statement against one or more DataStore resources. Useful for aggregations, joins, and complex filtering that datastore_search cannot express.

Only SELECT statements are permitted.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

HDX API token. Required for all Tabular Data Endpoint requests, including public resources.

Query parameters

sqlstringRequired

A single SQL SELECT statement to execute against the DataStore. Required. Only SELECT statements are permitted — INSERT, UPDATE, DELETE, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. SELECT * FROM "<resource_id>").

Responses

200

Successful response.

application/json

helpstringRequired

URL to the API documentation for this action.

successbooleanRequired

Whether the request succeeded.

403

Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.

application/json

404

Not Found — the resource_id does not exist in the DataStore.

application/json

409

Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).

application/json

429

Too Many Requests — rate limit exceeded.

application/json

500

Internal Server Error — unexpected server-side failure.

application/json

get/datastore_search_sql

HTTPcURLJavaScriptPython

GET /api/3/action/datastore_search_sql?sql=text HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Accept: */*

{
  "help": "text",
  "success": true,
  "result": {
    "sql": "text",
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "records": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "records_truncated": true
  }
}

Query a DataStore resource with SQL (POST)

post

Identical to the GET form. Use POST for long SQL statements.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

HDX API token. Required for all Tabular Data Endpoint requests, including public resources.

Body

application/json

sqlstringRequired

A single SQL SELECT statement to execute against the DataStore. Required. Only SELECT statements are permitted — INSERT, UPDATE, DELETE, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. SELECT * FROM "<resource_id>").

Responses

200

Successful response.

application/json

helpstringRequired

URL to the API documentation for this action.

successbooleanRequired

Whether the request succeeded.

403

Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.

application/json

404

Not Found — the resource_id does not exist in the DataStore.

application/json

409

Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).

application/json

429

Too Many Requests — rate limit exceeded.

application/json

500

Internal Server Error — unexpected server-side failure.

application/json

post/datastore_search_sql

HTTPcURLJavaScriptPython

POST /api/3/action/datastore_search_sql HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "sql": "text"
}

{
  "help": "text",
  "success": true,
  "result": {
    "sql": "text",
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "records": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "records_truncated": true
  }
}