OpenAPI specification

Full parameter and response reference for the package_search endpoint.

package_search needs no token for public datasets. Try it with curl or an API client:

curl "https://data.humdata.org/api/3/action/package_search?q=*:*&rows=5"

For a GUI, import the OpenAPI spec into Postman, Insomnia, Bruno, or Scalar. Add a token only to include private or draft datasets for organizations to which you belong.

Search datasets

get

Search for datasets (packages) using Solr query syntax. Supports filtering, faceting, sorting, and pagination. No authentication required for public data.

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

Authorizations

ApiKeyAuthCatalog

AuthorizationstringOptional

HDX API token. Optional — public dataset search needs no authentication; a token is only required to include private or draft datasets.

Query parameters

qstring · nullableOptional

Solr search query. Supports Solr syntax. Defaults to "*:*" (all datasets).

Default: *:*

fqstring · nullableOptional

Solr filter query. Restricts results without affecting relevance scoring.

Default: null

fq_liststring[] · nullableOptional

Additional filter queries as a list. Each entry is ANDed with fq.

Default: null

sortstring · nullableOptional

Sort order as a Solr sort string. Defaults to "score desc, metadata_modified desc".

Default: score desc, metadata_modified desc

rowsinteger · max: 1000 · nullableOptional

Maximum number of datasets to return. Defaults to 10, maximum 1000.

Default: 10

startinteger · nullableOptional

Offset into the result set. Used for pagination.

Default: null

facetstring · nullableOptional

Enable faceted results. Defaults to "true".

Default: true

facet.mincountinteger · nullableOptional

Minimum count for a facet value to be included in the response.

Default: null

facet.limitinteger · nullableOptional

Maximum number of values returned per facet field. Defaults to 50.

Default: 50

facet.fieldstring[] · nullableOptional

Fields to facet on.

Default: null

include_draftsboolean · nullableOptional

Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to false.

Default: false

include_deletedboolean · nullableOptional

Include deleted datasets in results. Defaults to false.

Default: false

include_privateboolean · nullableOptional

Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to false.

Default: false

use_default_schemaboolean · nullableOptional

Return results using the default package schema rather than any custom schema configured on the instance. Defaults to false.

Default: false

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 requested action or endpoint does not exist.

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/package_search

HTTPcURLJavaScriptPython

GET /api/3/action/package_search HTTP/1.1
Host: data.humdata.org
Authorization: YOUR_API_KEY
Accept: */*

{
  "help": "text",
  "success": true,
  "result": {
    "count": 1,
    "results": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "sort": "text",
    "facets": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "search_facets": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "facet_pivot": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "facet_queries": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "expanded": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Search datasets (POST)

post

Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for long fq_list or facet.field values.

Authorizations

ApiKeyAuthCatalog

AuthorizationstringOptional

HDX API token. Optional — public dataset search needs no authentication; a token is only required to include private or draft datasets.

Body

application/json

qstring · nullableOptional

Solr search query. Supports Solr syntax. Defaults to "*:*" (all datasets).

Default: *:*

fqstring · nullableOptional

Solr filter query. Restricts results without affecting relevance scoring.

Default: null

fq_liststring[] · nullableOptional

Additional filter queries as a list. Each entry is ANDed with fq.

Default: null

sortstring · nullableOptional

Sort order as a Solr sort string. Defaults to "score desc, metadata_modified desc".

Default: score desc, metadata_modified desc

rowsinteger · max: 1000 · nullableOptional

Maximum number of datasets to return. Defaults to 10, maximum 1000.

Default: 10

startinteger · nullableOptional

Offset into the result set. Used for pagination.

Default: null

facetstring · nullableOptional

Enable faceted results. Defaults to "true".

Default: true

facet.mincountinteger · nullableOptional

Minimum count for a facet value to be included in the response.

Default: null

facet.limitinteger · nullableOptional

Maximum number of values returned per facet field. Defaults to 50.

Default: 50

facet.fieldstring[] · nullableOptional

Fields to facet on.

Default: null

include_draftsboolean · nullableOptional

Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to false.

Default: false

include_deletedboolean · nullableOptional

Include deleted datasets in results. Defaults to false.

Default: false

include_privateboolean · nullableOptional

Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to false.

Default: false

use_default_schemaboolean · nullableOptional

Return results using the default package schema rather than any custom schema configured on the instance. Defaults to false.

Default: false

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 requested action or endpoint does not exist.

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/package_search

HTTPcURLJavaScriptPython

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

{
  "q": "*:*",
  "fq": "text",
  "fq_list": [
    "text"
  ],
  "sort": "score desc, metadata_modified desc",
  "rows": 10,
  "start": 1,
  "facet": "true",
  "facet.mincount": 1,
  "facet.limit": 50,
  "facet.field": [
    "text"
  ],
  "include_drafts": false,
  "include_deleted": false,
  "include_private": false,
  "use_default_schema": false
}

{
  "help": "text",
  "success": true,
  "result": {
    "count": 1,
    "results": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "sort": "text",
    "facets": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "search_facets": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "facet_pivot": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "facet_queries": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "expanded": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}