How to query HAPI

How to use 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, 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:

{
  "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 for ready-to-run pagination loops, and Troubleshooting and error handling for common pagination mistakes.