Welcome to the new home of the HDX FAQ
For the complete documentation index, see llms.txt. This page is also available as Markdown.

package_search

Learn how to query package_search to catalogue data on HDX

The package_search endpoint searches for datasets based on specified criteria. It supports powerful filtering using Solr query syntax and returns paginated results with dataset metadata.

Base URL: https://data.humdata.org/api/3/action/package_search

Method: GET or POST

Use Cases

  • Discovery: Find all datasets related to a specific crisis, country, or topic

  • Monitoring: Track when new datasets are added to specific locations

  • Data cataloging: Build custom dataset catalogs filtered by your criteria

  • Automated pipelines: Integrate dataset discovery into data processing workflows

Parameters

Parameter

Type

Required

Description

Default

q

string

No

Solr query string for full-text search

*:* (all datasets)

fq

string

No

Filter query to narrow results

None

rows

integer

No

Number of results to return

10

sort

string

No

Field to sort by (e.g., metadata_modified desc)

score desc, metadata_modified desc

facet.field

list

No

Fields to return facet counts for

None

See complete parameter support in CKAN API documentation and Solr query syntax.

Query Syntax

The q parameter accepts Solr query syntax:

  • Simple search: q=syr (searches all text fields)

  • Field-specific: q=title:returnees (searches only titles)

  • Boolean operators: q=water AND sanitation or q=water OR sanitation

  • Phrase search: q="humanitarian response plan" (exact phrase)

  • Wildcards: q=displace* (matches displacement, displaced, etc.)

Filter Query Examples

The fq parameter enables precise filtering:

Filter by organization: fq=organization:world-bank-group

Filter by country/location: fq=groups:uganda

Multiple filters (combine with AND): fq=organization:acaps AND groups:afghanistan

Filter by tags: fq=vocab_Topics:("climate-weather" OR "indicators")

Filter by dates: fq=last_modified:[2019-08-10T00:00:00.000Z%20TO%202020-08-10T00:00:00.000Z]

Key Response Fields

The package_search endpoint returns a structured response with metadata about the search results. Below are the key response fields but the list is not exhaustive:

  • count: Total number of datasets matching the search

  • results: Array of dataset objects (each with the same structure as package_show)

  • facets: Facet counts for the query (empty unless facet.field is specified)

  • search_facets: Detailed facet information including display names

  • Pagination fields: Use the start and rows parameters to paginate through results. The count field shows the total number of matching datasets.

Sample Truncated Response

Please note the following about the response structure:

  • count reflects the total number of matching datasets across all pages, not just the current page. Use the rows and start parameters to paginate through results. rows defaults to 10 and has a maximum value of 1000. start defaults to 0 and accepts any integer offset.

  • Each dataset result contains a nested resources array holding the actual downloadable files.

  • Countries are represented through the groups array using ISO3 codes (e.g., yem, sdn).

  • tags and vocabulary-based filter fields like vocab_Topics share the same vocabulary_id in the response, but they use different query syntax. See Filtering Query Examples section for more details.

Sample Queries

  1. Find recently updated datasets in a specific country

    1. https://data.humdata.org/api/3/action/package_search?fq=groups:afg&sort=metadata_modified desc&rows=10

  2. Search for datasets from a specific organization

    1. https://data.humdata.org/api/3/action/package_search?fq=organization:nrc&rows=20

  3. Find datasets with specific file formats

    1. https://data.humdata.org/api/3/action/package_search?fq=res_format:%22GeoJSON%22&rows=10

  4. Find which countries on HDX have population data

    1. https://data.humdata.org/api/3/action/package_search?q=population&rows=0&facet.field=["groups"]&facet.limit=250

  5. Paginate through a large result set

    1. https://data.humdata.org/api/3/action/package_search?fq=groups:afg&sort=metadata_modified desc&rows=10&start=10

  6. Search for datasets last modified within a time period for a specific organization

    1. https://data.humdata.org/api/action/package_search?q=*:*&fq=last_modified:[2019-08-10T00:00:00.000Z%20TO%202020-08-10T00:00:00.000Z]+AND+organization:wfp

Last updated

Was this helpful?