> For the complete documentation index, see [llms.txt](https://docs.humdata.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humdata.org/build/hdx-apis/metadata-endpoints/package_search.md).

# package\_search

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

<table data-header-hidden data-first-column-sticky><thead><tr><th></th><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Parameter</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Description</strong></td><td><strong>Default</strong></td></tr><tr><td>q</td><td>string</td><td>No</td><td>Solr query string for full-text search</td><td>*:* (all datasets)</td></tr><tr><td>fq</td><td>string</td><td>No</td><td>Filter query to narrow results</td><td>None</td></tr><tr><td>rows</td><td>integer</td><td>No</td><td>Number of results to return</td><td>10</td></tr><tr><td>sort</td><td>string</td><td>No</td><td>Field to sort by (e.g., metadata_modified desc)</td><td>score desc, metadata_modified desc</td></tr><tr><td>facet.field</td><td>list</td><td>No</td><td>Fields to return facet counts for</td><td>None</td></tr></tbody></table>

See complete parameter support in [CKAN API documentation](https://docs.ckan.org/en/2.9/api/) and [Solr query syntax](https://solr.apache.org/guide/query-syntax-and-parsing.html).

## 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

```json
{
  "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`&#x20;
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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.humdata.org/build/hdx-apis/metadata-endpoints/package_search.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.