# 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

| **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](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` 
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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.