> 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/hapi/how-to-query-hapi.md).

# How to query HAPI

### Get an app identifier

You do not need an HDX account to use HAPI, but every request must include an app identifier. This is a short string that encodes an application name and an email address. It is not a secret key and does not grant special permissions.

To generate one, use the Generate App Identifier section of the interactive docs at [hapi.humdata.org/docs](https://hapi.humdata.org/docshttps://hapi.humdata.org/docs), or call the encode endpoint with your application name and email:

`https://hapi.humdata.org/api/v2/encode_app_identifier?application={your_app_name}&email={your_email}`

The response contains your app identifier. Include it in every query, either as the query parameter app\_identifier, or as the request header `X-HDX-HAPI-APP-IDENTIFIER`.

### The base URL and themes

All HAPI requests use this base, followed by a theme path:

`https://hapi.humdata.org/api/v2/{theme}`

For example, to request operational presence data:

`https://hapi.humdata.org/api/v2/coordination-context/operational-presence`

### Common parameters

| `app_identifier` | \[Required] Identifies your application. Can also be sent as the header X-HDX-HAPI-APP-IDENTIFIER.                                                                                                              |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location_code`  | Filter by country using its ISO3 code, for example AFG. Not available on refugees-persons-of-concern or returnees, which use origin\_location\_code and asylum\_location\_code instead.                         |
| `admin_level`    | Filter results to a given administrative level. Not available on every sub-category: funding, national-risk, refugees-persons-of-concern and returnees have no admin filters, and poverty-rate has admin1 only. |
| `output_format`  | json (default) or csv                                                                                                                                                                                           |
| `limit`          | Maximum number of records to return per request. If no limit is set, a maximum of 10,000 records is returned.                                                                                                   |
| `offset`         | Starting index for the next page of results, zero-based                                                                                                                                                         |

Only app\_identifier, output\_format, limit and offset work on every sub-category. The location and admin filters do not, so check the API reference page before assuming one is available. Many sub-categories also accept their own filters. Operational presence, for example, accepts sector\_code, sector\_name, org\_acronym, and org\_name. See the API reference page for the filters available on each sub-category.

Note that filters on text fields are case insensitive and match as wildcards. For example, `location_name=Mali` will also return `Somalia`, because the text appears within it. Use codes such as `location_code` for exact matches.

### The response

By default HAPI returns JSON with your records inside a data array:

```json
{
  "data": [
{ },
{ }
  ]
}
```

To download the same query as a CSV file instead, add `output_format=csv`. Opening that URL in a browser downloads the file directly.

### Pagination

HAPI returns at most 10,000 records per call, so larger results must be retrieved in pages using limit and offset. Set a limit to control how many records you get per page, and increase offset by that amount for each page. The reliable way to retrieve a full dataset is to loop and stop when a page returns fewer records than your limit. 

See [Examples and use-cases](https://docs.humdata.org/build/hdx-apis/hapi/examples-and-use-cases) for ready-to-run pagination loops, and [Troubleshooting and error handling](https://docs.humdata.org/build/hdx-apis/hapi/troubleshooting-and-error-handling) for common pagination mistakes.


---

# 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/hapi/how-to-query-hapi.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.