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

{
  "success": true,
  "result": {
    "count": 1,
    "results": [
      {
        "id": "cb963915-d7d1-4ffa-90dc-31277e24406f",
        "title": "Global P-code List",
        "name": "global-pcodes",
        "notes": "CSV containing subnational p-codes, their corresponding administrative names, parent p-codes, and reference dates for the world (where available).",
        "state": "active",
        "archived": false,
        "private": false,
        "data_update_frequency": "30",
        "dataset_date": "[2015-06-15T00:00:00 TO 2026-02-16T23:59:59]",
        "last_modified": "2026-02-16T07:45:38.449605",
        "organization": {
          "id": "hdx",
          "name": "hdx",
          "title": "HDX"
        },
        "groups": [
          { "name": "world", "display_name": "World" }
        ],
        "tags": [
          { "name": "administrative boundaries-divisions" },
          { "name": "hxl" }
        ],
        "resources": [
          {
            "id": "71a63c2f-ba2f-4fef-8bf9-e4259dc41610",
            "name": "global_pcodes.csv",
            "format": "CSV",
            "download_url": "https://data.humdata.org/dataset/cb963915-d7d1-4ffa-90dc-31277e24406f/resource/71a63c2f-ba2f-4fef-8bf9-e4259dc41610/download/global_pcodes.csv",
            "size": 9964263,
            "last_modified": "2026-02-16T07:45:38.449027"
          }
          // ...more resources
        ]
      }
    ]
  }
}

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