# Humanitarian Data Exchange Documentation

HDX is a centralized data platform for humanitarians.

The Humanitarian Data Exchange (HDX) is an open platform for sharing humanitarian data. Our goal is to make data easy to find and use for analysis. This documentation is your guide to finding data, publishing data responsibly, and integrating HDX into your workflows through our tools and APIs.

### Navigate our documentation

We’ve organized the content into three main spaces to help you get the most out of HDX.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><h4><strong>Find data</strong></h4></td><td>Learn how to easily search, filter, preview, and download data on HDX.</td><td><a href="https://docs.humdata.org/find/">Find Data</a></td><td></td></tr><tr><td><h4><strong>Publish data</strong></h4></td><td>Step-by-step instructions for preparing, uploading, and maintaining data on HDX.</td><td><a href="https://docs.humdata.org/publish/">Publish Data</a></td><td></td></tr><tr><td><h4><strong>Build with HDX</strong></h4></td><td>Learn how to use our API, create data pipelines, and integrate HDX into your workflows.</td><td><a href="https://docs.humdata.org/build/">Build with HDX</a></td><td></td></tr></tbody></table>

Learn more [about HDX](/about/about-the-humanitarian-data-exchange).

### Need support?

Our team is here to support you. If you have questions, contact us at <hdx@un.org>.


# About the Humanitarian Data Exchange

Learn HDX works with humanitarian data.

The [Humanitarian Data Exchange](https://data.humdata.org/) (HDX) is an open platform for sharing data across crises and organizations. Launched in July 2014, the goal of HDX is to make humanitarian data easy to find and use. HDX has been accessed by millions of users in over 250 countries and territories and brings together more than 20,000 datasets from [hundreds of partners](https://data.humdata.org/organization).&#x20;

<div align="left" data-with-frame="true"><figure><img src="https://567372611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F058dN455791zvRCAbqvP%2Fuploads%2FzjHvWzwnyjdl1y5Ezymm%2Fhdx_dataset_downloads_2019_2025.png?alt=media&amp;token=94bf3d86-2fc3-40ab-8124-85a1845b47e5" alt="" width="563"><figcaption><p>HDX Dataset Downloads 2019-2025</p></figcaption></figure></div>

\
HDX is managed by the United Nations Office for Coordination of Humanitarian Affairs’ (OCHA) [Centre for Humanitarian Data](https://centre.humdata.org/?_gl=1*1u84lq0*_ga*ODMyMTMwODUuMTc0NDAyOTA2Nw..*_ga_E60ZNX2F68*czE3NTg4MTM1MjAkbzE2NCRnMSR0MTc1ODgxNDI0OCRqNjAkbDAkaDA.#), which is located in The Hague, the Netherlands. OCHA is responsible for coordinating humanitarian actors to ensure a coherent response to emergencies. The HDX team spans North America, Europe, Africa, the Middle East and Asia.

We define humanitarian data as:

* data about the context in which a humanitarian crisis is occurring
* data about the people affected by the crisis and their needs
* data about the response by organizations and people seeking to help those who need assistance<br>

Learn more about the impact of HDX [here](https://centre.humdata.org/category/impact-story/). A selection of stories are below:

* [How HDX and Sauti East Africa are Putting Data in People’s Hands](https://centre.humdata.org/how-hdx-and-sauti-east-africa-are-putting-data-in-peoples-hands/)
* [OCHA And Meta: Partnering To Give Humanitarians Open Access To Population Data](https://centre.humdata.org/ochas-partnership-with-meta-helps-find-people-in-need/)
* [HDX Signals: Alerting Humanitarians to Deteriorating Crises](https://centre.humdata.org/hdx-signals-alerting-humanitarians-to-deteriorating-crises/)


# Data Grids

A structured view of data availability across active humanitarian crises.

The Data Grids cover the majority of countries with a Humanitarian Needs and Response Plan (HNRP). They can be accessed via the [Data Grid overview](https://data.humdata.org/dashboards/overview-of-data-grids) or directly via the individual [location pages](https://data.humdata.org/group) (e.g. [Afghanistan](https://data.humdata.org/group/afg), [Yemen](https://data.humdata.org/group/yem)).

<div align="left" data-with-frame="true"><figure><img src="https://567372611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F058dN455791zvRCAbqvP%2Fuploads%2FM3LRt3q3z9vUdy4lrpUK%2FBF%20Data%20Grid%20less.png?alt=media&amp;token=a30a8711-18b6-4987-ba67-4c71ae4969ad" alt="" width="563"><figcaption><p>Burkina Faso Data Grid</p></figcaption></figure></div>

## Data in the Data Grids

The Data Grids place the most important crisis data into six categories: affected people; coordination and context; food security, nutrition and poverty; geography and infrastructure; health and education; and climate. Within each category, there are various sub-categories. For example, within the affected people category, there are sub-categories for internally displaced people, refugees, and returnees, among others.

The [Data Grid overview](https://data.humdata.org/dashboards/overview-of-data-grids) page provides a summary of data availability across contexts, while country specific datasets (such as population statistics, administrative boundaries, people in need, infrastructure, etc) can be accessed through the individual country pages.&#x20;

The Data Grids inform the yearly State of Open Humanitarian Data report published by the[ Centre for Humanitarian Data](https://centre.humdata.org/).&#x20;

## ‘Data availability’ measurement

In the Data Grids, ‘availability’ is presented as a percentage. This refers to the proportion of sub-categories in which data is available and up-to-date.&#x20;

<div align="left" data-with-frame="true"><figure><img src="https://567372611-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F058dN455791zvRCAbqvP%2Fuploads%2FVwdysnd7m92iHvyWmqRG%2FDG%20location%20data%20availability.png?alt=media&amp;token=a5e4ef2b-cfbc-496f-8d4c-3b48219907a6" alt="" width="563"><figcaption><p>Data Availability</p></figcaption></figure></div>

In the example above we can see that Burkina Faso's data grid availability is 58%. This means that 58% include data that is relevant, comprehensive and up to date. A further 37% of the categories include data that is available but not up to date and, for 5% subcategories, data is unavailable.

There are three criteria that determine whether a dataset is included in the data grids:

1. The dataset satisfies the sub-category definition (which can be accessed by hovering over the sub-category title)
2. The dataset is disaggregated beyond the national level&#x20;
3. The dataset uses common formats. &#x20;

When a dataset meets these three criteria, and is up to date, it is marked as ‘available and up to date’. If the dataset meets the  criteria, but is not up-to-date, then it will be marked as ‘not up-to-date’. If no relevant dataset is available for a sub-category, the sub-category is marked as 'unavailable'.

The dark blue indicates if the dataset is up to date. Light blue indicates if the dataset is not-up-to-date. Hovering on a 'not-up-to-date' dataset name will display comments about the limitations of the dataset, if available.

The grids include some datasets labeled as 'complementary.' These are included because they provide valuable context for understanding a context. They do not count toward the percentage of category availability.&#x20;

Where sub-categories are not relevant in a given country, they are marked as ‘not applicable’. Likewise, if data cannot be shared on HDX based on the data and information sensitivity classification outlined in the respective country’s Information Sharing Protocol (ISP), the sub-category will be as ‘not applicable’.&#x20;

## Data Grid category definitions

There are six data grid categories:&#x20;

1. **Affected People:** Data about the people affected by a crisis.
2. **Coordination & Context:** Core data relating to the coordination of humanitarian activities in a country or crisis and an understanding of the context in which humanitarian activities are taking place.
3. **Food Security, Nutrition & Poverty:** Data about a population’s access to food, key nutrition indicators and poverty rates.
4. **Geography & Infrastructure:** Data describing the administrative divisions as well as populated places and key physical geography and infrastructure.
5. **Health & Education:** Data describing health and education facilities.
6. **Climate:** Current and historical data about climate hazards and impact.

If you have feedback on the data grids, please reach out to the HDX team on <hdx@un.org>.<br>


# HDX Metadata

A reference for the dataset and resource fields available on HDX.

This page explains the main metadata fields available for download on each HDX dataset page. This is available in either JSON or CSV formats.

Metadata is data that defines and describes data. There are two types of metadata schemas used on HDX:

* **Dataset schema:** Describing the entire dataset. We define datasets on HDX as the main unit or container describing data on HDX.&#x20;
* **Resource schema:** Describing the resources within a dataset. A resource is a sub-container within a dataset. A resource can contain files such as a CSV file, Excel spreadsheet, or PDF document.

## Dataset Metadata Schema

<table data-header-hidden data-first-column-sticky><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Dataset ID</strong></td><td>Unique identification number for each dataset.</td><td>id</td><td>Text</td></tr><tr><td><strong>Title of Dataset</strong></td><td>Name of the dataset.</td><td>title</td><td>Text</td></tr><tr><td><strong>Dataset URL</strong></td><td>Dataset URL slug.</td><td>name</td><td>Text</td></tr><tr><td><strong>Description</strong></td><td>Description of the dataset.</td><td>notes</td><td>Text</td></tr><tr><td><strong>Source</strong></td><td>Entity that collected or generated the data.</td><td>dataset_source</td><td>Text</td></tr><tr><td><strong>Contributor</strong></td><td>Organization that published the dataset.</td><td>organization</td><td>Defined list. See full list of organizations on HDX here.</td></tr><tr><td><strong>Time period of the dataset</strong></td><td>Date or date range the data covers. If ongoing, the end date is set to the current date.</td><td>dataset_date</td><td>Date or date range</td></tr><tr><td><strong>Updated</strong></td><td>Date when the dataset was last modified on HDX.</td><td>last_modified</td><td>Date</td></tr><tr><td><strong>Expected update frequency</strong></td><td>How often the data is expected to be updated on HDX.</td><td>data_update_frequency</td><td><p>Defined list:</p><ul><li>-2: "As needed",</li><li>-1: "Never",</li><li>0: "Live",</li><li>1: "Daily",</li><li>2: "2 days",</li><li>7: "Weekly",</li><li>14: "2 weeks",</li><li>60: "2 months",</li><li>90: "3 months",</li><li>120: "4 months",</li><li>300: "10 months",</li><li>365: "Yearly",</li><li>730: "2 years"</li></ul></td></tr><tr><td><strong>Location</strong></td><td>Countries or areas the dataset relates to.</td><td>groups</td><td>Defined listSee full list of locations on HDX here</td></tr><tr><td><strong>License</strong></td><td>License governing reuse of the data.</td><td>license_title</td><td>Defined listSee full list of licenses used on HDX <a href="https://data.humdata.org/faqs/licenses">here</a>​</td></tr><tr><td><strong>Define license</strong></td><td>Full terms when a custom license is used.</td><td>license_other</td><td>Text</td></tr><tr><td><strong>Methodology</strong></td><td>How the data was collected (survey, registry, etc.).</td><td>methodology</td><td>Defined list</td></tr><tr><td><strong>Define methodology</strong></td><td>Details when "Other" methodology is selected.</td><td>methodology_other</td><td>Text</td></tr><tr><td><strong>Caveats/Comments</strong></td><td>Notes on data quality or limitations.</td><td>caveats</td><td>Text</td></tr><tr><td><strong>Tags</strong></td><td>Keywords for search and categorization.</td><td>tags</td><td>See full <a href="https://docs.google.com/spreadsheets/d/1fTO8T8ZVXU9eoh3EIrw490Z2pX7E59MhHmCvT_cXmNs/edit?usp=sharing">list of tags</a> on HDX​</td></tr></tbody></table>

## Resource Metadata Schema <a href="#resource-metadata-schema" id="resource-metadata-schema"></a>

A dataset can contain multiple resources and the resource’s position is reflected in each field name (e.g. resource\_1\_created).

<table data-header-hidden data-first-column-sticky><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Created</strong></td><td>Date when the resource was first created on HDX.</td><td>resource_X_created</td><td>Date</td></tr><tr><td><strong>Resource Description</strong></td><td>Short description of the resource’s contents.</td><td>resource_X_description</td><td>Text</td></tr><tr><td><strong>File Format</strong></td><td>File format of the individual resource.</td><td>resource_X_format</td><td>See full <a href="https://github.com/OCHA-DAP/hdx-ckan/blob/dev/ckanext-hdx_package/ckanext/hdx_package/config/resource_formats.json">list of formats supported</a> by HDX​</td></tr><tr><td><strong>Download URL</strong></td><td>URL to download the file from HDX.</td><td>resource_X_download_url</td><td>URL</td></tr><tr><td><strong>Resource ID</strong></td><td>Unique identification number for each resource on HDX.</td><td>resource_X_id</td><td>Text</td></tr><tr><td><strong>Updated</strong></td><td>Date when the resource was last modified on HDX.</td><td>resource_X_last_modified</td><td>Date</td></tr><tr><td><strong>Metadata Updated</strong></td><td>Date metadata for the resource was last modified on HDX.</td><td>resource_X_metadata_modified</td><td>Date</td></tr><tr><td><strong>Microdata</strong></td><td>Whether the resource contains microdata.</td><td>resource_X_microdata</td><td><p>Defined list:</p><ul><li>FALSE</li><li>TRUE</li></ul></td></tr><tr><td><strong>Dataset ID</strong></td><td>ID of the dataset this resource belongs to.</td><td>resource_X_dataset_id</td><td>Text</td></tr><tr><td><strong>Resource Type</strong></td><td>Indicates whether a file has been uploaded directly to HDX's servers or is a link to data stored elsewhere.</td><td>resource_X_resource_type</td><td><p>Defined list:</p><ul><li>file.upload</li></ul></td></tr><tr><td><strong>Resource Name</strong></td><td>Resource title shown on HDX.</td><td>resource_X_name</td><td>Text</td></tr><tr><td><strong>MIME type</strong></td><td>Media type of the resource file.</td><td>resource_X_mimetype</td><td>Text</td></tr><tr><td><strong>Size</strong></td><td>Size of the resource in kilobytes (KB) or megabytes (MB). For files that aren’t hosted on HDX, this may not always be available.</td><td>resource_X_size</td><td>Text</td></tr></tbody></table>

<br>


# HDX Signals

HDX Signals monitors key datasets and generates automated emails when significant, negative changes are detected. Signals are identified for given datasets and locations.

Over 200 locations are monitored, with coverage varying depending on the dataset. The following table details the number of locations covered by each dataset:

| Datasets                               | Number of locations |
| -------------------------------------- | ------------------- |
| Agricultural hotspots                  | 81                  |
| Conflict events                        | 188                 |
| Food insecurity                        | 52                  |
| INFORM Severity Index                  | 191                 |
| Internal conflict-driven displacements | 82                  |
| Internal disaster-driven displacements | 199                 |
| Market monitoring                      | 80                  |

We use a thresholds approach to identify when a signal should be created in a given dataset. The specific methodology for each dataset is detailed in the "Datasets" section of this site. We only send a signal if it has been detected in the past sixty days and if no identical signal was detected in the past six months.


# Datasets

This section contains an overview of all datasets scanned by HDX Signals. Each page described the dataset itself, overall methodology for detecting signals in the source data, and guidelines for interpreting output signals.&#x20;


# Agricultural hotspots

Signals are sent when the hotspot classification for a location increases.

## Source

We monitor [Anomaly Hotspots of Agricultural Production (ASAP)](https://agricultural-production-hotspots.ec.europa.eu) data produced by the Joint Research Centre. ASAP is an online decision support system for early warning about hotspots of agricultural production anomaly (crop and rangeland), developed for food security crises prevention and response.

The ASAP system produces automatic warnings at a subnational level, using a range of remote sensing and earth observation data to monitor agricultural conditions. These subnational warnings are converted into national level hotspots analyses by a team of analysts. Each location is classified as `No hotspot`, `Hotspot`, or `Major hotspot`.&#x20;

These classifications are produced on a monthly basis, covering a set of locations at risk of food insecurity. Read more about the ASAP methods in their [documentation](https://agricultural-production-hotspots.ec.europa.eu/documentation.php).

Access ASAP data directly on [HDX](https://data.humdata.org/dataset/asap-hotspots-monthly) and find additional datasets and context on the [ASAP website.](https://agricultural-production-hotspots.ec.europa.eu/download.php)

## Signals detection

Signals are sent when new agricultural hotspots are identified. This occurs when a location is classified as a `Hotspot` but was `No hotspot` in the previous month, or is now `Major hotspot` and was either `Hotspot` or `No hotspot` in the previous month.

#### Examples

Below are historical examples that show how signals are generated with ASAP data.

[Sudan](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=10b16f9587#SDN): classified as `Hotspot` in April 2023 and then classified as a `Major hotspot` in May 2023.&#x20;

[Mozambique](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=dab7a5f66c#MOZ): classified as `No hotspot` in December 2020, but `Hotspot` in January 2021.


# Armed conflict

Signals are sent when monthly conflict levels reach levels not seen in the past one to three years.

## Source

We monitor [Armed Conflict Location & Event Data Project (ACLED)](https://acleddata.com) data. ACLED data contains dates, actors, locations, fatalities, and types of all reported political violence and protest events in more than [200 locations in real time](https://acleddata.com/download/4404/). You can access aggregated ACLED data directly on [HDX](https://data.humdata.org/organization/acled?) and get full, disaggregated data through the [ACLED data and tools](https://acleddata.com/data/).

## Signals detection

We transform ACLED event datasets into a time series of armed conflict and fatalities, and calculate monthly fatalities as the rolling sum of fatalities across the past 30 days. Signals are generated whenever monthly fatalities reaches levels not seen in the past one or three years. Signals are not generated if monthly fatalities are below the minimum threshold of 100.

## Mapping

ACLED occasionally reports conflicts at sea, which would require more detailed maps to visualize, including neighboring countries and bodies of water. To keep the visualizations clear and simple, points lying outside the base administrative boundary map are removed during the mapping process.

#### Examples

Below are historical examples that show how signals are generated with ACLED data.

[Myanmar](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=3b6173e87a): in February 2021, monthly fatalities reached 169, higher than any time in the past year.

[South Sudan](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=171a61325b): in June 2022, monthly fatalities reached 527, a level not seen since early 2019.


# Food insecurity

Signals are sent when food insecurity is estimated or projected to increase in a new IPC analysis.

## Source

We monitor[ Integrated Food Security Phase Classification (IPC) ](https://www.ipcinfo.org)and [Cadre Harmonisé (CH)](http://cadreharmonise.org) data on acute food insecurity.  IPC/CH data estimate the levels of acute food insecurity in locations, estimating the number and percent of populations that fall into [five phases](https://www.ipcinfo.org/ipcinfo-website/ipc-overview-and-classification-system/ipc-acute-food-insecurity-classification/en/):

1. Minimal/None
2. Stressed
3. Crisis
4. Emergency
5. Catastrophe/Famine

IPC/CH analyses produce current estimates of populations in these phases, as well as future projections on how food insecurity will involve in the coming months. At the subnational level, individual areas are given a phase classification on the same phase scale, which can be used  to [map food insecurity](https://www.ipcinfo.org/ipc-country-analysis/ipc-mapping-tool/). You can access IPC/CH data directly on [HDX](https://data.humdata.org/dataset/global-acute-food-insecurity-country-data) or retrieve the data from their [API](https://www.ipcinfo.org/ipc-country-analysis/api/) and explore latest analyses on their [website](https://www.ipcinfo.org/ipc-country-analysis/en/).

## Signals detection

We generate signals on IPC/CH data when the most recent analyses show an increase in populations in phase 3 and above, comparing the current estimates to the previous analysis and the projections to the current.&#x20;

There are a series of thresholds to ensure signals are only generated if the food insecurity situation reaches a minimum level of severity. Signals are only generated if 20% or more of the population is in phase 3 and above in the current or projected estimates, or if 5% or more of the population is in phase 4 and above. This follows the [20% rule in area phase classification](https://www.ipcinfo.org/ipc-manual-interactive/ipc-acute-food-insecurity-protocols/function-2-classify-severity-and-identify-key-drivers/protocol-23-adhere-to-analytical-parameters/en/).

A signal is automatically generated if there are any populations estimated to be in catastrophic/famine conditions (phase 5), regardless of whether this is an increase from previous analyses.

#### Partial analyses

In some locations, IPC/CH analyses do not cover the entire population or all subnational areas. This can make it difficult to draw comparisons across time. To deal with this, for each IPC/CH analysis, we calculate the percent of the total population covered in that analysis and attempt to detect from the analysis title if it is a partial analysis for a specific subnational area. For example, for the analysis `Madagascar - Acute Food Insecurity Nov 2022 (Grand Sud/Est)` we estimate the coverage is partial, covering only Grand Sud/Est.

When generating signals, we only make comparisons to the previous analysis if we believe that previous analysis covers a similar population. This is done by checking if there is an indication of partial coverage in the title and the percent of population analyzed differs by less than 10%, based on[ IPC/CH standards](https://www.fsinplatform.org/report/global-report-food-crises-2024/#download). If they are not comparable, then we do not compare with the previous current estimates, and only compare current and projected estimates from the analysis.

#### Examples

Below are historical examples that show how signals are generated with IPC/CH data.

[Madagascar](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=1f4d296ccd#MDG): new IPC analysis in early 2022 projected increases in populations in phase 3 and above for Grand Sud/Est.

[South Sudan](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=abf8af12bf#SSD): populations estimated to be in phase 5 triggered an immediate signal.


# INFORM Severity Index

Signals are sent when the national level INFORM Severity Index is above 3 and exceeds the highest value recorded in the past 12 months.

## Source

We monitor the [INFORM Severity Index (ACAPS)](https://www.acaps.org/en/thematics/all-topics/inform-severity-index) data. The INFORM Severity Index is a composite indicator designed to measure the severity of humanitarian crises globally, against a common scale. It aggregates data from various sources to categorise all crises into five levels of severity:

* **Level 5:** Extreme humanitarian conditions. People are facing extreme shortages or availability and accessibility problems in regards to basic services.
* **Level 4:** Severe humanitarian conditions. People are facing significant shortages and/or significant availability and accessibility problems in regards to basic services.
* **Level 3:** Moderate humanitarian conditions. People are facing shortages and/or availability and accessibility problems in regards to basic services but they are not life-threatening.
* **Level 2:** Stressed humanitarian conditions. People are facing some shortages or/and some availability and accessibility problems in regards to basic services.
* **Level 1:** None/Minor humanitarian conditions. People are facing none or minor shortages or/and accessibility problems regarding basic services.

People with identified humanitarian needs are included in levels 3–5, depending on the severity of their needs.

You can access ACAPS data directly on [HDX](https://data.humdata.org/organization/acaps) and find additional datasets and context on the [ACAPS website](https://www.acaps.org/en/).

## Signals detection

The INFORM Severity Index is calculated for each crisis covered. In order to generate Signals at the country level, we aggregate crisis-level data to the national level. Signals are sent when the national level INFORM Severity Index is above 3 and exceeds the highest value recorded in the past 12 months.

#### Examples

Below are historical examples that show how signals are generated using the INFORM Severity Index:\
[Nigeria](http://eepurl.com/jaCrHc#NGA): In January 2025, the INFORM Severity Index reached 4, a value higher than any time in the previous year.\
[Malawi](http://eepurl.com/jaCrtg#MWI): In May 2024, the INFORM severity index reached 3.6, the highest value in the previous year.


# Internal displacements

Signals are sent when monthly displacements reach levels not seen in the past one to three years.

## Source

We monitor the [Internal Displacement Monitoring Centre's (IDMC) ](https://www.internal-displacement.org/)event data on conflict and disaster-driven population flows. Access IDMC data directly on [HDX](https://data.humdata.org/organization/international-displacement-monitoring-centre-idmc) and find additional datasets and context on the [IDMC website](https://www.internal-displacement.org/).

## Signals detection

We first remove duplicated event databased on event ID. If multiple entries for a single event ID, then only the recommended figures are kept if available. If unavailable, then the latest data updated into the IDU is kept based on the `created_at` date. We then transform this IDMC event data into a time series and calculate monthly displacements as the rolling sum of displacements across the past 30 days.

For some countries, we only consider reported events from a certain date when we are confident in consistent coverage. This is because the IDMC IDU has uncertain temporal coverage. This temporary fix will be removed once the IDMC provides metadata indicating the start date for coverage for each country. You can find the dates we use in [this table](https://github.com/OCHA-DAP/hdx-signals/blob/main/docs/datasets/displacement-dates.md).

Signals are generated whenever monthly displacements reach levels not seen in the past one or three years. Given the significant differences in conflict and natural disaster displacement, signals are generated separately for each type. Signals are not generated if monthly fatalities are below the minimum threshold of 5,000 (conflict-driven) and 50,000 (disaster-driven).

#### Examples

[Philippines](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=edd0633c44): Approximately 45,000 conflict-driven displacements were reported from February to March 2021.

[Congo](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=ee643f5da7): Floods in late 2023 causes large-scale displacement.


# Market monitoring

Signals are sent when month-to-month price increases reach a newly high level not seen in previous months.

## Source

The World Food Programme (WFP) produces a [Global Market Monitor dataset](https://www.wfp.org/publications/market-monitor) that monitors food prices in markets across a range of countries globally. The Global Market Monitor provides information on price changes for the most commonly consumed staples and their potential impacts on the cost of a basic food basket. For more details, please refer to the 'Methodology & Data' page at this [link](https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdataviz.vam.wfp.org%2Freports%2Fglobal-coverage-global-market-monitor-mar-2024%3F_ga%3D2.216546710.1452952701.1719219215-2028703503.1710344334\&data=05%7C02%7Cseth.caldwell%40un.org%7C0263c631cc444c1fb32808dc95e733b0%7C0f9e35db544f4f60bdcc5ea416e6dc70%7C0%7C0%7C638550067449484289%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C\&sdata=%2B3wl7Pg0Cs6Z%2Fhb8%2FzE5hDdXV6dRDbhe%2BEqzzImWYMk%3D\&reserved=0). The Global Market Monitor follows a standardized methodology to calculate the impacts of price changes on the cost of a basic food basket for cross-country comparability. Global Market Monitor figures might differ from those presented in local market monitoring reports.

Subnational price data from a range of markets on core food basket items are aggregated to produce a national-level cost of food basket dataset.

Data is aggregated monthly, and when comparisons are able to be made with the previous month, the % price change at the national level is reported and classified. The change is classified as high if month-to-month changes is between 10 - 25% and severe if > 25%.

Access the data directly on [HDX](https://data.humdata.org/dataset/global-market-monitor) and find additional datasets and context on the [WFP website](https://www.wfp.org/publications/market-monitor).&#x20;

## Signals detection

We generate signals if we detect month-to-month change in a location classifed as high or severe and the previous month-to-month change was at a lower classification.

#### Examples:

[Libya](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=2fac00caa6#LBY): high change int he cost of hte food basket detected in early 2021.

[Syrian Arab Republic](https://us14.campaign-archive.com/?e=0c9936e61d\&u=ea3f905d50ea939780139789d\&id=bcb44b460e): severe change in the cost of the food basket detected in mid-2023.


# Prompts

For datasets where text information is publicly available, OpenAI's [GPT-5 large language model](https://openai.com/index/introducing-gpt-5/) is used to generate summary content for signals, to provide additional context to the quantitative data and visualizations generated by the system. Publicly available text data from primary datasets and linked secondary sources is aggregated and passed to GPT-5 to produce key headlines (short summaries) and situation summaries (long summaries) for each signal.

Refer to the `src/indicators` source code to see what information is passed to the AI for summarization. Below you can find the prompts passed to GPT-5 to generate the summary text.

* [acaps\_inform\_severity](#acaps_inform_severity)
* [acled\_conflict](#acled_conflict)
* [idmc\_displacement](#idmc_displacement)
* [ipc\_food\_insecurity](#ipc_food_insecurity)
* [jrc\_agricultural\_hotspots](#jrc_agricultural_hotspots)

### acaps\_inform\_severity <a href="#acaps_inform_severity" id="acaps_inform_severity"></a>

#### long.txt

> In three sentences or less, please summarize the main risks for each country. Here are four rules:
>
> * Avoid providing specific numbers or dates.
> * Only use the information provided to you. If the information is limited, keep the summarization brief.
> * Focus on summarizing the situation
> * If the "date request" is specified, filter out all the information after that date.
>
> Here is the information -->

#### short.txt

> Please condense the following information into a single 10 word line, similar to text you might see on a news ticker. Outputs could look like the following 2 examples: 'Gang violence escalates crises: insecurity, displacement, migration surge imminent' or 'Complex crisis worsens: conflict, natural disasters, bans, and instability surge'.
>
> Do not include the country name in the output. For example, this output is invalid: 'INFORM Severity index increases in Burkina Faso"
>
> Expect the reader to have no context, but this is intended to capture their attention, so keep the messaging simple, clear and punchy. Use only the information below in your summary -->

#### system.txt

> You are a neutral assistant.

### acled\_conflict <a href="#acled_conflict" id="acled_conflict"></a>

#### long.txt

> In three sentences or less, please summarize the main reasons and locations for the reported events of armed conflict, protests, or riots. Here are three rules:
>
> * Avoid providing specific numbers or dates.
> * Only use the information provided to you. If the information is limited, keep the summarization brief.
> * Focus on summarizing the reasons and locations.
>
> Here is the information -->

#### short.txt

> Please condense the following information into a single 10 word line, similar to text you might see on a news ticker. Outputs could look like the following 2 examples: 'Conflict between agropasturalists surges in the northwest' or 'Military offensive in the south sees surge in fatalities'.
>
> Do not include the country name in the output. For example, this output is invalid: 'Insecurity rises in Afghanistan, driven by separatist armed groups'
>
> Expect the reader to have no context, but this is intended to capture their attention, so keep the messaging simple, clear and punchy. Use only the information below in your summary -->

#### system.txt

> You are a neutral assistant.

### idmc\_displacement <a href="#idmc_displacement" id="idmc_displacement"></a>

#### long.txt

> In three sentences or less, please summarize the main reasons for and locations of displacement reported in the following text. The information is a summary of displacement events. In some cases, you will also be provided raw text extracted from PDF documents that were the original source for the reports. They may not be in the English language, even though the overall summary is in English. Here are three rules:
>
> * Maintain strict neutrality: do not express opinions, assign responsibility, attribute blame, justify actions, or use evaluative or emotive language related to any party in a conflict. Do not include specific numbers or dates.
> * Only use the information provided to you. If the information is limited, keep the summarization brief.
> * The output should be in the English language.
>
> Here is the information -->

#### short.txt

> Please condense the following information into a single 10 word line, similar to text you might see on a news ticker. Outputs could look like the following 2 examples:
>
> 'Armed attacks in the capital force residents to flee to the countryside' or 'Instability due to gang activity drives displacement across the country'.
>
> Do not include the country name in the output. This output is invalid: 'Riverine floods in Burkina Faso destroys homes, displaces communities'
>
> Expect the reader to have no context, but this is intended to capture their attention, so keep the messaging simple, clear and punchy. Use only the information below in your summary -->

#### system.txt

> You are a neutral assistant.

### ipc\_food\_insecurity <a href="#ipc_food_insecurity" id="ipc_food_insecurity"></a>

#### ch\_recs.txt

> In three sentences or fewer, please summarize the recommended actions to address food security in {location} based on a document that will be provided. Expect the reader to be familiar with the terminology and general context, but wants to know exactly what is recommended based on information provided in the following text. Here are four rules rules:
>
> * There are a lot of random numbers in the text because the text was scraped from a PDF with tables, so please just focus on context, not specific numbers.
> * Only use the information provided to you in the document.
> * The document is written about multiple countries, but I only want actions recommended for {location}. If there are limited recommendations about {location}, keep your output concise.
> * The document is written in French, but the output should be in the English language.
>
> Here is the document -->

#### ch\_sit\_rep.txt

> In three sentences or fewer, please summarize the food security situation in {location} based on a document that will be provided. Expect the reader to be familiar with the terminology and general context, but wants to know exactly what is happening based on information provided in the text. Here are four rules:
>
> * There are a lot of random numbers in the text because the text was scraped from a PDF with tables, so please just focus on explanation, not figures.
> * Avoid discussing recommended actions, only discuss the overall situation.
> * Only use the information provided to you in the document.
> * The document is written about multiple countries, but I only want information about {location}. If there is limited information about {location}, keep your output concise.
> * The document is written in French, but the output should be in the English language.
>
> Here is the document -->

#### ipc\_recs.txt

> In three sentences or fewer, please summarize the key recommendations to address the food security situation. Expect the reader to be familiar with the terminology and general context, but wants to know exactly what is recommended. Here are two rules:
>
> * Avoid providing specific numbers, just provide a general overview of recommendations and other key qualitative information.
> * Only use the information provided to you.
>
> Here is the information -->

#### ipc\_sit\_rep.txt

> In three sentences or fewer, please summarize the current food insecurity situation. Expect the reader to be familiar with the terminology and general context, but wants to know exactly what is happening based on information provided. Here are two rules:
>
> * Avoid providing recommended actions, instead focus on the general situational overview and other key information provided.
> * Only use the information provided to you.
>
> Here is the information -->

#### short.txt

> Please condense the following information into a single 10 word line, similar to text you might see on a news ticker. Outputs could look like the following 2 examples:
>
> 'Food insecurity in the capital worsens following failed rainy season' or 'Seasonal forecasts indicate deteriorating food security in the northwest'.
>
> Do not include the country name in the output. This output is invalid: 'Burkina Faso projected to experience worsening food insecurity due to conflict, flooding'.
>
> Expect the reader to have no context, but this is intended to capture their attention, so keep the messaging simple, clear and punchy. Use only the information below in your summary: -->

#### system.txt

> You are a neutral assistant.

### jrc\_agricultural\_hotspots <a href="#jrc_agricultural_hotspots" id="jrc_agricultural_hotspots"></a>

#### long.txt

> Below, we will provide you information on crop-related drought conditions over a period of time up to 6 months. Data is presented with the earliest information first, formatted as 'Month 1: (information)\n Month 2: (information)' and so forth. We are most interested in conditions in the latest month presented, which will come last. Here are two rules:
>
> * Please summarize the situation now, using information from previous months to contextualize the recent past in the country.
> * Only use the information provided to you. If the information is limited, keep the summarization brief.
> * Do not include formatting in the output. Keep the output limited to one paragraph.
>
> Here is the information for summarization -->

#### short.txt

> Please condense the following information into a single 10 word line, similar to text you might see on a news ticker. Outputs could look like the following 2 examples: 'Tropical storm threatens crop harvest, exacerbating socio-economic driven food insecurity' or 'Rainfall patterns have improved, but poor vegetation conditions continue in the south'.
>
> Do not include the country name in the output. This output is invalid: 'Long-term drought conditions persists in South Sudan'
>
> Expect the reader to have no context, but this is intended to capture their attention, so keep the messaging simple, clear and punchy.
>
> Only use the following information in your summary -->

#### system.txt

> You are a neutral assistant.


# Data Licenses&#x20;

The licenses under which data can be shared on HDX.

**HDX promotes the use of licenses developed by the** [**Creative Commons Foundation**](http://creativecommons.org/) **and the** [**Open Data Foundation**](http://opendatacommons.org/)**. The main difference between the two classes of licenses is that the Creative Commons licenses were developed for sharing creative works in general, while the Open Data Commons licenses were developed more specifically for sharing databases.**

You can share your data on HDX under one of the following Creative Commons licenses. Note: If you would like us to include other license options for data shared through HDX, please send us an email with your request at <hdx@un.org>.

<details>

<summary><strong>Creative Commons Attribution for Intergovernmental Organisations (CC BY-IGO)</strong></summary>

Under the CC BY-IGO license, you are free to share (copy and redistribute the material in any medium or format) and or adapt (remix, transform, and build upon the material) for any purpose, even commercially. The licensor cannot revoke these freedoms as long as you follow the license terms. The license terms are that you must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. Additionally, you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. When the Licensor is an intergovernmental organization, disputes will be resolved by mediation and arbitration unless otherwise agreed.

\[more information: [deed](https://creativecommons.org/licenses/by/3.0/igo/) | [license](https://creativecommons.org/licenses/by/3.0/igo/legalcode)]

</details>

<details>

<summary><strong>Creative Commons Attribution International (CC BY)</strong></summary>

Under the CC BY license, you are free to share (copy and redistribute the material in any medium or format) and or adapt (remix, transform, and build upon the material) for any purpose, even commercially. The licensor cannot revoke these freedoms as long as you follow the license terms. The license terms are that you must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. Additionally, you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

\[more information: [deed](https://creativecommons.org/licenses/by/4.0/) | [license](https://creativecommons.org/licenses/by/4.0/legalcode)]

</details>

<details>

<summary><strong>Creative Commons Attribution-ShareAlike (CC BY-SA)</strong></summary>

Under the CC BY-SA license, you are free to share (copy and redistribute the material in any medium or format) and or adapt (remix, transform, and build upon the material) for any purpose, even commercially. The licensor cannot revoke these freedoms as long as you follow the license terms. The license terms are that you must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. Additionally, you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

\[more information: [deed](https://creativecommons.org/licenses/by-sa/4.0/) | [license](https://creativecommons.org/licenses/by-sa/4.0/legalcode)]

</details>

<details>

<summary><strong>Open Database License (ODC-ODbL)</strong></summary>

Under the ODC-ODbL license, you are free:

* To Share: To copy, distribute and use the database.
* To Create: To produce works from the database.
* To Adapt: To modify, transform and build upon the database.

As long as you:

* Attribute: You must attribute any public use of the database, or works produced from the database, in the manner specified in the ODbL. For any use or redistribution of the database, or works produced from it, you must make clear to others the license of the database and keep intact any notices on the original database.
* Share-Alike: If you publicly use any adapted version of this database, or works produced from an adapted database, you must also offer that adapted database under the ODbL.
* Keep open: If you redistribute the database, or an adapted version of it, then you may use technological measures that restrict the work (such as DRM) as long as you also redistribute a version without such measures.

\[more information: [deed](https://opendatacommons.org/licenses/odbl/summary/) | [license](https://opendatacommons.org/licenses/odbl/1-0/)]

</details>

<details>

<summary><strong>Open Data Commons Attribution License (ODC-BY)</strong></summary>

Under the ODC-BY license, you are free:

* To Share: To copy, distribute and use the database.
* To Create: To produce works from the database.
* To Adapt: To modify, transform and build upon the database.

As long as you:

* Attribute: You must attribute any public use of the database, or works produced from the database, in the manner specified in the license. For any use or redistribution of the database, or works produced from it, you must make clear to others the license of the database and keep intact any notices on the original database.

\[more information: [deed](https://opendatacommons.org/licenses/by/summary/) | [license](https://opendatacommons.org/licenses/by/1-0/)]

</details>

<details>

<summary><strong>Open Data Commons Public Domain Dedication and License (PDDL)</strong></summary>

Under the ODC-PDDL license, You are free:

* To Share: To copy, distribute and use the database.
* To Create: To produce works from the database.
* To Adapt: To modify, transform and build upon the database.

As long as you:

* Blank: This section is intentionally left blank. The PDDL imposes no restrictions on your use of the PDDL licensed database.

\[more information: [deed](https://opendatacommons.org/licenses/pddl/summary/) | [license](https://opendatacommons.org/licenses/pddl/1-0/)]

</details>

<details>

<summary><strong>Public Domain/No restrictions (CC0)</strong></summary>

Under the terms of this license you are free to use the material for any purpose without any restrictions.

\[more information: [deed](https://creativecommons.org/publicdomain/zero/1.0/) | [license](https://creativecommons.org/publicdomain/zero/1.0/legalcode)]

</details>

<details>

<summary><strong>Multiple Licenses</strong></summary>

The dataset contains data having different licenses or terms of use. The details of these licenses or terms of use should be listed in the file.

</details>

<details>

<summary><strong>Other</strong></summary>

Any other license or terms of use which are listed in the description of the dataset, or in the metadata fields of the dataset, or any other place in the dataset such as a specific license or terms of use file that is included as part of the dataset files.

</details>


# HDX Terms of Service

How HDX is managed and what is expected of organizations and users.

**The** [**Humanitarian Data Exchange**](https://data.humdata.org/) **(HDX) is an open data platform managed by the** [**United Nations Office for the Coordination of Humanitarian Affairs**](https://www.unocha.org/) **(OCHA) through its** [**Centre for Humanitarian Data**](https://centre.humdata.org/) **(the Centre). These Terms of Service (hereafter ‘Terms’ or ‘these Terms’) describe how HDX is managed and how the platform should be used. OCHA will update these Terms as needed, and will post notice of significant updates on HDX and through the HDX mailing list. HDX organizations and users are bound by these Terms. If you do not agree with the Terms, you should discontinue use of HDX. If you have any questions or comments about these Terms or HDX, send an email to** [**hdx@un.org**](mailto:hdx@un.org)**.**

### Account Management <a href="#docs-internal-guid-cbcd1a94-7fff-efb5-2a39-bea5aa8e574a" id="docs-internal-guid-cbcd1a94-7fff-efb5-2a39-bea5aa8e574a"></a>

1. User account. HDX is an open platform and anyone can use it without creating a user account. Signing up with HDX gives users access to additional features such as the ability to receive notifications about data; joining an organization as a member, editor or admin; and requesting access to data shared via HDX Connect, among other benefits.
2. Organization account. Data can only be shared on HDX by approved organizations. Organizations can represent a formal legal entity such as a non-governmental organization, or an informal collective such as an information management working group. OCHA reviews requests to create an organization account to: (1) verify the identity of the requester and (2) determine whether the data that will be shared meets the requirements set out in the DATA SCOPE AND CRITERIA section below.
3. You may ask OCHA to delete your user or organization account at any time. OCHA will delete all datasets shared by an organization before deleting the organization account. When a user or organization account is deleted, OCHA will delete any personal data we collected in order to create the account.
4. OCHA routinely reviews organization accounts to verify that they are still active. Accounts that have been inactive for over a year will be marked as closed but not deleted. Closed accounts will not appear in the list of organizations on HDX. Closed accounts can be reactivated if the organization contacts OCHA with a request to contribute data. OCHA will always contact organization administrators to verify inactivity prior to closure.
5. When an organization account with datasets on HDX is marked as closed, OCHA adds a bot as the organization administrator, demotes all administrators and editors to members and archives the data. The closed organization’s archived datasets can still be found through the search function and downloaded. If a closed organization has private datasets, OCHA will contact the organization to arrange transfer of the data and remove the private data from HDX. OCHA will not delete the closed organization unless a member of the closed organization requests OCHA to do so following clause 3.

### Data Scope and Criteria <a href="#docs-internal-guid-a87c82f0-7fff-30e0-319f-f3a5bf967b63" id="docs-internal-guid-a87c82f0-7fff-30e0-319f-f3a5bf967b63"></a>

6. There are three categories of humanitarian data which may be shared on HDX:\
   \
   (a) Data about the context in which a humanitarian crisis is occurring (e.g., administrative  boundaries, locations of schools, health facilities and other physical infrastructure, and baseline socio-economic indicators).\
   \
   (b) Data about the people affected by the crisis and their needs (e.g., needs assessment data, movement data and locations of affected people).\
   \
   (c) Data about the response by organizations seeking to help those who need assistance (e.g., who-is-doing-what-where, community perception surveys, and funding levels).<br>
7. All data shared publicly or privately on HDX must meet the following criteria:\
   \
   (a) Datasets may not contain any personal data. Personal data is information, in any form, that relates to an identified or identifiable natural person. An exception is made for aid worker contact details, which may be shared within a private dataset if those aid workers have provided consent.\
   \
   (b) Datasets may not contain any sensitive non-personal data. Sensitive non-personal data is data that, while not relating to an identified or identifiable natural person, may, by reason of its sensitive context, put certain individuals or groups of individuals at risk of harm.\
   \
   (c) Data must have been collected in a fair and legitimate manner with a defined purpose and in line with principles of necessity and proportionality.\
   \
   (d) Data must be shared in a supported data format. HDX supports [all common data formats](https://github.com/OCHA-DAP/hdx-ckan/blob/dev/ckanext-hdx_package/ckanext/hdx_package/config/resource_formats.json) and offers built-in preview support for CSV, TXT, XLS, and JSON formats. Map previews are possible from geographic data in zipped shapefile, KML and GeoJSON formats.<br>
8. Organizations should keep their data on HDX up-to-date in order to present the latest available information.

### Sharing Data

9. There are three ways to share data on HDX:\
   \
   (a) Public: Data is accessible to anyone who visits HDX, whether or not they are a registered user\
   \
   (b) Private: Data is accessible only to registered users who are members of the organization that uploaded the data on HDX.\
   \
   (c) HDX Connect: The metadata of a dataset is available and the contributing organization can decide whether or not to share the dataset when requested by a registered user.<br>
10. Organizations must specify an appropriate license for all data they share publicly. Organizations are free to choose the license for their data. We have suggested some options [here](https://data.humdata.org/about/license).&#x20;
11. Organizations may use HDX to share data from other sources if the applicable license allows for onward sharing.&#x20;
12. After downloading a public dataset, users must follow the applicable license when using and sharing the data.&#x20;
13. Organizations may use the HDX Connect feature to direct users to data hosted outside of HDX. In such cases, organizations should link directly to the specific dataset described on HDX and not to a more general landing page of an external platform.
14. When an organization grants access to data requested via HDX Connect, the data does not pass through the HDX infrastructure.

### Data Review

15. In order to ensure data quality and to prevent any sensitive data from being exposed through HDX, OCHA reviews datasets that are shared publicly on the platform. This review consists of:\
    \
    (a) An automated scan for sensitive data using one or multiple Large Language Models (LLMs). Any data used for automated scanning remains on UN Secretariat servers in the United States of America and is not exposed to third parties or used for training any public LLM. \
    \
    (b) A manual review by an HDX team member based on a [quality assurance checklist](https://data.humdata.org/dataset/2048a947-5714-4220-905b-e662cbcd14c8/resource/658d5c4f-1680-4cb5-9fbf-10a0a64e2c39/download/hdx-qa-checklist.pdf), which includes the completeness of metadata, the relevance of the data to humanitarian action, the integrity of the data resources, and the absence of any sensitive data, among other criteria.\
    \
    OCHA reserves the right to review datasets shared privately on HDX to verify the private datasets comply with these Terms.
16. If the review under clause 15 shows that a resource contains microdata, personal data, or non-personal sensitive data, the resource is placed ‘under review’. While a resource is  ‘under review’, users are only able to view the dataset page including metadata provided by the contributor, and are not able to download the resource. If a resource has been ‘under review’ for more than one month with no response from the contributor, OCHA will make the resource private. After another month with no response, OCHA will delete the resource.
17. For microdata such as household survey results, OCHA runs a disclosure risk assessment to assess the risk of reidentification of individuals. All resources labeled as ‘microdata’ by the contributing organization at the point of upload are automatically placed ‘under review’. The resource will remain ‘under review’ until OCHA determines that the resource can be shared responsibly, either publicly, privately with users that are members of the contributing organization, or on request via HDX Connect. More information about this process is available [here](https://humanitarian.atlassian.net/wiki/spaces/HDXKB/pages/1381498881/Statistical+Disclosure+Control+on+HDX).&#x20;
18. If a user notices personal or sensitive data shared through the HDX platform they should contact <hdx@un.org> immediately.

### Data Management

19. HDX is built using [CKAN](https://ckan.org/), an open-source data management system.&#x20;
20. Data that is uploaded to HDX is stored by OCHA on servers provided by Amazon Web Services. Data is encrypted in transit and at rest. The servers are located in Virginia, the United States of America.&#x20;
21. All data uploaded to HDX in csv, xls or xlsx format is sent via Google’s DLP API for automated scanning for sensitive data using the DLP algorithm. Data is encrypted in transit and scanned through DLP’s [content method](https://cloud.google.com/dlp/docs/concepts-method-types). Data is not retained by Google in this process.&#x20;
22. OCHA will never alter the values within resources shared through HDX without prior permission from the contributing organization. OCHA may make minor edits to correct errors in dataset descriptions and metadata. The activity stream of the dataset will show a notification if OCHA makes such edits.&#x20;
23. Data shared privately through the HDX platform will never be shared further by OCHA without prior permission from the contributing organization.&#x20;
24. OCHA will notify the contributing organization if we become aware of unauthorized access to private data. After notification OCHA will manage the incident in line with internal data incident management procedure.
25. OCHA will place data ‘under review’ if it is found to violate these Terms and will contact the contributing organization to discuss next steps.
26. OCHA may archive data that is more than five years old and is not updated or downloaded regularly. Contributors are notified if any of their data is archived. OCHA can restore archived data in the dataset list at the request of the contributing organization. Archived data is retained on OCHA’s infrastructure indefinitely.
27. Deleted data cannot be retrieved by users or organizations. Metadata continues to exist in backups of the HDX database indefinitely. Deleted data is purged from backups after 60 days. Deleted data marked as sensitive is purged immediately upon deletion.

### General Disclaimer of Liability

28. Organizations are responsible for the data they share on HDX. OCHA assumes no liability whatsoever for data shared on HDX. While OCHA upholds a high standard for the quality and timeliness of the data shared on HDX, we cannot verify data accuracy. Sharing data through HDX does not imply the transfer of any rights over this data to OCHA. OCHA disclaims all warranties, whether express or implied.&#x20;
29. Data and information on HDX do not imply the expression or endorsement of any opinion on the part of OCHA or the United Nations. This includes opinions concerning the legal status of any country, territory, city or area or of its authorities, or concerning the delimitation of its frontiers or boundaries.

### Privacy Notice

30. User contact details are only shared with the administrator of an HDX organization if the user requests access to data via HDX Connect.
31. OCHA upholds the highest standard of data protection for the personal data of HDX users and organization administrators. In case such personal data is exposed, OCHA will notify all affected individuals and manage the incident in line with internal data incident management procedures.
32. OCHA uses JIRA, a third-party service managed by Atlassian, to help automate workflows related to the administration of HDX, including organization management and quality assurance of datasets. OCHA transfers system-generated CKAN userID’s of HDX users who maintain a dataset on HDX to JIRA as part of our quality assurance process. The CKAN userID’s are retained on JIRA for five years to allow OCHA to follow up with dataset maintainers. After five years OCHA deletes the CKAN userID’s from JIRA. The data stored on JIRA is governed by the [Atlassian Privacy Policy](https://www.atlassian.com/legal/privacy-policy).&#x20;
33. OCHA uses GitBook, a third-party service provided by GitBook Inc, to organize and present HDX documentation. GitBook collects technical and behavioral data on visitors to their website, including IP addresses, visitor’s browser type, language preference, referring site, search queries, site feedback , and the date and time of each visitor request. GitBook visitor data management is explained in the [GitBook privacy statement](https://gitbook.com/docs/policies/privacy-and-security/statement).
34. OCHA uses MailChimp, a third-party marketing automation and email marketing platform managed by Intuit Inc., for outreach to registered HDX users and organization administrators. OCHA shares the email addresses and full names of registered HDX users with MailChimp in order to personalize messages. Review the[ Intuit Inc. Global Privacy Statement](https://www.intuit.com/privacy/statement/) for information on the processing of personal data by Intuit Inc.&#x20;
35. OCHA continually seeks to understand the behavior of users on the HDX platform in order to make improvements. To do so, OCHA uses third-party analytics services, including Google Analytics, Mixpanel and Hotjar. These services use cookies stored on users' devices to send encrypted information to Google Analytics, Mixpanel and Hotjar about how users arrived at HDX, what pages they visited on HDX, and their actions within those pages. Similar tracking is performed when users access HDX via our API or when directly downloading files from a shared link. OCHA does not send identifying information (including names, usernames, or email addresses) to Google Analytics, Mixpanel or Hotjar. Use and retention of the data collected from the HDX platform is governed by these services’ respective Terms of Use.&#x20;
36. If you would like to disable the tracking described above under clause 35, you can install the [Google Analytics Opt-out Browser Add-on](https://tools.google.com/dlpage/gaoptout) to disable Google Analytics tracking. Mixpanel and Hotjar respect ["Do Not Track"](https://allaboutdnt.com/) settings in web browsers. Follow the instructions in [this guide](https://allaboutdnt.com/#adjust-settings) to prevent your browser from sending data to Mixpanel and Hotjar.&#x20;
37. Emails sent by OCHA to registered HDX users may contain [web beacons](https://en.wikipedia.org/wiki/Web_beacon), which allow OCHA to track information about how many people have viewed its email campaigns. OCHA will never share personal data from this tracking with third parties other than with MailChimp, our mailing list provider, which has access by default. The data collected by this tracking system will be retained indefinitely in order to understand how readership of the emails is changing over time.

### Applicable Guidance And Policy

38. OCHA is mandated by [United Nations General Assembly Resolution 46/182](http://www.un.org/documents/ga/res/46/a46r182.htm) and guided by the [Humanitarian Principles](https://www.unocha.org/sites/dms/Documents/OOM-humanitarianprinciples_eng_June12.pdf). OCHA is governed by the applicable guidance and policies established by the United Nations General Assembly and the United Nations Secretariat. Notably, personal data is processed according to the [Data Protection and Privacy Policy for the Secretariat of the United Nations](https://undocs.org/Home/Mobile?FinalSymbol=ST%2FSGB%2F2024%2F1\&Language=E\&DeviceType=Desktop\&LangRequested=False).


# HAPI Terms of Service

By using the HDX HAPI, you acknowledge that you have read, understood, and agreed to these terms of service.

#### **Introduction**

Welcome to the HDX Humanitarian API (HDX HAPI), a digital service provided by the Centre for Humanitarian Data. HDX HAPI is designed to disseminate key humanitarian datasets in a standardized and programmatically accessible format, specifically tailored for countries with active humanitarian response plans.

#### **Acceptance of Terms**

By accessing or utilizing HDX HAPI, you, the user, agree to comply with and be legally bound by these terms and conditions in full. Please read these terms carefully before using the API. If you disagree with any part of the terms, you must not use this service.

#### **Usage Limitations**

To ensure equitable access and maintain optimal performance for all users, the API imposes a restriction on the maximum number of entries retrievable per API call, capped at 10,000 entries.

#### **Rate Limiting**

We regulate the frequency of API calls to prevent overloading our systems and ensure reliable service for all users. Users are kindly requested to moderate their rate of requests to 1 per second. Further details on rate limiting practices will be provided upon request.

#### **User Conduct**

Users are prohibited from interfering with or disrupting the APIs, as well as any servers or networks connected to the APIs. Such interference includes actions that compromise the integrity, performance, or reliability of the service.

#### **Data Logging and Analysis**

The Office for the Coordination of Humanitarian Affairs (OCHA) is committed to continuously improving the HAPI service. As part of this effort, OCHA may log API calls and analyze usage patterns. Users are required to include the ‘app identifier’ parameters in their API requests to facilitate tracking and analysis for statistical and performance evaluation purposes. OCHA also uses third-party analytics services, including Google Analytics, Mixpanel and Hotjar. OCHA does not send identifying information (including names, usernames, or email addresses) to Google Analytics, Mixpanel or Hotjar. Use and retention of the data collected from the HDX platform is governed by these services’ respective Terms of Use.

#### **Disclaimer**

The data and information available through HDX HAPI do not represent the opinions of OCHA or the United Nations, nor do they imply any endorsement. This extends to opinions regarding the legal status of any country, territory, city, or area, including its authorities and the delineation of its frontiers or boundaries.

#### **Contact Information**

Should you have any inquiries or require further assistance, please do not hesitate to contact <hdx@un.org>.


# Glossary

Definitions of key terms used across this documentation.

This Glossary defines the key terms used in this documentation. We also have a broader [Glossary of Data Terms](https://centre.humdata.org/glossary/) on the Centre for Humanitarian Data website.

<table data-header-hidden data-first-column-sticky><thead><tr><th width="264.48828125">Term</th><th>Definition</th></tr></thead><tbody><tr><td><strong>Administrative levels (admin levels)</strong></td><td>The hierarchical geographic divisions within a country, typically ranging from Admin 0 (national boundary) to Admin 1 (provinces or states), Admin 2 (districts), and down to more granular levels such as Admin 3 or 4. These standardized levels are used to organize and analyze data at different geographic scales.</td></tr><tr><td><strong>Comprehensive Knowledge Archive Network (CKAN)</strong></td><td>Open-source open data portal used by HDX. <a href="https://ckan.org/">Link</a></td></tr><tr><td><strong>Centre for Humanitarian Data</strong></td><td>The Centre for Humanitarian Data is focused on increasing the use and impact of data in the humanitarian sector. It is managed by the United Nations Office for the Coordination of Humanitarian Affairs (OCHA). <a href="https://centre.humdata.org/what-we-do/">Link</a></td></tr><tr><td><strong>Common Operational Dataset (COD)</strong></td><td>Authoritative reference datasets used by humanitarian organizations to support response efforts and decision-making. They provide a consistent and standardized data framework for all actors in a crisis. <a href="https://knowledge.base.unocha.org/wiki/spaces/imtoolbox/pages/4099440644/Common+Operational+Datasets+CODs+and+Dashboard">Link</a></td></tr><tr><td><strong>Data Dictionary</strong></td><td>A data dictionary is a reference document that describes the contents of a dataset on HDX. It lets you attach human-readable labels and descriptions to each column or field, making your data easier to understand by both human or machine.</td></tr><tr><td><strong>Data Grid</strong></td><td>Collection of core datasets in most countries with a Humanitarian Needs and Response Plan (HNRP). They provide a comparable way to assess data availability across locations and categories. <a href="https://data.humdata.org/faq#body-faq-Data_Grids">Link</a></td></tr><tr><td><strong>Data Responsibility</strong></td><td>The safe, ethical and effective management of personal and non-personal data for operational response, in accordance with established frameworks for personal data protection. <a href="https://data.humdata.org/dataset/2048a947-5714-4220-905b-e662cbcd14c8/resource/60050608-0095-4c11-86cd-0a1fc5c29fd9/download/ocha-data-responsibility-guidelines_2021.pdf">Link</a></td></tr><tr><td><strong>Dataset</strong></td><td>On HDX, the main unit or container describing data, made up of one or more resources.</td></tr><tr><td><strong>Freshness</strong></td><td>An indicator on HDX datasets that shows whether the data is up-to-date. This is calculated by comparing the dataset's latest time period with the expected update frequency.  <a href="https://hdx-data-freshness.readthedocs.io/en/latest/">Link</a></td></tr><tr><td><strong>Geodata</strong></td><td>Geodata is information about geographic locations that is stored in a format that can be used with a geographic information system (GIS).</td></tr><tr><td><strong>Humanitarian Data Exchange (HDX)</strong></td><td>Open platform for sharing data across crises and organisations. <a href="https://data.humdata.org/">Link</a></td></tr><tr><td><strong>HDX Connect</strong></td><td>Feature on HDX that allows organizations to publish only the metadata for a dataset, alongside a “Request Access” button where users can request access to the data itself.</td></tr><tr><td><strong>HDX API Metadata Endpoints</strong></td><td>Endpoints that allow users to read and write dataset metadata stored on HDX. They support actions like searching for datasets and viewing detailed metadata.</td></tr><tr><td><strong>HDX Python API Library</strong></td><td>Python wrapper built on top of the HDX “create” and “update” endpoints that simplifies publishing and maintaining data on HDX. This is designed to help data contributors easily automate data creation and updates. <a href="https://hdx-python-api.readthedocs.io/en/latest/">Link</a></td></tr><tr><td><strong>HDX File Download</strong></td><td>Programmatic access to download entire data files hosted on HDX. This allows users to retrieve original resources directly and integrate them into automated workflows or local analysis environments.</td></tr><tr><td><strong>HDX Humanitarian API (HDX HAPI)</strong></td><td>A way to access standardized indicators from multiple sources to automate workflows and visualizations. <a href="https://data.humdata.org/hapi">Link</a></td></tr><tr><td><strong>HDX Signals</strong></td><td>A product that monitors key datasets on HDX and generates automated emails to subscribers when significant, negative changes are detected. <a href="https://data.humdata.org/signals">Link</a></td></tr><tr><td><strong>HDX Notifications</strong></td><td>A feature that allows users to receive alerts when datasets on the dataset pages, crisis pages or location pages that they are subscribe to are updated or changed on HDX. <a href="https://docs.humdata.org/find/find-data/staying-up-to-date-with-hdx">Link</a></td></tr><tr><td><strong>Humanitarian Exchange Language (HXL)</strong></td><td>As of 31 January 2026, the Centre no longer supports the HXL standard and tools related to the HDX platform. HXL was created over a decade ago as a simple standard for messy data, with a primary focus on combining spreadsheets. As technology and our humanitarian data ecosystem has advanced, we are exploring new ways to standardize data, improve interoperability and speed up data processing across data sources. For more information, read our <a href="https://centre.humdata.org/retiring-hxl-services/">Retiring HDX Services</a> blog.</td></tr><tr><td><strong>Locations</strong></td><td>When used on HDX, this refers to countries or areas the dataset relates to. A full list of ‘locations’ covered by HDX is available <a href="https://data.humdata.org/group">here</a>. HDX names locations according to the <a href="https://unstats.un.org/unsd/methodology/m49/">UN's M49 standard</a>.</td></tr><tr><td><strong>Metadata</strong></td><td>Data that describes a dataset, including details such as its title, source, date of publication, geographic coverage, and update frequency. Metadata helps users understand what a dataset contains and whether it is suitable for their needs.</td></tr><tr><td><strong>Personally identifiable information (PII)</strong></td><td>Personally identifiable information, also called “direct identifiers”, are variables that reveal directly and unambiguously the identity of a respondent, (e.g. names, social identity numbers). Source <a href="https://sdcpractice.readthedocs.io/en/latest/glossary_acr.html#glossary">SDC Practice Guide</a>.</td></tr><tr><td><strong>Place Codes (P-codes)</strong></td><td>Unique geographic identification codes, usually represented by combinations of letters and numbers, to identify a specific place, point, positional location or feature on a map or within a database. <a href="https://knowledge.base.unocha.org/wiki/spaces/imtoolbox/pages/222265609/P-codes">Link</a></td></tr><tr><td><strong>Resource</strong></td><td>A sub-container within a dataset. A resource can contain files such as a CSV file, Excel spreadsheet, or PDF document. Each resource is associated with metadata that describes the file within it. </td></tr><tr><td><strong>Statistical Disclosure Control (SDC)</strong></td><td>A technique used to assess and lower the risk of a person or group being re-identified in the analysis of microdata. Applying SDC to microdata enables organizations to share the data more widely without exposing affected people to harm. <a href="https://data.humdata.org/dataset/2048a947-5714-4220-905b-e662cbcd14c8/resource/487f6d90-d879-4c59-8439-f2d08633f357/download/guidance_note_sdc.pdf?_gl=1*ymj6da*_ga*ODMyMTMwODUuMTc0NDAyOTA2Nw..*_ga_E60ZNX2F68*czE3NTkxNTY0OTgkbzE2OSRnMSR0MTc1OTE2MTY5MyRqNTkkbDAkaDA.">Link</a></td></tr><tr><td><strong>Tabular Data Endpoints (TDE)</strong></td><td>Provides programmatic access to a number of tabular datasets hosted on HDX. It supports features like customizable queries and dataset joins to enable seamless integration into external tools and systems. <a href="https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints">Link</a></td></tr><tr><td><strong>Tags</strong></td><td>Keywords or labels assigned to datasets to make them easier to discover and categorize. On HDX, tags might include terms like "education", "displacement", or "baseline population" to help users find relevant data.</td></tr><tr><td><strong>The United Nations Office for the Coordination of Humanitarian Affairs (UNOCHA)</strong></td><td>The United Nations Office for the Coordination of Humanitarian Affairs (OCHA) is the UN agency responsible for coordinating international humanitarian responses to emergencies and natural disasters. <a href="https://www.unocha.org/">Link</a></td></tr></tbody></table>

<br>


# Find data on HDX

This section walks you through the process of finding data on HDX. There are two main ways to discover data: searching for specific datasets using the search bar and browsing for datasets using our location, organization and crisis pages.

## Searching for data on HDX

You can search from the HDX home page or from the search bar in the header of any page.

### How to search for data on HDX

{% stepper %}
{% step %}

#### Enter your search term

Type keywords in English into the search bar, found at the center of the home page or at the top of any other HDX page.

<div align="left" data-with-frame="true"><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FkTYuunAysizk0tfjZkzf%2Fhomepage%20search.png?alt=media&amp;token=9e32ef3f-35d6-4a28-b890-8d0ba1b5e502" alt="Search bar on home page" width="563"></div>
{% endstep %}

{% step %}

#### View your search results

The search results page displays datasets that match your search term. Each result includes the dataset title, the organization that published it, and a brief summary of the dataset contents.

By default, results are sorted by Relevancy, so the datasets most closely related to your search appear first. You can change the sort order to “Last Modified”, “Last Added”, “Name Ascending”, “Name Descending”, “Trending” and “Most Downloads”. You can also adjust how many datasets are displayed on a page, increasing the default from 10 results to 25, 50, or 100.
{% endstep %}

{% step %}

#### Refine your search using filters

The left sidebar contains filters to help narrow your search results. You can filter by Location, Format, Organization, and Tags, as well as use the Advanced Filters, described below, to further narrow your results.&#x20;

* **Tabular Data Endpoints:** Programmatic access to a number of tabular datasets hosted on HDX. [Learn more](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints).
* **HDX HAPI Data:** Standardized data from the HDX Humanitarian API, organized by indicator and country. Learn more.
* **CODs:** Authoritative reference datasets for administrative boundaries and population statistics . [Learn more](https://storymaps.arcgis.com/stories/dcf6135fc0e943a9b77823bb069e2578).
  * **Standard COD:** A COD that has been accepted for use by the humanitarian community, but has not gone through an additional standardization process.&#x20;
  * **Enhanced COD (also COD+):** A COD that has been standardized.&#x20;
  * **HPC:** Data related to the Humanitarian Programme Cycle data. [Learn more](https://knowledge.base.unocha.org/wiki/spaces/hpc/pages/3993075713/About+the+HPC?_gl=1*ya642f*_ga*OTU2MzMzNjgxLjE2NzQ2OTkwMzc.*_ga_E60ZNX2F68*czE3NzYxNDk2NTMkbzg5MiRnMSR0MTc3NjE1MDE5NCRqMzYkbDAkaDA.).

    * **Humanitarian Needs:** Data from HPC Tools reflecting the humanitarian needs of affected people.
    * **Response Planning:** Data from HPC Tools on the planned humanitarian action.
    * [**Financials (FTS)**](https://data.humdata.org/dataset/?vocab_Topics=humanitarian+financial+tracking+service-fts)**:** Contains funding data from OCHA’s Financial Tracking Service (FTS) and HDX Humanitarian API (HDX HAPI).
    * **Sub-national:** Data disaggregated below country level.
    * **Geodata:** Datasets available in recognized geospatial data file formats e.g. GeoJSON, Shapefile etc.
    * **Datasets with P-Codes:** Data containing a [p-code](https://knowledge.base.unocha.org/wiki/spaces/imtoolbox/pages/222265609/P-codes), short for place code, a unique identifier for locations in humanitarian datasets.
    * **Tags:** Thematic filters such as "administrative boundaries", "population", or "health facilities".

    <div align="left" data-with-frame="true"><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FbfWi010pWF62YPzVKbYk%2FDataset%20page%20and%20search%20filter.png?alt=media&amp;token=fde0ce41-6010-419c-b938-20ed17f8a143" alt="Search Filter on the left, search results on the right" width="563"></div>

{% endstep %}
{% endstepper %}

### Tips for effective searching

* **Use English and full words rather than acronyms:** For example, search for 'internally displaced persons' rather than 'IDP'.&#x20;
* **Combine search with filters:** Start with a keyword search, then use filters to narrow results. For example, search "displacement" and then filter by a specific location.
* **Use the sort options:** By default, dataset results are sorted by relevance. You can also sort alphabetically and by popularity and last modified date.

### Understanding archived datasets

At the bottom of the search results on the left, you will see:

* **Datasets:** The number of public datasets matching your search
* **Archived Datasets:** Older datasets that are no longer maintained but may still be useful

<div align="left" data-with-frame="true"><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2Fv8jd193Ge83wiZhT3QRe%2Farchvied%20datasets.png?alt=media&amp;token=21cd3d8b-7f93-4d2d-8766-c340accce2c8" alt="Archived datasets" width="563"></div>

If you are looking for historical data and are not able to find the data you need in the main search results, try the Archived Datasets link under Products menu in the header or in the footer. This will show older datasets that have been archived on HDX in the search results.

## Browse for data on HDX

HDX allows you to browse for data from a specific location, organization or humanitarian crisis.&#x20;

* **Browse by location:** Location pages bring together datasets related to a specific country or territory. The map at the top of the location page shows all locations where data is available. Locations in red on the map or with a red dot beside the location name in the list under the map, denote a location with a humanitarian response plan&#x20;
* **Browse by organization:** Organization pages show all datasets shared by a specific data contributor. Learn more about organizations on HDX here.
* **Browse by crisis:** When demand for crisis-related information is high, we activate a crisis page on HDX. Crisis pages bring together the most relevant datasets in one place for users to easily find, download, and use without needing to search across multiple organizations. Crisis pages are featured on the HDX homepage under the Products menu on the header navigation.


# Understanding the HDX dataset page

This section explains how to interpret the information provided on HDX dataset pages and better understand the data being shared. Each dataset page consists of a fixed header section, left-hand menu that moves between tabs and Data and Resources section.

1. Dataset page header
2. Dataset details menu
3. Data and Resources

<div align="left" data-with-frame="true"><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FaaEL9uJXJAq5kmXLaMqS%2FWP%20dataset%20page.png?alt=media&amp;token=e9451e6a-be72-4608-9490-9b3ff6e8e243" alt="Dataset page" width="563"></div>

### Dataset page header

* **Dataset title:** The dataset title typically includes the location and topic, such as "Afghanistan - Health Indicators" or "Nigeria - Food Prices".
* **Dataset description:** Provides details about the dataset, including its purpose, context and potential use. &#x20;
* **'Get Notified' button:** Click this button to subscribe to email notifications about changes to this dataset. See the Notifications page for more information.
* **Downloads count:** The total number of times the dataset has been downloaded.
* **Organization logo :** The logo of the organization that shared the dataset. Click on the logo to go to the organization page on HDX.&#x20;
* **Contact the contributor:** Click this link to send a message to the person or team responsible for the dataset. See the 'Contact the contributor' section below for information.
* **Key metadata:** The row below the description shows key metadata such as location, expected update frequency, time period and source (see full definitions of these in the Metadata section.
* **Data preview:** HDX creates a map automatically from geodata formats that it recognizes. Here is an [example of geodata](https://data.humdata.org/dataset/hotosm_lbn_roads) showing the preview feature.

### Data and Resources

This section lists all the files available to download.

<div align="left" data-with-frame="true"><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FOvujmycyEfAjVhI6qgxa%2FWP%20dataset%20page-data%20and%20resources.png?alt=media&amp;token=be29d02d-c88a-4a5a-ace4-08a7e63715ad" alt="Data and Resources section of a dataset page" width="563"></div>

Each resource shows:

* **Format icon:** This icon displays the format of the resource file.
* **Resource name:** The name describes the file contents.&#x20;
* R**esource description:** Provides specific details about the resource, including its purpose, context and potential use.
* **Access via API:** Only shows on a tabular resource available through our Tabular Data Endpoint (TDE) API. Clicking the link takes you to the ‘API Access’ section on the Resource Page.&#x20;
* **Download button:** Click to download the file locally and directly to your computer. The file size is shown in parentheses.
* **More Information button:** Click to access the Resource Page.

### Metadata <a href="#docs-internal-guid-59851f75-7fff-a66b-9222-621d42a29f4c" id="docs-internal-guid-59851f75-7fff-a66b-9222-621d42a29f4c"></a>

This section contains metadata about the dataset.

* **Time period:** The date range that the data covers. For example, "01 January 2020 - 31 December 2024" means the data either contains information from that time period or is valid for that period.
* **Expected update frequency:** The frequency at which the data contributor plans to update the dataset. An ‘up to date’ label ("freshness") indicates that the dataset contains the latest available data. The calculation to determine if a dataset is up to date has been updated as of April 2025. It is as follows: End date + Frequency = cut-off date when data becomes out of date. Example: a dataset contains data from 01 January 2025 until 31 March 2025 and has an update frequency of every 3 months, it will appear as ‘up to date’ until the 30 June 2025.
* **Modified:** The date the  data contributor last updated the file.
* **Contributor:** The organization responsible for publishing the data on HDX, also represented by the logo at the top of the page.
* **Source:** The organization that collected or produced the data.&#x20;
* **Dataset Added on HDX:** The date that the datasets were first added to HDX.
* **Dataset ID:** A unique identifier for the dataset. Click the copy icon to copy this ID.
* **Location:** The country or countries the data relates to. Click the location name to go to the location page and find related datasets.
* **Methodology:** Information about how the data was collected or processed. A list of the types of methodology is linked here.
* **Caveats / Comments:** Important notes about the data, such as known issues, limitations, or special considerations for use.
* **License:** The open data license under which the data is available. See the section below on 'Understanding data licenses'.
* **Tags:** A tag is a term that a data contributor adds to a dataset’s metadata to describe or categorize the data. HDX maintains a list of approved tags here.
* **File Format:** The file format(s) the data is available in. HDX supports a range of file formats, a complete list of which you can find here.
* **Visibility:** Visibility metadata shows whether the dataset is public or private. Public data is openly available to download and access on HDX. Private datasets are only visible to members of an organization on HDX.&#x20;
* **Downloads:** A chart after the Metadata section showing downloads over recent months.

Additional features on the dataset page:

* **Showcases:** If you have a data visualization, documentation or related material in PDF format, you can add it as a showcase item on the dataset page.&#x20;
* **Activity:** Click the view a timeline of changes to the dataset, including when resources were added, updated, or removed.

### Resource page <a href="#docs-internal-guid-aca71fac-7fff-6d4a-c944-497f471eda58" id="docs-internal-guid-aca71fac-7fff-6d4a-c944-497f471eda58"></a>

Click the resource name or the More Information button on the resource card and you open the Resource Page for that resource. This shows the following information.

<div align="left" data-with-frame="true"><figure><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FlrWhw07hBnnQzJmRk9Ls%2FResource%20preview.png?alt=media&amp;token=394535e5-1af1-4140-aa53-f37323e67849" alt="" width="563"><figcaption><p>Resource Preview</p></figcaption></figure></div>

* **Format icon:** This icon displays the format of the resource file.
* **Resource name:**  The name describes the file contents.&#x20;
* **Resource description:** A description of the resource provided by the contributor is displayed here.
* **Download button:** Click to download the file locally and directly to your computer.
* **Export metadata button:** You can export the metadata for each resource in either JSON or CSV.
* **Last modified date:** The date the  data contributor last updated the file.
* **Resource ID:** A unique identifier for the data resource. Click the copy icon to copy this ID, which is useful for API and programmatic access. Find out more about Resource ID in the Build with HDX section.
* **Resource URL:** The full File URL for the resource which you can use to add data to PowerBI (see Power BI section)
* **Resource preview:** View the data in your browser without downloading (available for CSV and some tabular formats) The preview shows column headers, first rows of data and total number of rows and columns. This helps you quickly check whether the data structure meets your needs before downloading.
* **Data dictionary:** View a table of human-readable labels and descriptions for each column or field in the resource.
* **API access section:** Where a dataset is available through Tabular Data this section contains a link to the TDE documentation, a button to get an access token, the Resource ID and an example query.

## Finding out more about datasets

‘Contact the contributor’ lets users send inquiries directly to data contributors. This feature is available on all dataset pages and is located below the organization logo. If you are not already a registered user, you will be prompted to sign up before a message can be sent. Inquiries can be anything from a general question about a dataset to reporting a problem such as a broken link. The HDX team receives a copy of all messages sent through this feature.

### Using the 'Contact the contributor' form

{% stepper %}
{% step %}

#### **Click on the ‘Contact the contributor’ link on any dataset page.**&#x20;

If you're not already logged in, you will be prompted to log in or register before the form appears.

<div align="left" data-with-frame="true"><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2F8eLugQLZAzkiWGexwSyd%2Funknown.jpeg?alt=media&amp;token=c306560f-61b6-493a-b054-287b7b317320" alt="Contact the contributor form" width="375"></div>
{% endstep %}

{% step %}

#### **Fill out all sections of the form.**&#x20;

* **Your inquiry is regarding :** A dropdown to categorize your message:
  * General question
  * Metadata
  * Problem report
  * Suggested edits
* **Your name and email address:** Where the contributor can reply
* **Comments:** The body of your message.
  {% endstep %}

{% step %}

#### **Click Submit**

Note: It is the responsibility of the contributor to respond to you and the HDX team may not be included in further correspondence.&#x20;

For general questions about HDX itself (rather than specific datasets), email <hdx@un.org>.
{% endstep %}
{% endstepper %}


# Accessing and using data

There are two ways to download data from HDX.

1. Download directly from the dataset page

2. Download via the API


This section contains information about how to download data directly from HDX. Go to the [Build with HDX](https://docs.humdata.org/build) section for more information about accessing data through the API.

## Download directly from the dataset page


{% stepper %}
{% step %}

#### **Open the dataset page**

Every dataset on HDX has its own page with a description of the data, metadata, and a list of resources to download.
{% endstep %}

{% step %}

#### **Find the resource you want to download**

Under "Data and Resources", you will see all the resources of the dataset. Each resource has:

* Resource format (CSV, XLSX, etc.)
* Resource name and description
* More information
* Download button and resource size
  {% endstep %}

{% step %}

#### **Click Download**

Click the Download button to the right of the resource to download the file to your computer's default download location.

Next to the download button, you will see a More Information button. Click to view:

* Export metadata
* Last modified&#x20;
* Resource ID
* Resource URL
  {% endstep %}
  {% endstepper %}

### Tips for downloading data

* **Check the size of the resource before downloading:** Large files may take time to download on slower internet connections. The size is shown in parentheses next to the resource name.
* **Bookmark important datasets:** If you may need to re-download updated versions, bookmark the dataset page for easy access.
* **Check the file format before downloading:** Make sure you have software that supports the format you are downloading.
* **Review the metadata before downloading:** Metadata provides important information about the data and will help you understand whether the dataset fits your needs.

## Getting access to 'by request' data (HDX Connect)

Some datasets on HDX are available ‘by request’ rather than for direct download - this service is called [HDX Connect](https://docs.humdata.org/publish/publish-data/preparing-and-publishing-data).

### How to access ‘by request’ data <a href="#docs-internal-guid-8005ea47-7fff-339a-87e1-e9b5ea3f2121" id="docs-internal-guid-8005ea47-7fff-339a-87e1-e9b5ea3f2121"></a>

{% stepper %}
{% step %}

#### Find the dataset

HDX Connect data on HDX are marked by a red cross icon with a tooltip that says ‘This data is by request only’. Information about the dataset will be shown on the dataset page including the description, location, time period, and data contributor.
{% endstep %}

{% step %}

#### Click 'Request Data'

From the Dataset page, click the grey Request Data button.
{% endstep %}

{% step %}

#### Log in to your HDX account

You will be asked to log into your HDX account to request the data. If you do not have an account, click ‘Sign Up’ in the top right corner of any page.
{% endstep %}

{% step %}

#### Complete the request form

Fill in the required information:

* Your name
* Your email address
* Your organization
* Your organization type
* Where you are located
* Intended use of the data
* Comments: Please add further details here that might help the data contributor evaluate your request.
  {% endstep %}

{% step %}

#### Submit your request

Review the information you provided and click Submit. Your request will be sent to the data contributor and the HDX team. You will receive an email confirming your request.
{% endstep %}

{% step %}

#### Wait for a response

The data contributor will review your request and respond via email. Response times vary depending on the organization and complexity of the request. You will be able to see the status of your request from the HDX Connect Requests page in your User Dashboard.
{% endstep %}
{% endstepper %}

### Request Responses

If your request is approved, you will receive an email with instructions on how to access the data.&#x20;

This may include:

* A direct link to download the data
* Instructions for accessing the data&#x20;

If your request is denied, the data contributor will typically explain why. You may be able to submit a revised request with additional information. Some requests require additional review. The data contributor may contact you with questions before making a decision.

#### Tips for successful requests

* Be specific about your use case. Clearly explain what you are working on and how the data will help. Vague requests are harder to evaluate.
* Explain data protection measures. If the data is sensitive, describe how you will handle it responsibly and limit access.
* Be patient. Data contributors, especially those working in active crises, may need time to review requests. Allow at least a few business days for a response.

If you have questions about the HDX Connect process or a specific data request, email <hdx@un.org>.<br>

## Connecting HDX data to tools you use

You can access HDX data directly using data visualization and analysis tools without having to manually download and upload files. We are developing guidance on how to connect to  HDX data through common  tools. For the time being we have detailed guidance on linking [HDX data to Power BI](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints/how-to-query-the-tabular-data-endpoints).

If there are other tools that you would like us to consider developing more detailed guidance for, please email <hdx@un.org>

<br>


# Staying up-to-date with HDX

Humanitarian data changes frequently. This section explains how to stay informed about new and updated data on HDX. HDX offers several features to help you stay current:

* **HDX Notifications** - Subscribe to specific datasets, locations, organizations, or crises to receive email alerts when data is added or updated. You can find step-by-step instructions on signing up to Notifications on these pages.
* **HDX Signals** - A product that monitors key datasets and generates automated emails when significant, negative changes are detected. You can find out more about Signals and sign up for alerts [here](https://data.humdata.org/signals).
* **Activity streams** - View recent changes on organization and location pages on the Activity stream section of the dataset page.

## **HDX Notifications**

### Types of HDX Notification <a href="#types-of-hdx-notification" id="types-of-hdx-notification"></a>

There are two types of notifications available on HDX:&#x20;

**1. Datasets**

Dataset notifications inform users about changes to resources within a dataset, including when a resource has been added, updated or removed, or when there have been changes to the structure of tabular data (e.g., columns or headers change).

**2. Locations, crises and organizations**

Notifications for location, crisis and organization pages inform users when a new dataset has been added to the page by a data contributor.

### Subscribe to get HDX Notifications <a href="#subscribe-to-get-hdx-notifications" id="subscribe-to-get-hdx-notifications"></a>

{% stepper %}
{% step %}

#### Click the ‘Get notified’ button on the relevant page

<div align="left" data-with-frame="true"><figure><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FgDO5T4FkdPiwtcHoCdFi%2Fget%20notified.png?alt=media&amp;token=8b92cea0-2d46-459a-b8ea-d8f7c8821381" alt="" width="563"><figcaption><p>Get Notified Button</p></figcaption></figure></div>

From any dataset, location, crisis or organization page, you can subscribe by clicking the blue ‘Get notified’ button at the top of the page, below the title.
{% endstep %}

{% step %}

#### Enter your email address or log in

If you don’t have an HDX account, enter your email address and follow the prompts to verify your email.&#x20;

If you have an HDX account, log into the account using the associated email address.
{% endstep %}

{% step %}

#### You are subscribed!

You have successfully subscribed to notifications for this page.
{% endstep %}
{% endstepper %}

### Receive HDX Notifications <a href="#receive-hdx-notifications" id="receive-hdx-notifications"></a>

Notifications are sent shortly after data contributors add or update data on HDX.

### Unsubscribe from HDX Notifications

There are three ways to unsubscribe from notifications.

#### **1. Unsubscribe from a recent email**

Click the unsubscribe link on a recent email.

<div align="left" data-with-frame="true"><figure><img src="https://content.gitbook.com/content/4eRiaTyCUWRqgHINBcpH/blobs/GXw4rk9mThqrDzZi3DVg/email_unsub.jpg" alt="" width="300"><figcaption><p>Email unsubscribe</p></figcaption></figure></div>

#### **2. Unsubscribe via the page**

{% stepper %}
{% step %}
**Go to the dataset, location, crisis or organization page you are subscribed to**

<div align="left" data-with-frame="true"><figure><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2FtRIPXk2CmT9FQhhjdujT%2Funsubscribe.png?alt=media&amp;token=58682e9a-e1e8-43c6-bb27-29abe90c2dc4" alt="" width="563"><figcaption><p>Organization page unsubscribe button</p></figcaption></figure></div>
{% endstep %}

{% step %}
**Click the ‘Unsubscribe’ button**

Click the ‘Unsubscribe’ button on the page and confirm you want to unsubscribe.
{% endstep %}
{% endstepper %}

#### 3. Unsubscribe from the Notifications Hub (if you have an HDX account)

{% stepper %}
{% step %}
**Log into your HDX account**

Log in to your HDX account using the menu at the top of every page.
{% endstep %}

{% step %}
**Go to the Notifications Hub**

Once logged in, access the Notifications Hub under User Settings by clicking on your name at the top right of the page.

<div align="left" data-with-frame="true"><figure><img src="https://2832631354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4eRiaTyCUWRqgHINBcpH%2Fuploads%2F1lDgTB4LsmeGAnebU5et%2Fnotifications%20dropdown.png?alt=media&amp;token=8ba30aec-f3dd-40e6-a395-39f63cdb3083" alt="" width="563"><figcaption><p>Notifications Hub tab under User Settings</p></figcaption></figure></div>
{% endstep %}

{% step %}
**Find the notification that you want to unsubscribe from**

All of your notification subscriptions will be listed in the Notifications Hub.

<div align="left" data-with-frame="true"><figure><img src="https://content.gitbook.com/content/4eRiaTyCUWRqgHINBcpH/blobs/j3LqoimIpDSQjKtVNjrB/HDX_not_sub.jpg" alt="" width="563"><figcaption><p>Notifications Hub list</p></figcaption></figure></div>
{% endstep %}

{% step %}
**Click the ‘Unsubscribe’ button**

To unsubscribe from a notification, click the button next to the subscription.
{% endstep %}
{% endstepper %}

***

### HDX Notifications FAQs

**Q: Do I need an HDX account to get notified?**

No. You can sign up for notifications with your email address. However, we recommend keeping your browser’s cookies enabled to make it easier to unsubscribe. If you want to manage your subscriptions through the Notifications Hub, you will need an HDX account.

**Q. Are notifications available for all datasets on HDX?**

No. Notifications are only available for regularly updated, public datasets.

We do not currently offer notifications for the following datasets:

* Datasets that are not expected to update (‘Never’ under ‘Expected Update Frequency’)
* Private datasets
* Archived datasets
* HDX Connect datasets

**Q. What’s the difference between a dataset and a resource?**

A dataset is a collection of one or more resources.

* A dataset includes a title, description, tags, and metadata.
* A resource is an individual file within that dataset, such as a spreadsheet or shapefile.

**Q. What changes prompt a notification to be sent?**

Notifications will be sent when certain changes occur to a dataset resource or page. The table below summarises the changes that will prompt an email notification to be sent:

<table data-header-hidden data-first-column-sticky data-full-width="false"><thead><tr><th width="368"></th><th width="188.5" align="center"></th><th align="center"></th></tr></thead><tbody><tr><td><strong>Type of Change</strong></td><td align="center"><strong>Dataset</strong> <strong>Notification</strong></td><td align="center"><strong>Location, Crisis or Organization page Notification</strong></td></tr><tr><td><strong>Dataset added to page</strong></td><td align="center">n/a</td><td align="center">✅</td></tr><tr><td><strong>Dataset removed from page</strong></td><td align="center">n/a</td><td align="center">❌</td></tr><tr><td><strong>Resource (file) added or removed</strong></td><td align="center">✅</td><td align="center">❌</td></tr><tr><td><strong>Resource updated (e.g. file replaced)</strong></td><td align="center">✅</td><td align="center">❌</td></tr><tr><td><strong>Structure of resource has changed</strong></td><td align="center">✅</td><td align="center">❌</td></tr><tr><td><strong>Metadata or text description changed only</strong></td><td align="center">❌</td><td align="center">❌</td></tr></tbody></table>

**Q. How soon after a change will I get a notification?**

Notifications are sent three hours after a change is first detected. This delay gives us time to group related changes into a single email notification, and gives the data contributor time to complete their updates.&#x20;

**Q: I subscribed but I’m not getting notifications. What should I do?**

Check your spam or junk folder. If you signed up using your email (without logging into an HDX account), make sure you have clicked on the verification link we sent.

Alternatively, you might not have received a notification because there have not been any changes since you subscribed. You can check this by visiting the relevant page on HDX.

If the problem persists, contact <hdx@un.org> for support.

**Q: I want to unsubscribe from a notification, but I don’t see the ‘Unsubscribe’ button on the page. How can I unsubscribe?**

If you signed up using your email (without logging into an HDX account), and your browser has cleared the relevant cookies, the ‘unsubscribe’ button may not appear.

If this is the case, unsubscribe via the ‘Unsubscribe’ link in any of the email notifications you have received.

**Q. How reliable are notifications?**

We aim to ensure notifications are timely and relevant, but there are some limitations to be aware of. We can only notify you about changes that are made directly on HDX. We cannot guarantee that a dataset published on HDX is the most recent version available.


# Why publish on HDX?

## Data-driven humanitarian action <a href="#docs-internal-guid-ce75a1d3-7fff-dc46-142e-43c3a25beab0" id="docs-internal-guid-ce75a1d3-7fff-dc46-142e-43c3a25beab0"></a>

By publishing your organization’s data on HDX, you help frontline responders, policymakers, analysts, and affected communities access the information they need to make informed decisions. You are joining a global community, made up of UN agencies, NGOs, research groups, private sector companies, and national authorities, committed to enabling faster, more effective, and more accountable humanitarian response through open and responsible data sharing.

HDX is managed by the [United Nations Office for the Coordination of Humanitarian Affairs (OCHA)](https://www.unocha.org/).

## Benefits of publishing data on HDX

* **Support humanitarian response:** Your data can directly inform operational planning, situational awareness, and early warning systems.
* **Increase visibility and impact:** Publishing on HDX ensures the wider humanitarian data community can make use of your data, furthering the impact of your work.&#x20;
* **Be part of the humanitarian data community:** By publishing on HDX, you contribute to a collaborative community where partners can learn from each other’s approaches, tools, and use cases.
* **Advocate for open data and access:** Signals your commitment to transparency, accountability, and collaboration. HDX provides stable hosting and preserves all shared data. Older datasets are archived, never deleted, making them citable and reusable over time.
* **Improve data quality and interoperability:** Publishing on HDX invites feedback and validation, and helps align your data with global humanitarian standards. It also enhances compatibility with external systems and tools, such as dashboards and automated workflows.&#x20;
* **Track reach and use for reporting needs:** Use the HDX Stats dashboard to see who is downloading your data, aiding reporting requirements from donors and stakeholders.
* **Get support from the HDX team:** From joint webinars to promotion through impact stories and social media, we help you share your work with our community.&#x20;

## Who publishes data on HDX?

Over 220 organizations actively publish data to HDX, including:

* UN agencies (e.g. WFP, IOM, UNICEF)
* NGOs (e.g. ACAPS, CARE, Danish Refugee Council)
* Academic institutions (e.g. ETH Zurich, Heidelberg Institute for Geoinformation Technology, University of Oxford)
* Private sector and tech groups (e.g. Google Research, Microsoft AI for Good, Meta Data for Good)
* National governments and coordination bodies


# Preparing and publishing data

## Ways to publish data on HDX <a href="#docs-internal-guid-627def8e-7fff-c624-c499-2c416b79ca1a" id="docs-internal-guid-627def8e-7fff-c624-c499-2c416b79ca1a"></a>

Organizations can choose between three ways to publish data on HDX. These dictate who can access the data and how it is shared. Organizations should choose the appropriate setting based on the sensitivity of the data, the intended audience, and internal policies or restrictions. All data on HDX must be published with comprehensive metadata (information about the data).&#x20;

#### Open data publishing

**Public:** Public datasets are visible to and can be downloaded by anyone visiting HDX. This option is the most common way to publish data on HDX.

Opt for ‘public’ when:&#x20;

* A resource contains non-sensitive data
* You want your data to be visible and available for download to anyone visiting HDX

#### Controlled access publishing

**HDX Connect / By Request:** HDX Connect is a feature that allows organizations to publish only the metadata for a resource. By using HDX Connect, organizations can signal that data exists, while ensuring access is adequately controlled in line with the data’s sensitivity.&#x20;

Registered HDX users can request access to the resource through a “Request Access” button. The contributing organization can then decide whether to share the data that has been requested. The data is not hosted on HDX servers, and therefore, if access is approved, the contributing organization will share the data directly with the requester. The Centre recommends using secure (encrypted) channels for data sharing between contributing organizations and requesters.

Opt for HDX connect / ‘by request’ when: &#x20;

* A resource contains sensitive data
* You want to approve access requests individually

Example: [IOM Cameroon multi-sector needs assessment results](https://data.humdata.org/dataset/2025-cameroon-multi-sector-needs-assessment-msna-dataset) (September 2025). Registered users can request access to the underlying data by clicking the ‘Request Access’ button. They will be asked to share information about who they are and how the data will be used in order to inform the decision by the contributing organization on whether to share the requested data.&#x20;

**Private:** Private datasets are only visible by members of your HDX organization, when they are logged in. They are not included in HDX search results or listed under datasets. Private datasets may not contain personal data or other data that is classified as ‘strictly confidential’ in an Information Sharing Protocol.

Opt for ‘private’ when:

* You are sharing data solely for internal collaboration&#x20;
* Datasets are not approved for public release

#### Comparing data publication options

When selecting how to share data on HDX, it is important to consider the data sensitivity and potential risks to affected people. You can also change how the data is shared at any time.&#x20;

<table data-header-hidden data-first-column-sticky data-full-width="false"><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><br></td><td><strong>Open data</strong></td><td><strong>Controlled access</strong></td><td></td></tr><tr><td><strong>Sharing option</strong></td><td><strong>Public</strong></td><td><strong>HDX Connect (By request)</strong></td><td><strong>Private</strong></td></tr><tr><td>Who can see the dataset? </td><td>Data and metadata visible and accessible to anyone visiting HDX</td><td>Metadata visible to anyone visiting HDX</td><td>Metadata and data visible only to members of the contributing organization account on HDX</td></tr><tr><td>Is data downloadable from HDX?</td><td>Yes</td><td>No. The data stays on the  organization’s infrastructure and is shared directly with approved users</td><td>Yes, only for logged-in members of the organization.</td></tr><tr><td>What is the data sensitivity level?</td><td>Low / No - data is unlikely to cause any harm to affected people or humanitarian organizations</td><td>High / Severe - data is likely to cause significant harm or negative impacts to affected people, humanitarian organizations or a response</td><td>Moderate - data is likely to cause minor harm or negative impacts to affected people, humanitarian organizations or a response</td></tr><tr><td>Best for</td><td>Non-sensitive, open data</td><td>Sensitive or proprietary data</td><td>Internal collaboration or draft data</td></tr><tr><td>Examples</td><td>Road network data; population statistics</td><td>Locations of at-risk communities; detailed data on humanitarian access incidents </td><td>Early drafts; internal analysis</td></tr></tbody></table>

## Preparing data to publish

Before uploading data to HDX, take time to prepare your data and metadata. Well-prepared data is easier to find, understand, and use. Two questions to consider:

#### Is the data safe to publish?

When uploading data to HDX, consider whether the data is sensitive, i.e. whether exposure of the data could lead to harm or negative impacts for affected people or impede the work of humanitarian organizations.

The [HDX Terms of Service](https://data.humdata.org/faqs/terms) informs support users how to share data responsibly. Review section 7 under ‘Data Scope and Criteria’ for instructions on responsible data sharing via HDX.

**How HDX defines data sensitivity**

* **Low or No sensitivity:** exposure of the data is unlikely to cause any harm to affected people or humanitarian organizations. Data at this sensitivity level is suitable for sharing publicly on HDX. Examples include data on road networks, geospatial information on (undisputed) boundaries, and country-level population statistics.&#x20;
* **Moderate sensitivity:** exposure of the data is likely to cause minor harm or negative impacts and/or be disadvantageous to affected people or humanitarian organizations. Data at this sensitivity level may only be shared privately or through HDX Connect. Examples include preliminary results of assessments that have not been cleared for publication, as well as operational presence mapping data at the district-level for some response contexts.
* **High sensitivity:** exposure of the data is likely to cause serious harm or negative impacts to affected people or humanitarian organizations, and /or damage a humanitarian response. Data at this sensitivity level may only be shared through HDX Connect. Examples include data on the movement of humanitarian convoys, and community-level survey results covering sensitive subjects such as Gender-Based Violence.
* **Severe sensitivity:** exposure of the data is likely to cause severe harm or negative impacts to affected people or humanitarian organizations, and /or damage a humanitarian response. Data at this sensitivity level may only be shared through HDX Connect and following an approved request should only be shared with strict data security measures in place, as well as a data sharing agreement if required. Examples include personal data of beneficiaries, locations of at-risk communities, and detailed accounts of access incidents

**How to assess and manage risk**

The sensitivity of datasets varies depending on the crisis context. For example, the exact location of a health facility may be safe to share in a natural disaster, while sharing similar data in certain conflict zones can lead to significant harm.

To assess and manage risks:&#x20;

* Review the Information Sharing Protocol (ISP) for the response context to understand the sensitivity level of your data. An overview of endorsed ISPs is available [here](https://centre.humdata.org/data-responsibility/). If no ISP is available for your response context and you are not sure about the sensitivity level, reach out to the HDX team via <hdx@un.org> for support.
* For microdata, apply Statistical Disclosure Control (SDC). This reduces re-identification risk. HDX uses the open-source tool sdcMicro. The Centre for Humanitarian Data’s [Guidance Note on SDC](https://centre.humdata.org/guidance-note-statistical-disclosure-control/?_gl=1*j95yp3*_ga*OTU2MzMzNjgxLjE2NzQ2OTkwMzc.*_ga_E60ZNX2F68*czE3NjMxMDEyNTQkbzQ1OCRnMSR0MTc2MzEwMTMxMCRqNCRsMCRoMA..) outlines the process, tools, and best practices for managing microdata responsibly.

#### Check the quality of the data before publishing

Key dataset preparation tips to consider:

* **File naming:** Use descriptive filenames (e.g. population\_by\_admin2\_2024\_Q1.csv) to help users understand what each file contains. Write a clear dataset title and description.
* **File formats:** Use open formats like CSV, XLSX, Geotiffs, GeoJSON or shapefiles where possible and try to avoid proprietary formats. Please note that a PDF file is not data. If you wish to share documents, graphics, or other types of humanitarian information that are not related to the data you are sharing, please visit [ReliefWeb](https://reliefweb.int/).
* **File sizes:** If your resource is a link to a file hosted elsewhere, there is no size limit. If you are uploading a file onto HDX we recommend that you keep file size to under 300MB. If you have larger files that you want to share, email us at <hdx@un.org>.
* **Structure:** Use clear, consistent column headers. Do not mix data types in a single column. Avoid merged cells or heavy formatting.
* **Clarity:** Ensure clear caveats and limitations are explained and documented. Provide a link to the methodology, codebook, data dictionary or any existing documentation that can help the user make the best use of your data.
* **P-codes:** Where appropriate, use [p-codes](https://knowledge.base.unocha.org/wiki/spaces/imtoolbox/pages/222265609/P-codes?_gl=1*1omi4so*_ga*OTU2MzMzNjgxLjE2NzQ2OTkwMzc.*_ga_E60ZNX2F68*czE3NjMxMDEyNTQkbzQ1OCRnMSR0MTc2MzEwMTQwOCRqNTgkbDAkaDA.) to ensure interoperability. You can access the global p-code list here: [Global P-Codes Dataset](https://data.humdata.org/dataset/global-pcodes).

#### Check the quality of the metadata before publishing

Prepare metadata carefully. Accurate and complete metadata helps users find, understand and trust your data.

Here are the most important metadata fields to complete:

* **Description:** Provide specific details about the dataset, including its purpose, context, and potential use.&#x20;
* **Source of the data:** Clearly name the entity that created or collected the data.
* **Time period covered:** Add the start and end dates that apply to all files in the dataset.
* **Expected Update frequency:** Indicate how often the data is expected to be updated (e.g. daily, monthly, quarterly, never). The dataset will show a green leaf mark when it is up to date based on the update frequency provided and on the time period end date. Data maintainers will receive reminders to update based on this frequency.
* **License:** Confirm you have the right to share the data and select an appropriate open data license.
* **Methodology:** Briefly explain how the data was  collected or produced. Link to related documentation if available.
* **Tags and locations:** Add tags and geographic locations..

## Getting data onto HDX

There are two ways to publish data on HDX:

* Manually
* Programmatically&#x20;

#### Publishing data on HDX manually (how to use the share data form)

To publish manually, you will need to upload the data file directly to the HDX platform through the share data form, following the steps outlined below:  &#x20;

Please note, to add data, you must be logged in and belong to an HDX organization with publishing permissions. To start, click on ‘Add Data’ from anywhere on HDX.

{% stepper %}
{% step %}
**Choose how you want to share your data**

<div align="left" data-full-width="false" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FNZBfTvqWepRmrO77hUWA%2Fshare_data_options.png?alt=media&amp;token=ded09afe-4eec-420a-93ae-02b53f096d4d" alt="" width="563"><figcaption><p>Choose how to share</p></figcaption></figure></div>

You have three options:

**Public:** Data is published openly on the platform.

**HDX Connect:** Only the metadata will be available on HDX and no files will be uploaded to the platform. If selected you only need to complete steps 1, 2, 3 and 7.

**Private:** Data is only visible to members of your organization.
{% endstep %}

{% step %}
**Describe the dataset**

Provide a clear and concise Title and Description for your dataset.

<div align="left" data-full-width="false" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FY2zfyAGTmNLTl3jt8rAJ%2FDescribe%20dataset.png?alt=media&amp;token=51436fb4-9e34-467e-8c37-d77cb8fda98e" alt="" width="563"><figcaption><p>Describe dataset</p></figcaption></figure></div>
{% endstep %}

{% step %}
**Include additional information**

Provide additional information to help users of HDX understand the origins and limitations of your data.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FzvBtPR3P2C4KQFSsTYzF%2F3%20add%20info.jpg?alt=media&amp;token=a273501f-ca9c-4929-bbc3-e3ec4fe86627" alt="" width="563"><figcaption><p>Add additional information</p></figcaption></figure></div>

**Source:** The source of the data is the entity that collected or created it, rather than the organization that published the data. Use acronyms rather than full names of the source where possible. In cases where there are multiple sources, list all the sources separated by commas. Enter ‘Multiple sources’ in this field if the list of sources is long, over five sources.

**Organization:** The organization sharing this dataset on HDX.

**Maintainer:** The data maintainer is the point person for a specific dataset. They will receive any messages from users who have questions or comments about that dataset.&#x20;

**Time Period:** The time period covered by the dataset or the data collection period. This time period should cover all files in the dataset, from the earliest start date to the latest end date.&#x20;

**Update Frequency:** Choose how often this dataset is expected to be updated on HDX.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F7XhTH46HJ7Oa7UPT64su%2Flocation.jpg?alt=media&amp;token=14d59fa4-6646-4d39-9742-8c62d74ff5bd" alt="" width="563"><figcaption><p>Location and Licence</p></figcaption></figure></div>

**Location:** Detail the location(s) or countries  that this dataset covers.

**License:** Choose the license under which the data can be used. In general, we recommend the CC BY-IGO or CC-BY licenses for data on HDX, as they allow others to use data freely as long as they credit your organization.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FZqbyTYJ16dL08UfbkR6B%2Fmeth%20and%20tags.jpg?alt=media&amp;token=79f6984c-0bef-4932-a70a-1766fef1916e" alt="" width="563"><figcaption><p>Methodology, Caveats and Tags</p></figcaption></figure></div>

**Methodology:** Select how this data was collected or generated.

**Caveats / Comments:** Note any limitations or special considerations that relate to this data.

**Tags:** Add tags to help others find your dataset. Tags are auto-generated from an [approved list](https://docs.google.com/spreadsheets/d/1fTO8T8ZVXU9eoh3EIrw490Z2pX7E59MhHmCvT_cXmNs/edit?gid=1261258630#gid=1261258630).
{% endstep %}

{% step %}
**Click the ‘Add more files’ button**

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FJd9WDXTTftI44byw2foS%2F4%20add%20files.jpg?alt=media&amp;token=3c73b4d4-3721-415d-a903-7552cc1d6059" alt="" width="563"><figcaption><p>Upload files</p></figcaption></figure></div>

The files you add here will be published in a list, in the order you arrange them. You can upload multiple files by clicking the ‘Add More Files’ button. Order the files to  ensure that the latest resource is the first file. We accept all machine readable data formats but only offer preview features for: CSV, TXT, XLS, JSON, zipped shapefiles, KML, and GeoJSON.\
\
There are a number of ways to upload your file (s):

**Upload file (default):** You can drag and drop files from your computer into HDX. Select your files and drop them into the light grey upload area. A new dataset form will open with some fields pre-filled based on your files. You can also click ‘Browse’ and locate the files you want to upload.

**Import from URL:** HDX can host your data directly, but it works equally well with externally hosted data. If your organization already has a platform, API, or repository for downloads, you can include a link to that file as a resource in your HDX dataset. The HDX version will automatically point to the live version, keeping everything up to date without re-uploading files.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FjYzCUVPKdoDQTVh0KsJQ%2F4%20import%20detail.png?alt=media&amp;token=0c431b37-02ba-40b9-a551-dbdf4b7e3afa" alt="" width="563"><figcaption><p>Upload files - Import from URL</p></figcaption></figure></div>

1. Add URL to Remote file location. (mandatory)
2. Input File name and File format (mandatory)
3. Add notes about this file (optional)
4. Check ‘contains personal data’ if the data includes information that could identify people.
5. Check ‘contains Microdata’ if the data includes information such as detailed survey responses or disaggregated needs assessment data.

**Dropbox:** HDX can link to and preview files stored in Dropbox, including CSV or XLS files. To do this:

1. Log in to Dropbox via the web
2. Locate and select the desired file
3. Click “Share link” and copy the generated link

Dropbox links usually end in dl=0. To ensure the file is downloadable and previewable in HDX, change dl=0 to dl=1 before adding it to the dataset. For example: <https://www.dropbox.com/etc/etc/your_file_name.csv?dl=1>

The HDX resource will reflect updates made to the original file as long as the filename and path stay the same.

**Google Drive:** To share data from Google Drive, make sure your files are set to be publicly visible or accessible via link.&#x20;

How to make a file shareable in Google Drive:

1. Open Google Drive and locate the file you want to share.
2. Right-click the file and select ‘Share’.
3. In the pop-up window, under General access, click the dropdown menu.
4. Select ‘Anyone with the link’ and choose ‘Viewer’.
5. Click Copy link to get the shareable link.
6. Click Done.

In HDX, select the Google Drive option. A pop-up window will let you browse and select your files. These files aren’t copied to HDX, the Download button on HDX will link directly to the live version on Google Drive.

The HDX Resource Picker will only access your Google Drive file list during the file selection process. You can revoke this access anytime through the Google Drive App Manager, although this won’t affect files already published on HDX.
{% endstep %}

{% step %}
**Click the tick box to enable automatic data previews (Optional)**

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F6UitftHuHRXocdhwRCF0%2F5%20previews.jpg?alt=media&amp;token=74048131-41ae-472f-bcd5-c93e58a22408" alt="" width="563"><figcaption><p>Add automatic Data Previews and other data visualizations</p></figcaption></figure></div>

1. \[check box] Enable Data Preview.
2. Select the file to preview - the default selection is the first resource.
3. Add link to other data visualizations (Optional).\
   \
   If you have published visualizations of this data elsewhere, these can be embedded on the HDX dataset page, e.g., the URL (only URLs starting with ‘https’ are supported; embed code cannot be used) from a public PowerBI dashboard. Your visualization will appear under ‘Interactive Data’ above the files you have shared. Go back to edit if you would like to add more or remove the existing data visualization.<br>
4. Click the tick box to confirm the dataset does not contain personal data or otherwise violate the HDX Terms of Service.
   {% endstep %}

{% step %}
**Click submit dataset**
{% endstep %}
{% endstepper %}

## Publishing data by API&#x20;

If you manage frequently updated datasets, you can automate publishing and updating data through the HDX Python API. This library, built by HDX, offers a simple, Pythonic way to interact with the HDX endpoints. It makes it easier to push, pull, and manage datasets programmatically.

Why share data via HDX Python API?

* Automatically manages metadata structure for HDX datasets and resources
* Integrates easily into existing ETL or data pipeline workflows
* Simplifies code for dataset and resource creation and updates

See full documentation [here](https://hdx-python-api.readthedocs.io/en/latest/) in the HDX Python API Library. You can also find the HDX Github organization [here](https://github.com/ocha-dap?q=scraper\&type=all\&language=\&sort=) with a list of example scrapers that use the HDX Python API to get data onto HDX.

We are in the process of expanding our technical documentation to include step-by-step examples of how to use the HDX development tools, such as the Python API. These resources will help users better understand how to automate updates and integrate data pipelines with HDX.

### Preparing your data for Tabular Data Endpoints <a href="#docs-internal-guid-51c98ba6-7fff-2dc2-935e-96873081ca6d" id="docs-internal-guid-51c98ba6-7fff-2dc2-935e-96873081ca6d"></a>

Below are guidelines to help you prepare your datasets on HDX for Tabular Data Endpoints (TDE). These recommendations support better structure, stability, and interoperability on HDX.

**File format:** Upload tabular data as CSV files. XLSX, ZIP, merged cells, footnotes, and comments are not supported by the TDE ingestion process.

**Column headers:** The first row of each CSV file should contain column headers only. Do not include secondary header rows, such as HXL tags. If your files include HXL tags, remove so that the first row is the sole header row.

Where possible, use clear and human-readable column names with consistent naming conventions (for example, underscores or spaces as separators, full words rather than acronyms).

**Row content:** Each row should represent an individual data record. Remove any total, subtotal, or summary rows before uploading.

**Data update pattern:** We recommend overwriting the same resource over time rather than creating new resources for each update. Append new rows to the existing file while keeping the same schema (no columns added, renamed, or removed) and replace the resource. This keeps the resource\_id stable, which means downstream users can continue querying the same API endpoint without updating their integrations.

Avoid creating new datasets or new resources for each reporting cycle, as this fragments data discovery and breaks API continuity.&#x20;

For more information on TDE, visit the [Build with HDX section](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints).

## After data is uploaded

#### P-Code Detector

The P-Code detector is a script that automatically identifies whether a dataset contains P-Codes. Once you upload a dataset, HDX will automatically analyze the files it contains and indicate the presence of P-Codes. If a resource is labeled “P-Coded: Yes”, it means our system has detected P-Codes in the file. With this feature, HDX now lets you search and filter datasets based on whether they contain P-Codes. If your dataset does not yet include P-Codes or you want to ensure interoperability, you can access the global P-Code list here: Global P-Codes Dataset. As of April 2025, the P-Code detector is compatible with all data formats that can be interpreted as tabular (such as geojson, shapefile, geopackage, json) It is not compatible with non-tabular formats like PDF or GeoTIFF. If you have uploaded P-Coded data but the label doesn’t appear or believe there is an issue with the P-Code detector, please reach out to us: <hdx@un.org>.

#### HDX Quality Assurance (QA) Process

When a new dataset is published on HDX, it goes through a quality assurance (QA) review to ensure it meets HDX standards for quality, completeness, and responsible data sharing.

Every resource is checked against standard QA criteria:

* Metadata completeness (title, description, source, dates, etc.)
* No  personally identifiable information
* File integrity (accessible, readable, appropriate format)

If it contains microdata, it will be placed Under Review while HDX assesses the disclosure risk before public release.

This process exists to ensure compliance with the [HDX Terms of Service](https://docs.humdata.org/about/hdx-terms-of-service), which prohibit the sharing of personal data.

What we do when data is Under Review

Datasets flagged as sensitive are placed Under Review and assessed for:

* Metadata completeness
* Relevance to humanitarian action
* File integrity
* Sensitivity (personal data, microdata, etc.)

Microdata is assessed in a secure environment and based on a disclosure risk threshold determined by the HDX team. The default global disclosure risk threshold is 3%, and the HDX team may adjust this threshold for specific datasets based on the content of the data and the response context. If the global disclosure risk is below the HDX threshold the dataset is approved for public sharing. If the risk is above the threshold, the HDX team will contact the data contributor. HDX works with the data contributor to reduce the risk by applying Statistical Disclosure Control or publishing via HDX Connect.

We can work with you to:

* Improve metadata or formatting
* Apply risk mitigation techniques to microdata
* Switch to HDX Connect if needed

#### **QA resources**

* [HDX QA Checklist](https://data.humdata.org/dataset/2048a947-5714-4220-905b-e662cbcd14c8/resource/658d5c4f-1680-4cb5-9fbf-10a0a64e2c39/download/hdx-qa-checklist.pdf) - An overview of the quality criteria reviewed by the HDX team during the QA process.&#x20;
* [HDX Statistical Disclosure Control Process](https://humanitarian.atlassian.net/wiki/spaces/HDXKB/pages/1381498881/Statistical+Disclosure+Control+Process+to+handle+individual+survey+data+on+HDX) - An overview of why and how the HDX team applies Statistical Disclosure Control to all microdata uploaded on the platform.&#x20;

<br>


# Organizations on HDX

## What is an Organization on HDX? <a href="#docs-internal-guid-b6a9e434-7fff-4b03-9000-c40b4e88b740" id="docs-internal-guid-b6a9e434-7fff-4b03-9000-c40b4e88b740"></a>

Data on HDX is published and shared by organizations. These can be formal entities, such as a UN agency, NGO, government body, research institute, or private sector partner, or an informal group, such as an Information Management Working Group. All organizations are vetted by the HDX team to ensure they are trusted sources of relevant data. &#x20;

## Features of Organizations

Organizations on HDX provide:

<table data-header-hidden data-first-column-sticky data-full-width="false"><thead><tr><th width="263"></th><th></th></tr></thead><tbody><tr><td><strong>Data management</strong></td><td>Upload, edit, and manage datasets with role-based permissions to control who can publish and modify content.</td></tr><tr><td><strong>Organization page</strong></td><td>Branded space with logo, description, and datasets (public, private, or metadata-only).</td></tr><tr><td><strong>Team collaboration</strong></td><td>Add team members with Administrator, Editor, or Member roles to manage data collectively.</td></tr><tr><td><strong>Contact the data contributor</strong></td><td>The 'Contact the contributor' feature on every dataset page allows registered users and HDX to send emails directly to the person who uploaded the dataset. </td></tr><tr><td><strong>Internal group messaging</strong></td><td>The 'Group message' feature enables members of the same organization to message each other from dataset pages (both public and private). You can send messages to all members or filter by role (for example, administrators or editors). Messages are internal and not visible to users outside your organization.</td></tr><tr><td><strong>Performance tracking</strong></td><td>Access statistics on dataset downloads, page views, and visitor metrics.</td></tr><tr><td><strong>Private data sharing</strong></td><td>Share datasets only with organization members.</td></tr><tr><td><strong>Visibility and credibility</strong></td><td>Build trust through a verified presence on HDX, making it easier for users to discover and assess your data. Request custom-branded pages with your colour scheme, topline figures, and optional data visualizations.</td></tr></tbody></table>

#### Understanding the Organization Page

Every organization on HDX has a dedicated page featuring its logo, description, and a list of the datasets it has published (public and metadata-only via HDX Connect). Users can subscribe to receive email alerts about dataset changes via 'Get Notified'.&#x20;

Tabs provide access to different functions:

* **Datasets:** All public datasets published by the organization.
* **Activity Stream:** Recent updates or uploads.
* **Stats:** Downloads and page view metrics for the organization’s datasets.

More tabs are available when you are a member of an organization.

#### Why Organizations are required on HDX

HDX requires data to be published through organizations for two reasons:&#x20;

1. **Authorization and control:** Only organization members with appropriate roles can upload, edit, or manage datasets, ensuring accountability and transparency.&#x20;
2. **Search and discovery:** HDX follows a content hierarchy (Organization → Dataset → Resource) that helps users understand the source of the data, assess credibility, and explore related data published by the same organization.

#### Organizational structures

HDX supports different organizational structures:

* **Centralized - Single page:** Some groups, like IOM, choose to consolidate all data under one organization page. This simplifies management and provides a unified view of their contributions across countries or thematic areas.
* **Decentralized - Multiple pages:** Others, like UNICEF, maintain separate pages on HDX for each country office, enabling more localized data management and visibility.

The choice depends on your internal structure, workflows, and how you want to present your data. During the onboarding process, the HDX team can advise on the best setup.&#x20;

#### Membership roles and permissions

HDX organizations have three different membership roles with varying levels of permissions to control their organization page on HDX.

<table data-header-hidden data-first-column-sticky data-full-width="false"><thead><tr><th width="459.5">Text</th><th width="158.5"></th><th width="131"></th><th></th></tr></thead><tbody><tr><td><strong>Permission</strong></td><td><strong>Member</strong></td><td><strong>Editor</strong></td><td><strong>Administrator</strong></td></tr><tr><td>View organization’s public and private dataset</td><td>☑️</td><td>☑️</td><td>☑️</td></tr><tr><td>Send group message to organization</td><td>☑️</td><td>☑️</td><td>☑️</td></tr><tr><td>Be the data maintainer</td><td></td><td>☑️</td><td>☑️</td></tr><tr><td>Add new dataset</td><td></td><td>☑️</td><td>☑️</td></tr><tr><td>Edit dataset</td><td></td><td>☑️</td><td>☑️</td></tr><tr><td>Delete dataset</td><td></td><td>☑️</td><td>☑️</td></tr><tr><td>Manage organization page</td><td></td><td></td><td>☑️</td></tr><tr><td>Invite users to organization</td><td></td><td></td><td>☑️</td></tr><tr><td>Change the role of a user</td><td></td><td></td><td>☑️</td></tr><tr><td>Remove a user from organization</td><td></td><td></td><td>☑️</td></tr><tr><td>Turn on/off “Request membership” option</td><td></td><td></td><td>☑️</td></tr></tbody></table>

The user who creates an organization is automatically assigned as an administrator. That person can invite other HDX users into their organization and assign them one of the three roles above, or registered users on HDX can request membership from the organization’s administrator(s). Organizations should have at least two administrators to ensure continuity in managing data and membership. It is good practice for the administrator(s) to review the member list regularly as all members are able to view private datasets and to grant users the minimum amount of permissions needed.

## Request membership of an existing organization

You only need to request membership of an organization if you plan to share data on its behalf. Regular HDX users don't need organization membership to access data.

{% stepper %}
{% step %}
**Log into your HDX account**\
Only registered users can request to join an organization on HDX.
{% endstep %}

{% step %}
**Click on your profile name on the top right of any page**
{% endstep %}

{% step %}
**Open ‘User Dashboard’**
{% endstep %}

{% step %}
**Scroll down and click on ‘My Organizations’**

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FQvu4uTTvh7sSYLVNWxJO%2Fdashboard%20join%20org.png?alt=media&amp;token=cc517d7f-393e-46fd-846d-998bf566eef0" alt="" width="563"><figcaption></figcaption></figure></div>

{% endstep %}

{% step %}
**Click the ‘Request to join an org’ blue button**

Alternatively you can request membership by logging into HDX, navigating to your organization’s page and clicking the Request Membership button. If the Request Membership button is not visible, the organization is a closed group and not accepting new members at this time.

What happens next:

* The request is reviewed by an administrator
* If your request is successful, the admin assigns your role based on responsibilities
  {% endstep %}
  {% endstepper %}

## Create a new organization on HDX

{% stepper %}
{% step %}
**Log into your HDX account.** \
Only registered users can request to create a new organization.
{% endstep %}

{% step %}
\*\*Open: <https://data.humdata.org/org/request/new**\\>
If you are not logged in, you will see an error page.
{% endstep %}

{% step %}
**Fill in the new organization request form**&#x20;

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FBnyB9XmTcMl93D12fBBM%2Fcreate%20new%20org%201.png?alt=media&amp;token=78803191-36d6-471c-b6b0-84ac83a904b2" alt="" width="563"><figcaption><p>Request to create a new organization form</p></figcaption></figure></div>

* Organization name;
* Description of the organization including its focus, location and activities;&#x20;

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2ForcXp3SuyD9Mw95J5dPN%2Fcreate%20new%20org%202.png?alt=media&amp;token=05d42323-383a-4910-90db-13777446fc92" alt="" width="563"><figcaption><p>Request to create a new organization form</p></figcaption></figure></div>

* Website link;&#x20;
* Your role within the organization; &#x20;
* Type of data your organization would like to share;&#x20;
* Whether the data is already publicly available and where.
  {% endstep %}

{% step %}
**Click submit**

The HDX onboarding team will review your request and then either approve it or ask for more information (such as a sample dataset) by email. Approved organizations will remain inactive until at least one dataset has been shared through HDX.&#x20;

Custom-branded pages: HDX offers custom-branded organization pages that include your organization’s logo, color scheme, topline figures, an optional data visualization, and a list of all your shared datasets. To request customization, please email <hdx@un.org>.
{% endstep %}
{% endstepper %}

## Managing organization members

Administrators can manage members from the Members tab on the organization page.

#### How to invite a new user

1. Open the Members tab
2. In the right column, enter the email, name, or username under ‘Add / invite colleagues to this organization’
3. Select the role (Admin, Editor, Member)
4. Click submit

If they are already registered on HDX, they will be added immediately. If not, they will receive an email invitation.

#### How to remove a user

1. Open the Members tab
2. In the left column, click ‘Remove from this organization’ next to their name
3. Click confirm

Users who are data maintainers must have their datasets reassigned before removal. If you are the only admin for your organization and want to change the role or remove yourself from the organization, you will be asked to assign the admin role to at least one existing member of the organization.

#### How to change a user’s role

1. Open the Members tab
2. Click ‘Change role’ next to their name
3. Click submit

Users who are data maintainers cannot be changed to Member status until datasets are reassigned. Organizations must always have at least one Administrator.

#### Responding to membership requests

By default, organizations on HDX are open, which means any registered user can request to join. Requests are:

* Sent to all administrators via email
* Displayed as notifications on HDX

The first administrator to respond determines the outcome, approve or decline. Once a decision is made, other admins are not notified again. All members of your organization, regardless of role, can view your private datasets. Only approve requests from users you can verify, such as via staff directories or trusted contacts.

#### Making your organization a closed group

As administrator, if you prefer not to allow membership requests, you can make your organization a closed group.

1. Go to your organization’s page
2. Click the Edit button under the organization logo
3. Uncheck Allow Membership Requests
4. Save changes

Once disabled, the Request Membership button disappears and only admins can add new members.

## Understanding how your data on HDX is used

HDX provides metrics that help you track the visibility, popularity and reach of your datasets on the platform. These insights are useful for internal reporting, demonstrating value to donors, or deciding which datasets to prioritize for updates.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F5fNKYx5lmPvt55gYwEQd%2FScreenshot%202026-09-14%20at%2016.11.22.png?alt=media&amp;token=b7d65e82-8ef8-4b7e-b68a-870b4a496d6b" alt="" width="563"><figcaption><p>Stats dashboard</p></figcaption></figure></div>

Organization data performance can be accessed under the Stats tab.&#x20;

* Total number of downloads for the organization's content&#x20;
* Number of downloads by dataset (last 24 weeks)
* Downloads and total page views (last 24 weeks)
* Unique visitors who downloaded datasets from this org (last 30 days)
* Unique visitors to this organization's content (last 30 days)

HDX provides a downloadable file with monthly statistics for administrators of an organization.

1. Navigate to your organization’s page on HDX and log in
2. Click the Stats tab
3. Click the XLSX link (top left of the stats dashboard)&#x20;

This file includes monthly stats on downloads and page views of your data for the current year and previous years, along with a README containing more detailed information. Data is updated on the first day of each month. The coverage period includes monthly data for the current year (January to December) as well as the previous four years. HDX sends emails with annual stats each January, and quarterly stats to the most popular organizations on HDX.&#x20;


# Maintaining data

## What maintaining data means

Maintaining data on HDX is the process to ensure datasets are kept accurate and up-to-date throughout their lifecycle. This includes updating files when new information becomes available, correcting or improving metadata, monitoring alerts from HDX, responding to requests for underlying data, and making sure each dataset has a person assigned to oversee its quality and relevance (referred to as a ‘data maintainer’).

## Why maintaining data matters

Maintaining your data on HDX is essential to ensure it remains useful, accurate and reliable for humanitarians.  By regularly reviewing and updating your data you can make sure that HDX remains a source for reliable and high-quality humanitarian data.

This section explains the following key tools and processes that help you manage and maintain your data on HDX:

* The User Dashboard and My Datasets tab
* Understanding alerts through the notifications bell
* How to edit or update a dataset
* The role of data maintainers and how to manage them
* How to respond to HDX Connect data requests
* How and why datasets are archived on HDX

## The User Dashboard

The User Dashboard is your central workspace on HDX for managing and maintaining data. It brings together the datasets you maintain, your organization memberships, data requests, and updates from across the platform.

To access the User Dashboard, click on your name in the top banner of any page.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FZRddrYvkPdhtg9EtdRB0%2Fuser%20dashboard%201%20use.jpg?alt=media&amp;token=35209514-4b2c-48db-80d5-bac28c2d40e7" alt="" width="563"><figcaption><p>Access the User Dashboard</p></figcaption></figure></div>

**Newsfeed**

The Newsfeed displays recent activity across HDX, including updates to datasets you follow and changes made by HDX system bots. HDX bots perform automated background checks, maintenance and updates, such as metadata validation, to help maintain consistency and data quality across the platform.

**My Datasets**

To view the My Datasets tab click on your name in the top banner and scroll down to User Dashboard. The My Datasets tab shows all datasets that you maintain on HDX, and their update status.

From this page, you can quickly see which datasets are up to date, which need attention, and which have outdated metadata. Filters on the left help you narrow results by update status, location, or file format.

Each dataset listed displays information such as:

* Time period of the dataset
* Expected update frequency and warning if the expected update date has passed
* Links to edit or delete the dataset

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FZkGrfOyZL2gyQ00Wkhql%2Fuser%20dash%20new.jpg?alt=media&amp;token=9d541166-d4cf-46f6-bdc8-fab1c8ad2313" alt="" width="563"><figcaption><p>My Datasets Tab</p></figcaption></figure></div>

**HDX Connect Requests**

The HDX Connect Requests tab is where you manage all HDX Connect (by request) data access requests. Learn more about [HDX Connect](/publish/publish-data/preparing-and-publishing-data#controlled-access-publishing).

There are three sections:

* **New:** Requests you have not yet responded to
* **Open:** Requests you have replied to but not archived
* **Archived:** Previously completed or declined requests

From here you can reply, decline, track your response to previous requests, and/or reopen past requests.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F5PeEZju2QIEcsnKfXCkr%2Fmy%20HDX%20connects%20dashboard.png?alt=media&amp;token=502a8d1c-3437-4f6b-a3cc-ac00270d2116" alt="" width="563"><figcaption><p>HDX Connect Requests Tab</p></figcaption></figure></div>

## The Notifications Bell

The notifications bell in the top header of HDX alerts you to important actions that require your attention.&#x20;

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F8C8hlY5ayDmsQoFsIGRd%2Fnotifications%20bell.png?alt=media&amp;token=239198a5-8e0f-4b6e-bf57-94dd935189c6" alt="" width="563"><figcaption><p>Notifications Bell Location</p></figcaption></figure></div>

When a red dot appears, it means you have new notifications related to:

1. Datasets needing updates based on their expected update frequency
2. Pending HDX Connect requests for datasets you maintain
3. Quality Assurance updates, such as datasets placed Under Review
4. Messages or activity related to your organization’s datasets

Click the bell to open the notifications panel, where you can view all alerts and sort as needed. Take action by navigating directly to the pages. This feature helps data maintainers to quickly respond to requests, keep their data up-to-date, and stay informed about QA-related actions.

## How to edit or update a dataset on HDX <a href="#docs-internal-guid-9f60ea79-7fff-3424-04e5-21df3f341a54" id="docs-internal-guid-9f60ea79-7fff-3424-04e5-21df3f341a54"></a>

HDX will notify you when a dataset you maintain needs to be updated. To review these alerts, click the notifications bell icon in the top header. An example notification is shown below, where five datasets need to be updated. Please note the notifications bell is not connected to the notifications feature. Learn about the [notifications feature](/find/staying-up-to-date-with-hdx#hdx-notifications).

**Common reasons to update your dataset on HDX**

* The data is out-of-date, one of the most frequent triggers for updates
* There are  new resources to add
* The metadata needs correcting
* The  sharing level needs to change, ex. public to private

### **How to manually edit a dataset on HDX**

The Edit button appears just below your organization’s logo on the dataset page.

{% stepper %}
{% step %}

#### Click Edit

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F8bG4J6tSBtBKcRXCe17y%2Fedit%20dataset.png?alt=media&amp;token=38c39f82-3845-4af2-b669-4e367ca6ab7e" alt="" width="563"><figcaption><p>Edit Dataset</p></figcaption></figure></div>

You can only edit a dataset if you are an [administrator or editor](/publish/publish-data/organizations-on-hdx#membership-roles-and-permissions) of the HDX organization. If you are logged in, and have the appropriate role,you will find an ‘Edit’ button just below the organization logo.
{% endstep %}

{% step %}

#### Make changes in the Edit data form

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2F4HQpvFwuUEAly8O3bkgg%2Fedit%20data%20form%201.jpg?alt=media&amp;token=2bb44cca-27ce-4050-86b8-6c8fb8b8cc7b" alt="" width="563"><figcaption><p>Edit Data Form</p></figcaption></figure></div>

The edit form contains the same details in the [share data form](/publish/publish-data/preparing-and-publishing-data#publishing-data-on-hdx-manually-how-to-use-the-share-data-form).

Common edits include:

* Updating the title or description
* Updating the time period or adding files when new data becomes available
* Correcting or expanding metadata fields
* Assigning a new data maintainer if responsibilities have changed
* Changing the sharing level (e.g., private, public, HDX Connect) after reassessing sensitivity or internal policy
* Replacing links to remote files that have moved or expired (example: Google Drive)
  {% endstep %}

{% step %}

#### Check the tick box to confirm the dataset does not contain Personally Identifiable Data (PII) or violate the HDX Terms of Service.&#x20;

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FTetMzXTKWzd3DgA2mr4n%2Ftick%20consent.jpg?alt=media&amp;token=2c80bda9-8435-46d5-8b0a-7025e12d64cb" alt="" width="563"><figcaption><p>Confirm and Submit </p></figcaption></figure></div>

\[Important!] You must check the data sensitivity box before submitting your dataset. This confirms that you have reviewed the data and that it is safe to publish on HDX. Learn more about [assessing sensitive data here](/publish/publish-data/preparing-and-publishing-data#is-the-data-safe-to-publish).&#x20;
{% endstep %}

{% step %}

#### Click Submit Dataset

If your dataset is updated programmatically through a pipeline, refer to our Github repository to learn more about the Python functions: <https://github.com/OCHA-DAP/hdx-python-api>
{% endstep %}
{% endstepper %}

### Understanding dataset maintainers <a href="#docs-internal-guid-9cda8a53-7fff-a83f-125d-9e231b0af875" id="docs-internal-guid-9cda8a53-7fff-a83f-125d-9e231b0af875"></a>

Every dataset on HDX must have a designated data maintainer. They provide a point of contact for users, receive update reminders, and are responsible for keeping the dataset up-to-date. It is important that organizations review their data maintainers, ensuring continuity as teams change. Without an assigned maintainer, requests may go unanswered and datasets can quickly become outdated.

Dataset maintainer role:

* Update datasets when new versions are available.
* Respond to user questions via “Contact the Contributor.”
* Receive HDX Connect requests and decide whether data can be shared.
* Ensure responsible data sharing, including sensitivity checks and metadata accuracy.

**How to reassign a data maintainer**

If a team member leaves an organization (or moves roles) their datasets must be reassigned to a new data maintainer. To reassign a maintainer:

1. Open the dataset
2. Click Edit
3. Scroll to the Maintainer field
4. Select a new person from the dropdown list (must be a member of the organization on HDX)
5. Save changes by clicking Submit Dataset

Maintaining an active data maintainer is required to ensure accountability and continuity. If a new maintainer is not assigned, the HDX team will contact the organization’s administrators to flag the issue and request that one be added. If a new data maintainer cannot be assigned after follow-up, the dataset may be archived to maintain data quality and governance standards on the platform.

## Managing HDX Connect requests <a href="#docs-internal-guid-050bfc61-7fff-6c01-eecc-dc1706be7a6c" id="docs-internal-guid-050bfc61-7fff-6c01-eecc-dc1706be7a6c"></a>

When a metadata-only dataset is published using HDX Connect, registered HDX users can request access to the underlying data. The dataset maintainer is responsible for reviewing and responding to these requests through the organization dashboard.

### How to review and respond to user requests

{% stepper %}
{% step %}

#### Review the request

You will receive an email notification when someone requests access to one of your HDX Connect datasets.

The email will include:

* Requester’s name, email, location, and organization
* The dataset name
* The requester’s intended use
* Their message explaining why they need the data

To respond:

* Click the “My Requests” link in the email OR
* Click the red notification dot next to your username in the HDX header
  {% endstep %}

{% step %}

#### Manage requests on the My Requests page

The My Requests page displays all requests for the data on HDX you maintain. The page has three sections:

* **New**: New, unanswered requests that require your action.
* **Open**: Requests you have replied to, but have not yet archived. The request will remain “Open” until you close the ticket and it is archived. Please close all open tickets once action is taken to ensure that we can effectively track requests.
* **Archived**: Requests you declined or previously closed. You can reopen archived requests if needed.

For each request, you will see the dataset name, the requester’s user details, and their reason for requesting the data, alongside ‘reply’ or ‘decline’ buttons.&#x20;
{% endstep %}

{% step %}

#### Respond to the request

As the data maintainer, you have two options. You can either reply (to share the data or ask follow-up questions) or decline the request

#### **If the data maintainer chooses to share the data or discuss further**

Please note that HDX does not host or share the requested data. The data is shared directly between your organization and the requester, outside of the HDX platform. Sensitive data should always be shared through a secure channel. Share passwords separately, using a different secure channel. For more on [responsible approaches to data sharing](https://centre.humdata.org/data-responsibility/).

1. **Click Reply to open the response form.**

In your reply:

* Explain how you will share the data (e.g., encrypted email, secure transfer)
* Ask any clarification questions if needed
* Include any instructions the requester must follow

2. **Click Submit when finished.**&#x20;

The request will stay in Open status until you manually archive it.

#### If you choose to decline the request

1. **Click Decline.**

You will be prompted to:

* Provide a brief explanation of why the data cannot be shared

Once submitted:

* The request is automatically moved to Archived

HDX tracks whether a request is approved or declined, but does not track the content of your messages.
{% endstep %}

{% step %}

#### Keep track of shared data

In the Open section, HDX displays Yes/No buttons to track whether you have shared the data\
with the requester. This helps your organization monitor its data-sharing actions over time.
{% endstep %}
{% endstepper %}

## Archiving data on HDX <a href="#docs-internal-guid-e4bdb5bb-7fff-f46c-7a69-eb0f4507d7dd" id="docs-internal-guid-e4bdb5bb-7fff-f46c-7a69-eb0f4507d7dd"></a>

To keep HDX a reliable and up‑to‑date resource for humanitarian data, older datasets that are no longer operationally relevant are periodically archived by the HDX team. Archiving ensures users can more easily find current data while still offering access to older datasets for research or historical analysis. Archived datasets remain available and searchable under Products in the header and footer and at the bottom of the search filter. They are excluded from the main dataset listings by default.

<div align="left" data-with-frame="true"><figure><img src="https://1333625253-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5R1HHSyBWYO1CsgBEPUp%2Fuploads%2FGsaU2RVRnqbIVL5dnNQC%2Farchvied%20datasets.png?alt=media&amp;token=91313092-10c2-479c-89cd-c7d8a2a393a3" alt="" width="563"><figcaption><p>Archived Datasets</p></figcaption></figure></div>

**When and how are datasets archived?**

The HDX team reviews datasets on an annual basis and applies both automated and manual checks to identify which should be archived. Archived datasets typically meet the following criteria:

* Created more than five years ago
* Reference period ended more than five years ago
* Fewer than 1,000 total downloads
* Not categorized as requestable (HDX Connect)

Certain datasets and organizations are exempt from archiving, including [Common Operational Datasets (CODs)](https://data.humdata.org/cod), and organizations with historical data that are still operationally relevant such as World Bank development data. If a dataset is archived and later found to be relevant again, the owning organization can request to unarchive it at any time.


# HDX support

We have a global team who are here to advise and support you in preparing and publishing data on HDX. If you have questions or run into issues, reach out to us at <hdx@un.org>.

Our documentation helps you navigate common questions, including what data you can publish, how to choose the right license, manage sensitive data, use HDX Connect, and how to upload by API.

<br>


# Build with HDX

Build with HDX provides developers and data teams with the tools, APIs, and documentation needed to access, integrate, and extend humanitarian data.

This section is designed to help you explore how HDX can be used in your own tools and workflows. Here you will find examples, testing guides, and explanations of the core technical concepts behind HDX. Whether you are building applications, running analysis, or connecting HDX datasets to your data pipelines, this space will guide you through the essentials.

*The material here is evolving and will expand over time as we refine it together with our users.*

### GitHub and technical links

Our GitHub organization can be found [here](https://github.com/OCHA-DAP). See popular repositories below:

1. [hdx-python-api](https://github.com/OCHA-DAP/hdx-python-api): Python library providing easy APIs to push and pull datasets from the HDX platform.
2. [hdx-ckan](https://github.com/OCHA-DAP/hdx-ckan): HDX‑CKAN custom configuration and extensions built on CKAN for the HDX platform.
3. [hdx-python-utilities](https://github.com/OCHA-DAP/hdx-python-utilities): Provides a range of helpful utilities for Python developers.&#x20;
4. [hdx-python-country](https://github.com/OCHA-DAP/hdx-python-country): Utilities to map between country and region codes and names and to match administrative level names from different sources.
5. [rhdx](https://gitlab.com/dickoa/rhdx): R package to interact with HDX.


# HDX core concepts

Essential HDX concepts referenced throughout products and integrations.

### API tokens

An API token is a unique key that authenticates users when making requests to HDX programmatically. It works like a password for the API, allowing you to create, update, or delete data depending on your permissions. Permissions are dependent on your level of access to various organizations (admin, editor, or member).&#x20;

API tokens are connected to your HDX account and must be kept secure. Never share them publicly as they also allow *write* functionality.

#### Creating an HDX API token

* Sign into HDX [data.humdata.org](http://data.humdata.org/).
* Navigate to your profile settings in the top banner and select API Tokens from the dropdown.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FiUabsKw2j7CBhDZbCqHi%2Fbuild-apitoken.png?alt=media&amp;token=d0710e05-ff71-471b-864c-75aec2a0ac64" alt="" width="563"><figcaption><p>API Tokens</p></figcaption></figure></div>

* Select “Manage API tokens”, and then **generate your token**.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FkbCzoUXKgpVwBQjhKSvk%2FScreenshot%202026-01-22%20at%2011.03.16.png?alt=media&amp;token=034496be-2f5e-4425-9dfe-dd1c1dea2be3" alt="" width="563"><figcaption><p>Manage API Tokens</p></figcaption></figure></div>

* **Copy your token** (you will not be able to view it again) and save it either in your password manager or other secure location.

#### Data resources <a href="#data-resources" id="data-resources"></a>

On HDX, a *data resource* is an individual data file or API endpoint that belongs to a dataset. Each dataset can contain one or more resources, for example a CSV file, Excel spreadsheet, shapefile, or an API feed. Resources are the actual data objects that users download or query.To understand how resources fit into the overall structure of HDX, it helps to see their relationship to datasets and organizations:

**Relationship of HDX entities**

Organization

&#x20;          └── Dataset

&#x20;                              └── Resource(s)

* **Organization:** The publisher or owner of data (e.g., OCHA).
* **Dataset:** A collection of related information published by an organization (e.g., “Food Prices in Kenya”).
* **Resource:** The actual data file or service within a dataset (e.g., CSV file of market prices, shapefile of locations).

Each available HDX resource is identified by a **unique resource ID**, which you’ll need to include in API requests. Resource IDs are the form of a 36 character UUID, for example: `f3f203bf-d29b-4b88-a724-25ab32a67543`. You can find a resource ID through the dataset page UI, or by using the HDX metadata API.

**Finding a resource ID: Resource page**

You can locate a resource’s unique ID directly from its resource page in the HDX UI. Click on More Information next to the blue Download Button on any dataset page to view its Resource ID. Clicking the copy icon next to the ID will copy the full UUID to your clipboard, making it easy to use in scripts, API calls, or downstream analysis.

This is the quickest way to retrieve the exact identifier for a resource you want to query programmatically.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2Fyy7FnleHC0wUDzD6X7HJ%2FBuild-resourceID.png?alt=media&amp;token=dc4b9233-4164-41e5-9875-804a2a19cd90" alt="" width="563"><figcaption><p>Resource ID</p></figcaption></figure></div>

**Finding a resource ID: HDX Metadata API**

For predictable dataset names, you can also access `resource_ids` through the [HDX metadata API](https://data.humdata.org/dataset/2048a947-5714-4220-905b-e662cbcd14c8/resource/3b675846-d01c-4fc9-b577-b7d426d2a598/download/hdx-ckan-api-cookbook.pdf?_gl=1*mlbc9r*_ga*NjQxMDQxNjkxLjE3NDM2NzcxNjc.*_ga_E60ZNX2F68*czE3NTY3Mzg1MjUkbzE5MCRnMSR0MTc1NjczOTI5NSRqNjAkbDAkaDA.) endpoint which allows you to search the metadata of the data in our catalogue. See instructions below:

1. **Find the dataset name:** Go to the dataset page and find the name in the URL. You can also search using the HDX metadata API (see cookbook above) which can also generate the dataset name.
   1. Example: `https://data.humdata.org/dataset/`**`zwe-rainfall-subnational`**
2. **Retrieve package and resource metadata:** Use the `package_show` endpoint to fetch details about the dataset, including all its associated resources and the id. See example below.
   1. Example: `https://data.humdata.org/api/3/action/package_show?id=zwe-rainfall-subnational`
3. **Locate the resource in the response:** From the response, identify the resource that corresponds to the structured data you're interested in. There you will find the `resource_id`.

   1. Example:

   <div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FKmpij32VxU5OGwvf1a3y%2FScreenshot%202026-01-22%20at%2011.04.32.png?alt=media&amp;token=b282b499-d5ee-4e88-8261-647fbca8910d" alt="" width="563"><figcaption><p>resource_id</p></figcaption></figure></div>


# HDX API overview

The Humanitarian Data Exchange (HDX) API offers a set of endpoints that allows users to access, search, and interact with humanitarian data, as well as contribute through flexible and automated ways.

The endpoints are broken out into two main categories: **data read endpoints** for *accessing and using data* and **data write endpoints** for *uploading (creating) and updating data*. See diagram below explaining the different groupings of endpoints by use-case.

<div align="left"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2F6fIfnB1LFresuzoNTY7n%2Fimage.png?alt=media&amp;token=3cee54af-e711-48d9-8e4e-7c6cbd52eb8c" alt="" width="563"><figcaption></figcaption></figure></div>

See descriptions, endpoints, and product table when to use each API endpoint below.

## Data Read Endpoints

These endpoints show how to read and access data on HDX.&#x20;

### Metadata Endpoints

The metadata endpoints provide programmatic access to HDX metadata. It allows users to search, filter, and retrieve detailed information about organizations, datasets, and resources. This can be used for users to discover data and data contributors to programmatically automate data management.

See sample endpoints below:

* `package_search`
* `package_show`

See full information [here](https://docs.humdata.org/build/hdx-apis/metadata-endpoints).

### File Download

The file download allows full downloads of data resources on HDX. This can be used to programmatically access data resources but does not allow for large data handling or filtering.

See sample URL below:

* `https://data.humdata.org/dataset/<DATASET_ID>/resource/<RESOURCE_ID>/download/`

See information [here](https://docs.humdata.org/build/hdx-apis/file-download-endpoint).

### Tabular Data Endpoints

The Tabular Data Endpoints enable direct access to structured, tabular data resources on HDX. It supports both native and SQL queries, allowing users to filter, aggregate, and query data without downloading entire files. This is particularly useful for creating data pipelines, dashboards, and real-time data analysis.

See sample endpoints below:

* `datastore_search`
* `datastore_search_sql`
* `datastore_info`

See full documentation [here](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints).

## Data Write Endpoints

These endpoints let contributors publish and update data on HDX programmatically. All write operations require an HDX API token, managed under your user profile. The recommended tool is the HDX Python API wrapper; additional write endpoints are documented in the CKAN documentation.

For setup, code examples, and full guidance, see **Contributing Data**.

### Create Data Endpoints

The create endpoints allow contributors to programmatically create new datasets and data resources. They are used when onboarding new data or establishing an automated upload process for a pipeline. Files are uploaded directly to HDX, and associated metadata is registered under the dataset within an organization.

See **The HDX Python Library** for setup and create examples.

### Update Data Endpoints

The update endpoints allow contributors to modify existing datasets or resources on HDX. They are used for routine data refreshes and metadata corrections through data resource replacement in HDX and do not require the entire metadata schema dictionary.

See **The HDX Python Library** for update examples.

## Choosing the right API endpoint

Each HDX API endpoint is designed for a specific type of task. Use the guidance below to quickly identify which API best fits your workflow.

|             **If you want to…**             |            **Use this Endpoint**           |                                                  **Why**                                                  |
| :-----------------------------------------: | :----------------------------------------: | :-------------------------------------------------------------------------------------------------------: |
|        **Search or explore datasets**       |      `package_search`, `package_show`      | Ideal for search, filtering, and metadata retrieval. Provides dataset and organization level information. |
|           **Download data files**           |                  File URL                  |                Use the resource download URL returned in the metadata to fetch full files.                |
|            **Query data schemas**           |              `datastore_info`              |                                    Returns column names and data types.                                   |
|   **Query data tables and large datasets**  | `datastore_search`, `datastore_search_sql` |     Enables querying or filtering without downloading the whole file like in dashboards or pipelines.     |
|   **Run complex filters or aggregations**   |           `datastore_search_sql`           |          Use SQL syntax for flexible queries like aggregations, joins, or conditional filtering.          |
|       **Access spatial geo datasets**       |                  File URL                  |                     Returns full GeoJSON or vector data for mapping or GIS workflows.                     |
|      **Programmatically write to HDX**      |               HDX Python API               |                               Allows authenticated users to create datasets.                              |
| **Automate metadata or dataset management** |               HDX Python API               |                 Allows authenticated users to update existing datasets and data resources.                |

### Getting started tips

If you’re unsure which HDX API endpoint to start with:

* Start with **metadata endpoints** for discovery or metadata.
* If you want to access data (tabular and geodata), use the **file URL** to access the entire data resource.
* Move to **Tabular Data Endpoints** if you need to query inside the data resource or if you are working with large files.
* **\[Data Contributors]** Use **data write endpoints or the HDX Python API library** to programmatically create and update datasets within your organization.

## Additional programmatic services

HDX is built on CKAN, an open-source data management platform. While this page highlights the most relevant endpoints for HDX users, additional CKAN endpoints are available in the broader open-source [documentation](https://docs.ckan.org/en/2.9/api/).

HDX and the open-source community also maintain tools that extend these APIs, making integration and automation easier for contributors and developers.

* [**HDX Python Wrapper**](https://github.com/OCHA-DAP/hdx-python-api?tab=readme-ov-file)**:** A HDX supported Python library that wraps the metadata endpoints, making it easier to read, update, and publish datasets from scripts or pipelines specifically for HDX. This is our recommendation to push and edit data to HDX.
* [**HDX CLI Wrapper**](https://github.com/OCHA-DAP/hdx-cli-toolkit)**:** Built on the Python API as an open-source HDX contribution enabling basic operations (search, upload, download) directly from the terminal (Command Line Interface).
* [**HDX Metadata Endpoints Notebook:**](https://github.com/OCHA-DAP/hdx-metadata-endpoints-notebook) Example Python notebook showing how to call different endpoints and exploring HDX data.
* [**HDX Tabular Data Endpoints Notebook**](https://github.com/OCHA-DAP/hdx-datastore-api-python-quickstart)**:** Example Python notebook demonstrating API workflows, which may evolve into a lightweight Python package for analysis.

## Feedback and support

Our team reviews feedback regularly to improve the APIs and support the humanitarian data community.&#x20;

If you encounter issues, have suggestions for improvement, or need guidance using the APIs, please email us at <hdx@un.org>.

<br>


# File download endpoint

A guide to accessing, downloading, and integrating HDX data through the File URL.

## Introduction

The File URL endpoint allows you to download data from HDX directly in a programmatic way, without needing to use the HDX website. Leveraging additional endpoints like the HDX metadata endpoints further lets you access data without using the HDX UI. This approach is well suited for batch processing, scheduled pipelines, and integration with external tools that consume complete data resources directly. (For large data handling or filtering, use the Tabular Data Endpoints, link [here](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints)).

The HDX File URL endpoint is powered by the CKAN core API and relies on resource metadata to identify downloadable files.

The following documentation is intended for analysts and technical audiences who want to retrieve data files in a reproducible way, troubleshoot common issues, and integrate HDX data into automated workflows and tools.

## Building a File URL query

The file URL query is reproducible, granted you know the dataset ID and resource ID along with the format type.

<div align="left"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FOUYAZtMzQyLcoBHKpsD5%2Fconfig.png?alt=media&amp;token=c67004f7-2cb9-4ad7-9977-b76c22cf29c8" alt="" width="563"><figcaption></figcaption></figure></div>

See sample URL below. Replace the `dataset_id`, `resource_id`, `resource_name`, and `format` with your desired dataset.&#x20;

`https://data.humdata.org/dataset/<DATASET_ID>/resource/<RESOURCE_ID>/download/<RESOURCE_NAME>.`

## Feedback and support

We are always adding new data and features into the HDX API endpoints. If you would like to request either a new feature or think a critical dataset is missing, please let us know!

Report bugs and request features by emailing [hdx@un.org](mailto:undefined).


# Finding and downloading data

Many data resources can be accessed through the file download endpoint

## Available data

File download access is available for all public data on HDX. Any dataset resource that exposes a `download_url` can be retrieved programmatically, regardless of whether the data is tabular, geospatial, or provided in another file format like zip folders.

This includes CSV and Excel files, geospatial formats, zipped folders, and other common data files hosted on HDX, as well as redirect you to from resources that have externally hosted data. Availability and structure varies by data contributor, and datasets may include multiple resources with different formats or purposes.

## Finding and downloading data

Data on HDX can be discovered either through the web interface or programmatically via the metadata API endpoint (`package_search`). Both approaches reference the same underlying data.

### Finding the data via the HDX UI

You can identify downloadable files directly from HDX.

Navigate to a dataset page on HDX. Each dataset lists one or more resources which contain the data itself. For each resource, you will see the resource name, file format, a More Information button and a Download button.

Select the resource you want to work with by clicking the More Information button, screenshot below. Here you can see, where available, the resource preview, data dictionary and API access information.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FBGVGGAru90DHuL4LzQY6%2FWP%20dataset%20page-data%20and%20resources.png?alt=media&amp;token=08c1fac5-f856-4c12-a48d-03b831520b53" alt="" width="563"><figcaption><p>More Information button location</p></figcaption></figure></div>

Once on the resource page, the URL listed is the file download endpoint for that particular resource.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2Fk5waYU5nuGuywW8Ln6fw%2FBuild-resource-preview.png?alt=media&amp;token=14544d06-046b-412a-ae7e-449b62043a9c" alt="" width="563"><figcaption><p>Resource preview</p></figcaption></figure></div>

### Finding the data via the HDX Metadata API

Downloadable file URLs can also be discovered programmatically using the HDX metadata endpoints.

Query the dataset metadata endpoint (`package_show` or `package_search`) to retrieve the dataset object. In the response, inspect the `resources` array. Each entry represents a single resource and includes metadata such as `id`, `name`, `format`, and `download_url`.

Identify the resource that corresponds to the data file you want to retrieve. Datasets may include multiple resources, such as data files or codebooks. Once identified, use the `download_url` field from that resource object to download the file programmatically.

See example below for the package\_show query using the [Global Pcodes dataset](https://data.humdata.org/dataset/global-pcodes) on HDX. `https://data.humdata.org/api/action/package_show?id=global-pcodes`

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FXN4Q91KzMvrbyQdIjKvz%2Funknown.png?alt=media&amp;token=ca59f345-6f0f-4ccd-8219-c539ac0daf13" alt="" width="563"><figcaption><p>Global Pcodes example</p></figcaption></figure></div>


# Tools

Learn how to use the file download in Power BI.

The File download is suitable for complete file based ingestion and scheduled refreshes where the underlying file is updated over time. Due to performance issues, resources downloaded through the File download should be small (see Tabular Data Endpoints section for ability to query large datasets).

## Power BI

HDX file URL resources can be used directly as a data source in Power BI and other Microsoft tools that support Power Query, such as Fabric. Follow this section to connect HDX’s File URL endpoint to Power BI as a data source.

{% stepper %}
{% step %}

#### **Open Power BI Desktop. From the Home menu, select Get data, then choose Web as the data source.**

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2F6CyDsE8AGfYmfO9vRFQ0%2Funknown.png?alt=media&amp;token=08f85bbb-0985-4a20-9148-3025e54da9a2" alt="" width="563"><figcaption><p>Web</p></figcaption></figure></div>

{% endstep %}

{% step %}

#### In the URL field, paste the  `download_url`  for the resource you want to load.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2Fp5Iw2sWoA8qF0PyLbzA9%2Funknown.png?alt=media&amp;token=1c9bf6f8-851e-455b-a3f1-9c924f58800a" alt="" width="563"><figcaption><p>URL field</p></figcaption></figure></div>

{% endstep %}

{% step %}

#### **If prompted for credentials, select Anonymous. If you encounter credential errors, go to File → Options and settings → Data source settings, clear existing permissions for the URL, and retry the connection.**

{% endstep %}

{% step %}

### **Once the data preview loads in the Power Query Editor, click Close & Apply to load the dataset into Power BI. Power BI will re-download the file on refresh using the same URL.**

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2F8NpJ1DkexeWo8BU7uG0I%2Funknown.png?alt=media&amp;token=405a1a51-ef39-493e-ac1f-084235d60665" alt="" width="563"><figcaption><p>Load</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

For datasets with multiple resources or changing file structures, ensure the selected `download_url` consistently points to the intended file.


# Metadata endpoints

A guide to accessing and cataloguing HDX data through the metadata endpoints.

## Introduction

The HDX metadata endpoints provide programmatic access to metadata on HDX. They allow users to search, filter, and retrieve detailed information about organizations and data on the platform. This enables users to discover data and data contributors to programmatically automate data management.

The HDX Metadata endpoints are powered by the CKAN API and provide two main functions:

* `package_search`: Search and filter datasets with advanced query capabilities
* `package_show`: Retrieve detailed metadata for a specific dataset

This documentation is designed for analysts and technical audiences who want to discover datasets, build automated workflows, or integrate HDX data into external systems.

## How to query the metadata endpoints

There are two main Metadata Endpoints that can be queried, each accessed via their own endpoint.&#x20;

1. Searching Catalogue (`package_search`)
2. Dataset schema (`package_show`)

HDX is built on CKAN, an open source data management platform. Additional CKAN endpoints exist beyond those listed above, but these are the most relevant for working with HDX. For more detailed information, please see the [CKAN documentation](https://docs.ckan.org/en/2.9/api/) for APIs.

## Feedback and support

We are always adding new features and additional datasets into the HDX API endpoints. If you would like to request either a new feature or think a critical dataset is missing, please let us know!

Report bugs and request features by emailing <hdx@un.org>.


# 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

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


# package\_show

Learn how to query package\_show to learn more about a dataset on HDX

The `package_show` endpoint retrieves complete metadata for a single dataset, including all resources, tags, and relationships.

**Base URL:** `https://data.humdata.org/api/action/package_show`

**Method:** GET or POST

## Use Cases

* **Dataset details:** Get comprehensive information about a specific dataset like the date last updated
* **Resource enumeration:** List all files and resources in a dataset
* **Metadata extraction:** Extract specific fields for analysis or cataloging like countries or time period
* **Validation:** Check dataset properties before processing for downstream access like Tabular Data Endpoints access

## Parameters

<table data-header-hidden data-first-column-sticky><thead><tr><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></tr><tr><td><code>id</code></td><td>string</td><td>Yes</td><td>Dataset ID or URL name (can be used interchangeably) </td></tr></tbody></table>

## Key Response Fields

There are some key response fields returned from the API response which give insight into the dataset. Below are some key responses but the list is not exhaustive.

* **dataset\_date:** Dataset time period
* **data\_update\_frequency:** How often the dataset is updated
* **cod\_level:** Flag for COD datasets
* **notes:** Dataset description/abstract
* **license\_id** and **license\_title**: Data usage license
* **maintainer** and **maintainer\_email**: Contact information
* **resources**: Detailed information about each file
  * **size**: File size in bytes
  * **download\_url**: Direct download link (see File URL section here )
* **organization**: Full organization details including package count

### Sample Query

`https://data.humdata.org/api/action/package_show?id=cod-ab-pak`

## Common use cases

The Metadata endpoints are very flexible and can be used in many different types of processes in the humanitarian sector. See specific URLs and code examples below in Python and Javascript.&#x20;

Note that you do not need to be signed into HDX to access the endpoints directly in your browser or need an API token unless you hit the rate limit of 60 requests per minute.

### Direct URLs

These examples show some specific use-cases of how to configure the URL to query the HDX catalogue for specific humanitarian use-cases.

1. **Search HDX for the most recently updated datasets of South Sudan for returnees data**

`https://data.humdata.org/api/action/package_search?q=returnees&fq=groups:ssd&sort=metadata_modified%20desc&rows=5`

2. **Search for datasets from UNFPA for population**

`https://data.humdata.org/api/action/package_search?q=population&fq=organization:unfpa&rows=10`<br>

3. **Get all downloadable resources for a specific dataset**

`https://data.humdata.org/api/action/package_show?id=ukraine-border-crossings`

<br>


# OpenAPI specification

Full parameter and response reference for the package\_search endpoint.

`package_search` needs no token for public datasets. Try it with curl or an API client:

{% code overflow="wrap" %}

```
curl "https://data.humdata.org/api/3/action/package_search?q=*:*&rows=5"
```

{% endcode %}

For a GUI, import the [OpenAPI spec](https://raw.githubusercontent.com/OCHA-DAP/hdx-openapi-specs/main/dist/openapi.json) into Postman, Insomnia, Bruno, or Scalar. Add a token only to include private or draft datasets for organizations to which you belong.

## Search datasets

> Search for datasets (packages) using Solr query syntax. Supports filtering, faceting, sorting, and pagination. No authentication required for public data.\
> \
> Pass parameters as query string arguments (GET) or as a JSON body (POST).

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{},{"ApiKeyAuthCatalog":[]}],"components":{"securitySchemes":{"ApiKeyAuthCatalog":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Optional — public dataset search needs no authentication; a token is only required to include private or draft datasets."}},"schemas":{"PackageSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/PackageSearchResult"}},"required":["help","success","result"],"title":"PackageSearchResponse","type":"object"},"PackageSearchResult":{"properties":{"count":{"description":"Total number of datasets matching the query.","title":"Count","type":"integer"},"results":{"description":"List of matching dataset objects.","items":{"additionalProperties":true,"type":"object"},"title":"Results","type":"array"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Sort string echoed from the request.","title":"Sort"},"facets":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Legacy facet counts. Prefer `search_facets`.","title":"Facets"},"search_facets":{"additionalProperties":true,"description":"Facet counts keyed by field name. Each entry has a `title` and an `items` list of `{name, display_name, count}` objects.","title":"Search Facets","type":"object"},"facet_pivot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Pivot facet results, if requested.","title":"Facet Pivot"},"facet_queries":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Facet query results, if requested.","title":"Facet Queries"},"expanded":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Expanded results, if requested.","title":"Expanded"}},"required":["count","results","search_facets"],"title":"PackageSearchResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/package_search":{"get":{"operationId":"package_search_get","summary":"Search datasets","description":"Search for datasets (packages) using Solr query syntax. Supports filtering, faceting, sorting, and pagination. No authentication required for public data.\n\nPass parameters as query string arguments (GET) or as a JSON body (POST).","tags":["Catalog"],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"*:*","title":"Q"},"description":"Solr search query. Supports Solr syntax. Defaults to `\"*:*\"` (all datasets)."},{"name":"fq","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Fq"},"description":"Solr filter query. Restricts results without affecting relevance scoring."},{"name":"fq_list","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Fq List"},"description":"Additional filter queries as a list. Each entry is ANDed with `fq`."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"score desc, metadata_modified desc","title":"Sort"},"description":"Sort order as a Solr sort string. Defaults to `\"score desc, metadata_modified desc\"`."},{"name":"rows","in":"query","required":false,"schema":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":10,"title":"Rows"},"description":"Maximum number of datasets to return. Defaults to `10`, maximum `1000`."},{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Start"},"description":"Offset into the result set. Used for pagination."},{"name":"facet","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"true","title":"Facet"},"description":"Enable faceted results. Defaults to `\"true\"`."},{"name":"facet.mincount","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Facet.Mincount"},"description":"Minimum count for a facet value to be included in the response."},{"name":"facet.limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":50,"title":"Facet.Limit"},"description":"Maximum number of values returned per facet field. Defaults to `50`."},{"name":"facet.field","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Facet.Field"},"description":"Fields to facet on."},{"name":"include_drafts","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Drafts"},"description":"Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to `false`."},{"name":"include_deleted","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Deleted"},"description":"Include deleted datasets in results. Defaults to `false`."},{"name":"include_private","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Private"},"description":"Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to `false`."},{"name":"use_default_schema","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Use Default Schema"},"description":"Return results using the default package schema rather than any custom schema configured on the instance. Defaults to `false`."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the requested action or endpoint does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search datasets (POST)

> Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for long \`fq\_list\` or \`facet.field\` values.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{},{"ApiKeyAuthCatalog":[]}],"components":{"securitySchemes":{"ApiKeyAuthCatalog":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Optional — public dataset search needs no authentication; a token is only required to include private or draft datasets."}},"schemas":{"PackageSearchParams":{"properties":{"q":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"*:*","description":"Solr search query. Supports Solr syntax. Defaults to `\"*:*\"` (all datasets).","title":"Q"},"fq":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Solr filter query. Restricts results without affecting relevance scoring.","title":"Fq"},"fq_list":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Additional filter queries as a list. Each entry is ANDed with `fq`.","title":"Fq List"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"score desc, metadata_modified desc","description":"Sort order as a Solr sort string. Defaults to `\"score desc, metadata_modified desc\"`.","title":"Sort"},"rows":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":10,"description":"Maximum number of datasets to return. Defaults to `10`, maximum `1000`.","title":"Rows"},"start":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Offset into the result set. Used for pagination.","title":"Start"},"facet":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"true","description":"Enable faceted results. Defaults to `\"true\"`.","title":"Facet"},"facet.mincount":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum count for a facet value to be included in the response.","title":"Facet.Mincount"},"facet.limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":50,"description":"Maximum number of values returned per facet field. Defaults to `50`.","title":"Facet.Limit"},"facet.field":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Fields to facet on.","title":"Facet.Field"},"include_drafts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include draft datasets in results. Requires authentication as the owning user or org admin. Defaults to `false`.","title":"Include Drafts"},"include_deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include deleted datasets in results. Defaults to `false`.","title":"Include Deleted"},"include_private":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include private datasets in results. Requires authentication as a member of the owning organisation. Defaults to `false`.","title":"Include Private"},"use_default_schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Return results using the default package schema rather than any custom schema configured on the instance. Defaults to `false`.","title":"Use Default Schema"}},"title":"PackageSearchParams","type":"object"},"PackageSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/PackageSearchResult"}},"required":["help","success","result"],"title":"PackageSearchResponse","type":"object"},"PackageSearchResult":{"properties":{"count":{"description":"Total number of datasets matching the query.","title":"Count","type":"integer"},"results":{"description":"List of matching dataset objects.","items":{"additionalProperties":true,"type":"object"},"title":"Results","type":"array"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Sort string echoed from the request.","title":"Sort"},"facets":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Legacy facet counts. Prefer `search_facets`.","title":"Facets"},"search_facets":{"additionalProperties":true,"description":"Facet counts keyed by field name. Each entry has a `title` and an `items` list of `{name, display_name, count}` objects.","title":"Search Facets","type":"object"},"facet_pivot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Pivot facet results, if requested.","title":"Facet Pivot"},"facet_queries":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Facet query results, if requested.","title":"Facet Queries"},"expanded":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Expanded results, if requested.","title":"Expanded"}},"required":["count","results","search_facets"],"title":"PackageSearchResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/package_search":{"post":{"operationId":"package_search_post","summary":"Search datasets (POST)","description":"Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for long `fq_list` or `facet.field` values.","tags":["Catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSearchParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the requested action or endpoint does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


# Code examples and Python notebook

Python and Javascript examples and a ready-to-run Python notebook

The HDX metadata endpoints can be used with many different coding languages and processes in the humanitarian sector. See specific code examples below.

*Note that you can access the endpoints directly in your browser as well.*

{% tabs %}
{% tab title="Python" %}
**See Python specific examples below.**

*While these endpoints are designed for lightweight, token-free access, two Python libraries are available if you prefer a higher-level interface:*[ *ckanapi*](https://github.com/ckan/ckanapi)*, a low-level library from CKAN, and the*[ *HDX Python API*](https://github.com/OCHA-DAP/hdx-python-api)*, which builds on it and is primarily intended for data contributors publishing data to HDX.*

#### Search HDX for the most recently updated datasets of South Sudan for returnees data

```python
import requests
response = requests.get(
    "https://data.humdata.org/api/action/package_search",
    params={
        "q": "returnees",
        "fq": "groups:ssd",
        "sort": "metadata_modified desc",
        "rows": 5
    }
)

data = response.json()
for dataset in data["result"]["results"]:
    print(dataset["title"])
    print(f"  Updated: {dataset['metadata_modified'][:10]}")
```

#### Search for datasets from UNFPA for population

```python
import requests
response = requests.get(
    "https://data.humdata.org/api/action/package_search",
    params={
        "q": "population",
        "fq": "organization:unfpa",
        "rows": 10
    }
)

data = response.json()
print(f"Found {data['result']['count']} datasets")

for dataset in data["result"]["results"]:
    print(f"• {dataset['title']}")
```

#### Get all downloadable resources for a specific dataset

```python
import requests
dataset_id = "ukraine-border-crossings"

response = requests.get(
    "https://data.humdata.org/api/action/package_show",
    params={"id": dataset_id}
)

data = response.json()
dataset = data["result"]

print(f"Dataset: {dataset['title']}")
print(f"Resources: {len(dataset['resources'])}\n")

for resource in dataset["resources"]:
    print(f" {resource['name']}")
    print(f"   Format: {resource.get('format', 'N/A')}")
    if 'download_url' in resource:
        print(f"   Download: {resource['download_url']}")
    print()
```

{% endtab %}

{% tab title="Javascript" %}
**See Javascript specific examples below.**

*For JavaScript, there are also CKAN client libraries available, including a*[ *newer option from Datopian*](https://github.com/datopian/portaljs/tree/main/packages/ckan-api-client-js) *and a*[ *legacy version*](https://github.com/datopian/ckan-client-js)*.*

#### Search HDX for the most recently updated datasets of South Sudan for returnees data

```javascript
const params = new URLSearchParams({
    q: "returnees",
    fq: "groups:ssd",
    sort: "metadata_modified desc",
    rows: 5
});

fetch(`https://data.humdata.org/api/action/package_search?${params}`)
    .then(response => response.json())
    .then(data => {
        data.result.results.forEach(dataset => {
            console.log(dataset.title);
            console.log(`  Updated: ${dataset.metadata_modified.substring(0, 10)}`);
        });
    });
```

#### Search for datasets from UNFPA for population

```javascript
const params = new URLSearchParams({
    q: "population",
    fq: "organization:unfpa",
    rows: 10
});

fetch(`https://data.humdata.org/api/action/package_search?${params}`)
    .then(response => response.json())
    .then(data => {
        console.log(`Found ${data.result.count} datasets`);
        data.result.results.forEach(dataset => {
            console.log(`• ${dataset.title}`);
        });
    });
```

#### Get all downloadable resources for a specific dataset

```javascript
const datasetId = "ukraine-border-crossings";
const params = new URLSearchParams({ id: datasetId });

fetch(`https://data.humdata.org/api/action/package_show?${params}`)
    .then(response => response.json())
    .then(data => {
        const dataset = data.result;
        console.log(`Dataset: ${dataset.title}`);
        console.log(`Resources: ${dataset.resources.length}\n`);
        
        dataset.resources.forEach(resource => {
            console.log(`${resource.name}`);
            console.log(`   Format: ${resource.format || 'N/A'}`);
            if (resource.download_url) {
                console.log(`   Download: ${resource.download_url}`);
            }
        });
    });
```

{% endtab %}
{% endtabs %}

#### Python notebook <a href="#python-notebook" id="python-notebook"></a>

We provide a ready-to-run Python `ipynb` notebook showing how to query the metadata endpoints (`package_search` and `package_show`) for Python scripts and pipelines. You can open it directly in your browser via GitHub and test queries without needing to install anything locally.

**Open the Python notebook** [**here**](https://github.com/OCHA-DAP/hdx-metadata-endpoints-notebook)**.**

**Important:**

* For the advanced section, you must provide your own HDX API token in the notebook.
* Never commit your token or share it publicly! Treat it like a password.

**The notebook covers:**

* Searching the HDX catalogue using `package_search` with `q` and `fq` filters
* Aggregating catalogue stats using facet queries with `rows=0`
* Extracting full dataset metadata via `package_show`
* Automating shapefile downloads and loading into a GeoDataFrame
* Querying tabular data via TDE (`datastore_info`, `datastore_search`)


# Troubleshooting and error handling

Need help with the metadata endpoints? Look no further.

### HTTP Status Codes

<table data-header-hidden data-first-column-sticky><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Code</strong></td><td><strong>Meaning</strong></td><td><strong>Action</strong></td></tr><tr><td><code>200</code></td><td>Success</td><td>Process the response</td></tr><tr><td><code>400</code></td><td>Bad request</td><td>Check query syntax</td></tr><tr><td><code>401</code></td><td>Unauthorized</td><td>Verify API token</td></tr><tr><td><code>403</code></td><td>Forbidden</td><td>Check permissions</td></tr><tr><td><code>404</code></td><td>Not found</td><td>Verify resource ID</td></tr><tr><td><code>429</code></td><td>Too many requests</td><td>Implement rate limiting</td></tr><tr><td><code>500</code></td><td>Server error</td><td>Retry after delay</td></tr></tbody></table>

### Dataset not found

* **Symptom**: See response below.

```
{
  "success": false,
  "error": {
    "__type": "Not Found Error",
    "message": "Not found"
  }
}
```

* **Likely cause**: Incorrect dataset ID or name.
* **Fix**: Verify the dataset ID or name. Use `package_search` to find the correct identifier.

### No results

* **Symptom:** No results returning from `package_search` endpoints even though the query should return packages.
* **Likely cause:** Incorrect search query.
* **Fix:** Review your Solr query syntax. Ensure quotes and operators are properly formatted.

### Rate limiting

* **Symptom:** `429` error code
* **Likely cause:** Using API calls more than 60 times per minute.
* **Fix:** HDX implements rate limiting to ensure service stability. Anonymous requests are limited to prevent abuse. Authenticated requests have higher limits for registered users. For best practices, we recommend caching results when possible and adding delays between bulk requests.


# Tabular Data Endpoints

A guide to accessing, filtering, and integrating HDX data through the Tabular Data Endpoints (TDE).

## Introduction

The HDX Tabular Data Endpoints (TDE) provide programmatic access to a number of tabular datasets hosted on HDX. It supports features like customizable queries and dataset joins to enable seamless integration into external tools and systems. By allowing real-time querying of tabular data, HDX Tabular Data endpoints makes it easier for developers, analysts, and humanitarian responders to automatically integrate HDX data into their workflows.

The HDX Tabular Data endpoints are powered by the [CKAN DataStore](https://ckan.org/features/datastore) extension.

The following documentation is intended for analysts and technical audiences to configure the endpoints, troubleshoot, integrate with tools, and learn from working examples.

## Building a HDX Tabular **Data** query

With your HDX API token and the `resource_id` (see [HDX Core Concepts section](https://docs.humdata.org/build/overview/hdx-core-concepts) for more information), you have the key components needed to configure an HDX Tabular Data query. The diagram below shows how these elements fit together; the different endpoints are explained in the following sections.

<div align="left"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FVOsGt51BYkA6vfA24MF9%2Fconfig%20tab.png?alt=media&amp;token=0fadb7a1-d787-4f22-8219-c00cfda9a9fd" alt="" width="563"><figcaption><p>This diagram shows the basic elements of a Tabular Data Endpoint query.</p></figcaption></figure></div>

## Feedback and support

We are always adding new features and additional datasets into the Tabular Data Endpoints. If you would like to request either a new feature or think a critical dataset is missing, please let us know!

Report bugs and request features by emailing [hdx@un.org](mailto:undefined).


# Available data and resource IDs

How to find Tabular Data resources

The Tabular Data endpoints works at the resource level, meaning you query a specific file, not the entire dataset. Tabular Data API access is currently available for a subset of resources on HDX.&#x20;

We’re working on expanding coverage to include additional structured CSV resources.

#### Browse datasets active in Tabular Data Endpoints

HDX provides a pre-filtered discovery view that shows all datasets with at least one resource currently active in the Tabular Data Endpoints. You can access this view directly [here](https://data.humdata.org/dataset?fq=res_extras_datastore_active:true).

This page automatically applies a filter for resources where `datastore_active` is true, meaning the dataset contains one or more structured CSV resources available via the Tabular Data Endpoints. From this list, you can open individual dataset pages to identify the specific resource and retrieve its resource ID for programmatic access.

#### **Tabular Data** Resource ID: HDX UI <a href="#datastore-resource-id-hdx-ui" id="datastore-resource-id-hdx-ui"></a>

Here's how to find resources active on Tabular Data through the HDX UI:

1. **Navigate to the Available Datasets via Tabular Data Endpoints Page:** Go to the discovery [page](https://data.humdata.org/dataset?fq=res_extras_datastore_active:true) that lists the available datasets for Tabular Data API access.
2. **Find your dataset:** On the actual dataset page, each data resource is listed with a name, file format, and additional indicators (e.g. API access).
3. **Access Tabular Data API endpoint:** For the individual resource available within HDX’s Tabular Data endpoints, you’ll see a link to the relevant API(s) along with the resource ID. This information is essential for querying the resource programmatically.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FYhnKMokPh8VV4eS7gjAO%2FScreenshot%202026-01-22%20at%2011.32.06.png?alt=media&amp;token=28d43025-3752-4ac8-9481-b483a9a9d685" alt="" width="563"><figcaption><p>API button</p></figcaption></figure></div>

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FKHQEsDBxsQce1wQnwbd9%2FScreenshot%202026-01-22%20at%2011.32.16.png?alt=media&amp;token=8a219965-262c-4f80-991c-683c7b892f8d" alt="" width="563"><figcaption><p>API popup</p></figcaption></figure></div>

#### Tabular Data Resource ID: HDX Metadata API <a href="#datastore-resource-id-hdx-ckan-api" id="datastore-resource-id-hdx-ckan-api"></a>

Resource ids can also be found in the HDX metadata API response. See HDX System documentation for finding the `resource_id` through the HDX metadata API.

From the response, identify the resource that corresponds to the structured data you're interested in. Sometimes datasets include multiple resources (e.g. data files, documentation). Inspect each item in the resources array and look for one where `"datastore_active": true` (if present), which indicates Tabular Data API compatibility. Note the `id` of that resource since this is your `resource_id`.

<div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2F7wh0zdsyrO8qsb4TTpIM%2FScreenshot%202026-01-22%20at%2011.34.42.png?alt=media&amp;token=5ad25ab0-188d-40e7-a13a-4595415ab52d" alt="" width="563"><figcaption><p>id</p></figcaption></figure></div>


# How to query the Tabular Data Endpoints

How to use the different Tabular Data endpoints

There are three ways that the Tabular Data endpoints can be queried, each accessed via it's own endpoint. See below:

1. **Schema Information (`datastore_info`):** This endpoint returns information about the data within the resource like column names and data types. This is helpful to better understand the data instead of calling the entire data table.
   1. Use `datastore_info` for simple information on the data resources.
2. **Native (`datastore_search`):** This endpoint provides a simple, URL-based interface for querying records within a data resource. If you are starting out with APIs, this is the one you should use. It supports standard functionality including filtering by field values, text search, pagination, field selection, and sorting.
   1. Use `datastore_search` when working with simple filters, browsing data, or building lightweight applications or a Power BI dashboard.
3. **SQL (`datastore_search_sql`):** This endpoint allows for more advanced querying using full SQL syntax. It is useful when complex conditions like aggregations, or joins within multiple resources are needed. It offers greater flexibility but also requires a proper understanding of SQL.
   1. Use `datastore_search_sql` for more analytical purposes or when multiple conditions and calculations are required.

For more detailed information, please see the [CKAN DataStore API documentation](https://docs.ckan.org/en/2.9/maintaining/datastore.html#the-datastore-api).

#### 1. Query requests: Schema information <a href="#id-1.-api-requests-schema-information" id="id-1.-api-requests-schema-information"></a>

This is a basic information endpoint which simply returns information about the data resource. This can be used to learn more about the column names and data types by retrieving a dictionary describing the columns and their types.

**Endpoint**

`https://data.humdata.org/api/3/action/datastore_info`

**Parameters**

ID of the resource.

**Example URL**`https://data.humdata.org/api/3/action/datastore_info?id=<resource_id>`

#### 2. Query requests: Native <a href="#id-2.-api-requests-native" id="id-2.-api-requests-native"></a>

With the **endpoint**, **token**, and **resource\_id**, you can now query data using standard API calls by configuring the URL like follows:

**Endpoint**

`https://data.humdata.org/api/3/action/datastore_search`

**Example:** Retrieve the rows in a dataset where the country is “Kenya” for 2024.

`https://data.humdata.org/api/3/action/datastore_search?id=<resource_id>&filters={"country":"Kenya",”year”:2024}`

**Common parameters (see** [**the CKAN DataStore documentation**](https://docs.ckan.org/en/latest/maintaining/datastore.html#ckanext.datastore.logic.action.datastore_search) **for more details)**

| `resource_id` | <mark style="color:$danger;">\[Required] The resource unique identifier</mark>                              |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| `limit`       | Maximum number of results to return                                                                         |
| `offset`      | Start index for pagination                                                                                  |
| `q`           | Search across all data (can pass as dictionary to limit to a specific column)                               |
| `filters`     | ​[Filter specific fields](https://docs.ckan.org/en/latest/maintaining/datastore.html#filters) (exact match) |
| `fields`      | Limit which columns are returned                                                                            |
| `sort`        | Sort results                                                                                                |

#### 3. Query Requests: SQL <a href="#id-3.-api-requests-sql" id="id-3.-api-requests-sql"></a>

For more advanced API queries, the SQL API supports a full subset of PostgreSQL syntax. It's ideal for advanced queries, aggregations, joins (within limits), and complex filters. It also requires the **endpoint**, **token**, and **resource\_id**.

**Endpoint**

`GET /datastore_search_sql`

**Parameters:** `sql` (Required) A SQL query string. Must reference the correct resource (table name is the `resource_id`).

**Example: WHERE clause**

`https://data.humdata.org/api/3/action/datastore_search_sql?sql=SELECT+*+FROM+"id"+WHERE+country='Kenya'+AND+year=2024`

**Example SQL Query**

`SELECT country, AVG(value) FROM "id" WHERE indicator = 'population' AND year = 2024 GROUP BY country`

Note: Be sure to URL-encode your SQL queries when sending them via GET (e.g. urlib.parse in Python).


# OpenAPI specification

Full parameter and response reference for the three Tabular Data Endpoints.

Query these endpoints with curl or an API client, using your HDX token:

{% code overflow="wrap" %}

```
curl -H "Authorization: <your-api-token>" \  "https://data.humdata.org/api/3/action/datastore_search?resource_id=<resource-id>&limit=5"
```

{% endcode %}

For a GUI, import the [OpenAPI spec](https://raw.githubusercontent.com/OCHA-DAP/hdx-openapi-specs/main/dist/openapi.json) into Postman, Insomnia, Bruno, or Scalar and set an `Authorization` header. Get your token at **data.humdata.org → profile → Manage API tokens**.

## Get DataStore resource metadata

> Retrieve field definitions, type information, and size/count metadata for a DataStore resource.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreInfoResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreInfoResult"}},"required":["help","success","result"],"title":"DatastoreInfoResponse","type":"object"},"DatastoreInfoResult":{"properties":{"meta":{"anyOf":[{"$ref":"#/components/schemas/DatastoreResourceMeta"},{"type":"null"}],"default":null,"description":"Resource metadata including aliases, row count, and size information."},"fields":{"description":"List of field descriptor objects. Each contains `id`, `type`, and optionally `schema` with index and uniqueness information.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"}},"required":["fields"],"title":"DatastoreInfoResult","type":"object"},"DatastoreResourceMeta":{"properties":{"aliases":{"description":"List of aliases defined for this resource.","items":{"type":"string"},"title":"Aliases","type":"array"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of rows in the resource table.","title":"Count"},"db_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total size of the DataStore database in bytes (all tables, not just this resource).","title":"Db Size"},"id":{"description":"The resource ID.","title":"Id","type":"string"},"idx_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of indexes on this resource table in bytes.","title":"Idx Size"},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of this resource table in bytes.","title":"Size"},"table_type":{"anyOf":[{"enum":["BASE TABLE","VIEW","FOREIGN","LOCAL TEMPORARY"],"type":"string"},{"type":"null"}],"default":null,"description":"PostgreSQL table type for this resource.","title":"Table Type"}},"required":["aliases","id"],"title":"DatastoreResourceMeta","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_info":{"get":{"operationId":"datastore_info_get","summary":"Get DataStore resource metadata","description":"Retrieve field definitions, type information, and size/count metadata for a DataStore resource.","tags":["DataStore"],"parameters":[{"name":"resource_id","in":"query","required":true,"schema":{"title":"Resource Id","type":"string"},"description":"The `id` or alias of the DataStore resource to describe. Required."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreInfoResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get DataStore resource metadata (POST)

> Identical to the GET form.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreInfoParams":{"properties":{"resource_id":{"description":"The `id` or alias of the DataStore resource to describe. Required.","title":"Resource Id","type":"string"}},"required":["resource_id"],"title":"DatastoreInfoParams","type":"object"},"DatastoreInfoResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreInfoResult"}},"required":["help","success","result"],"title":"DatastoreInfoResponse","type":"object"},"DatastoreInfoResult":{"properties":{"meta":{"anyOf":[{"$ref":"#/components/schemas/DatastoreResourceMeta"},{"type":"null"}],"default":null,"description":"Resource metadata including aliases, row count, and size information."},"fields":{"description":"List of field descriptor objects. Each contains `id`, `type`, and optionally `schema` with index and uniqueness information.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"}},"required":["fields"],"title":"DatastoreInfoResult","type":"object"},"DatastoreResourceMeta":{"properties":{"aliases":{"description":"List of aliases defined for this resource.","items":{"type":"string"},"title":"Aliases","type":"array"},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of rows in the resource table.","title":"Count"},"db_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total size of the DataStore database in bytes (all tables, not just this resource).","title":"Db Size"},"id":{"description":"The resource ID.","title":"Id","type":"string"},"idx_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of indexes on this resource table in bytes.","title":"Idx Size"},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Size of this resource table in bytes.","title":"Size"},"table_type":{"anyOf":[{"enum":["BASE TABLE","VIEW","FOREIGN","LOCAL TEMPORARY"],"type":"string"},{"type":"null"}],"default":null,"description":"PostgreSQL table type for this resource.","title":"Table Type"}},"required":["aliases","id"],"title":"DatastoreResourceMeta","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_info":{"post":{"operationId":"datastore_info_post","summary":"Get DataStore resource metadata (POST)","description":"Identical to the GET form.","tags":["DataStore"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreInfoParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreInfoResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search a DataStore resource

> Query rows from a DataStore resource with optional filtering, full-text search, sorting, and pagination.\
> \
> Pass parameters as query string arguments (GET) or as a JSON body (POST).

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchResult"}},"required":["help","success","result"],"title":"DatastoreSearchResponse","type":"object"},"DatastoreSearchResult":{"properties":{"resource_id":{"description":"The resource ID that was queried.","title":"Resource Id","type":"string"},"fields":{"description":"List of field descriptor objects, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The offset used in the query.","title":"Offset"},"limit":{"description":"The limit used in the query.","title":"Limit","type":"integer"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Filters applied to the query.","title":"Filters"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Indicates whether `total` is included.","title":"Include Total"},"records_format":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Format used for `records`.","title":"Records Format"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of matching rows. Present when `include_total` is `true`.","title":"Total"},"total_was_estimated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the total count was estimated rather than exact.","title":"Total Was Estimated"},"total_estimation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Row count threshold above which total estimation is used. `null` when estimation is not configured.","title":"Total Estimation Threshold"},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"items":{"items":{},"type":"array"},"type":"array"},{"type":"string"}],"description":"Matching rows. Shape depends on `records_format`.","title":"Records"},"_links":{"$ref":"#/components/schemas/DatastoreSearchLinks","description":"Pagination helper URLs. Always present — `next` contains the URL for the next page of results."}},"required":["resource_id","fields","limit","records","_links"],"title":"DatastoreSearchResult","type":"object"},"DatastoreSearchLinks":{"properties":{"start":{"description":"URL to the first page of results with the same parameters.","title":"Start","type":"string"},"next":{"description":"URL to the next page of results.","title":"Next","type":"string"}},"required":["start","next"],"title":"DatastoreSearchLinks","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search":{"get":{"operationId":"datastore_search_get","summary":"Search a DataStore resource","description":"Query rows from a DataStore resource with optional filtering, full-text search, sorting, and pagination.\n\nPass parameters as query string arguments (GET) or as a JSON body (POST).","tags":["DataStore"],"parameters":[{"name":"resource_id","in":"query","required":true,"schema":{"title":"Resource Id","type":"string"},"description":"The `id` or alias of the resource to search. Required."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Filters"},"description":"Matching conditions as a dictionary of `{field: value}` pairs. Rows must match all conditions. Example: `{\"country\": \"Uganda\"}`."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Q"},"description":"Full-text search query. Pass a string to search across all fields, or a dictionary of `{field: query}` to target specific fields. Note: behavior differs subtly from `filters` — `q` uses full-text ranking while `filters` performs exact matching."},{"name":"full_text","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Full Text"},"description":"Full-text search query applied across all fields. Similar to `q` with a string value, but always searches all fields. Cannot be combined with `q`."},{"name":"distinct","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Distinct"},"description":"Return only unique rows. Defaults to `false`."},{"name":"plain","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"title":"Plain"},"description":"Treat the `q` query as plain text (no special FTS operators). Set to `false` to use PostgreSQL tsquery syntax. Defaults to `true`."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"english","title":"Language"},"description":"Language used for full-text search stemming. Defaults to `english`."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":100,"title":"Limit"},"description":"Maximum number of rows to return. Defaults to `100`."},{"name":"offset","in":"query","required":false,"schema":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Offset"},"description":"Number of rows to skip before returning results. Used for pagination."},{"name":"fields","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"title":"Fields"},"description":"Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sort"},"description":"Comma-separated list of fields to sort by, with optional `asc`/`desc` direction. Example: `\"fieldname1 asc, fieldname2 desc\"`."},{"name":"include_total","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"title":"Include Total"},"description":"Include the total number of matching rows in the response. Defaults to `true`."},{"name":"total_estimation_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Estimation Threshold"},"description":"When `include_total` is `true` and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to `null` (default) to always return an exact count."},{"name":"records_format","in":"query","required":false,"schema":{"anyOf":[{"enum":["objects","lists","csv","tsv"],"type":"string"},{"type":"null"}],"default":"objects","title":"Records Format"},"description":"Format for the returned records. `objects` returns a list of dicts, `lists` returns a list of lists, `csv` and `tsv` return delimited strings. Defaults to `objects`."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search a DataStore resource (POST)

> Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for large \`filters\` or \`fields\` payloads.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchParams":{"properties":{"resource_id":{"description":"The `id` or alias of the resource to search. Required.","title":"Resource Id","type":"string"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Matching conditions as a dictionary of `{field: value}` pairs. Rows must match all conditions. Example: `{\"country\": \"Uganda\"}`.","title":"Filters"},"q":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Full-text search query. Pass a string to search across all fields, or a dictionary of `{field: query}` to target specific fields. Note: behavior differs subtly from `filters` — `q` uses full-text ranking while `filters` performs exact matching.","title":"Q"},"full_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Full-text search query applied across all fields. Similar to `q` with a string value, but always searches all fields. Cannot be combined with `q`.","title":"Full Text"},"distinct":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Return only unique rows. Defaults to `false`.","title":"Distinct"},"plain":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Treat the `q` query as plain text (no special FTS operators). Set to `false` to use PostgreSQL tsquery syntax. Defaults to `true`.","title":"Plain"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"english","description":"Language used for full-text search stemming. Defaults to `english`.","title":"Language"},"limit":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum number of rows to return. Defaults to `100`.","title":"Limit"},"offset":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of rows to skip before returning results. Used for pagination.","title":"Offset"},"fields":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"},{"type":"null"}],"default":null,"description":"Columns to include in the response. Pass a comma-separated string or a list. Defaults to all fields.","title":"Fields"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated list of fields to sort by, with optional `asc`/`desc` direction. Example: `\"fieldname1 asc, fieldname2 desc\"`.","title":"Sort"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include the total number of matching rows in the response. Defaults to `true`.","title":"Include Total"},"total_estimation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"When `include_total` is `true` and the estimated row count exceeds this threshold, CKAN returns an estimated total rather than an exact count. Set to `null` (default) to always return an exact count.","title":"Total Estimation Threshold"},"records_format":{"anyOf":[{"enum":["objects","lists","csv","tsv"],"type":"string"},{"type":"null"}],"default":"objects","description":"Format for the returned records. `objects` returns a list of dicts, `lists` returns a list of lists, `csv` and `tsv` return delimited strings. Defaults to `objects`.","title":"Records Format"}},"required":["resource_id"],"title":"DatastoreSearchParams","type":"object"},"DatastoreSearchResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchResult"}},"required":["help","success","result"],"title":"DatastoreSearchResponse","type":"object"},"DatastoreSearchResult":{"properties":{"resource_id":{"description":"The resource ID that was queried.","title":"Resource Id","type":"string"},"fields":{"description":"List of field descriptor objects, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The offset used in the query.","title":"Offset"},"limit":{"description":"The limit used in the query.","title":"Limit","type":"integer"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Filters applied to the query.","title":"Filters"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Indicates whether `total` is included.","title":"Include Total"},"records_format":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Echoed from the request parameter. Format used for `records`.","title":"Records Format"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of matching rows. Present when `include_total` is `true`.","title":"Total"},"total_was_estimated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Whether the total count was estimated rather than exact.","title":"Total Was Estimated"},"total_estimation_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Row count threshold above which total estimation is used. `null` when estimation is not configured.","title":"Total Estimation Threshold"},"records":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"items":{"items":{},"type":"array"},"type":"array"},{"type":"string"}],"description":"Matching rows. Shape depends on `records_format`.","title":"Records"},"_links":{"$ref":"#/components/schemas/DatastoreSearchLinks","description":"Pagination helper URLs. Always present — `next` contains the URL for the next page of results."}},"required":["resource_id","fields","limit","records","_links"],"title":"DatastoreSearchResult","type":"object"},"DatastoreSearchLinks":{"properties":{"start":{"description":"URL to the first page of results with the same parameters.","title":"Start","type":"string"},"next":{"description":"URL to the next page of results.","title":"Next","type":"string"}},"required":["start","next"],"title":"DatastoreSearchLinks","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search":{"post":{"operationId":"datastore_search_post","summary":"Search a DataStore resource (POST)","description":"Identical to the GET form. Use POST to pass parameters as a JSON body, which is useful for large `filters` or `fields` payloads.","tags":["DataStore"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Query a DataStore resource with SQL

> Execute a SQL \`SELECT\` statement against one or more DataStore resources. Useful for aggregations, joins, and complex filtering that \`datastore\_search\` cannot express.\
> \
> Only \`SELECT\` statements are permitted.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchSqlResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchSqlResult"}},"required":["help","success","result"],"title":"DatastoreSearchSqlResponse","type":"object"},"DatastoreSearchSqlResult":{"properties":{"sql":{"description":"The SQL query echoed back from the request.","title":"Sql","type":"string"},"fields":{"description":"List of field descriptor objects for the result columns, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"records":{"description":"List of result row objects.","items":{"additionalProperties":true,"type":"object"},"title":"Records","type":"array"},"records_truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Present and `true` if the result set was truncated at the server-side 32,000-row limit.","title":"Records Truncated"}},"required":["sql","fields","records"],"title":"DatastoreSearchSqlResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search_sql":{"get":{"operationId":"datastore_search_sql_get","summary":"Query a DataStore resource with SQL","description":"Execute a SQL `SELECT` statement against one or more DataStore resources. Useful for aggregations, joins, and complex filtering that `datastore_search` cannot express.\n\nOnly `SELECT` statements are permitted.","tags":["DataStore"],"parameters":[{"name":"sql","in":"query","required":true,"schema":{"title":"Sql","type":"string"},"description":"A single SQL `SELECT` statement to execute against the DataStore. Required. Only `SELECT` statements are permitted — `INSERT`, `UPDATE`, `DELETE`, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. `SELECT * FROM \"<resource_id>\"`)."}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchSqlResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Query a DataStore resource with SQL (POST)

> Identical to the GET form. Use POST for long SQL statements.

```json
{"openapi":"3.1.0","info":{"title":"HDX APIs","version":"2.11.4"},"servers":[{"url":"https://data.humdata.org/api/3/action","description":"HDX Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"HDX API token. Required for all Tabular Data Endpoint requests, including public resources."}},"schemas":{"DatastoreSearchSqlParams":{"properties":{"sql":{"description":"A single SQL `SELECT` statement to execute against the DataStore. Required. Only `SELECT` statements are permitted — `INSERT`, `UPDATE`, `DELETE`, and DDL statements are not allowed. Table names correspond to resource IDs (e.g. `SELECT * FROM \"<resource_id>\"`).","title":"Sql","type":"string"}},"required":["sql"],"title":"DatastoreSearchSqlParams","type":"object"},"DatastoreSearchSqlResponse":{"properties":{"help":{"description":"URL to the API documentation for this action.","title":"Help","type":"string"},"success":{"description":"Whether the request succeeded.","title":"Success","type":"boolean"},"result":{"$ref":"#/components/schemas/DatastoreSearchSqlResult"}},"required":["help","success","result"],"title":"DatastoreSearchSqlResponse","type":"object"},"DatastoreSearchSqlResult":{"properties":{"sql":{"description":"The SQL query echoed back from the request.","title":"Sql","type":"string"},"fields":{"description":"List of field descriptor objects for the result columns, each with `id` and `type` keys.","items":{"additionalProperties":true,"type":"object"},"title":"Fields","type":"array"},"records":{"description":"List of result row objects.","items":{"additionalProperties":true,"type":"object"},"title":"Records","type":"array"},"records_truncated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Present and `true` if the result set was truncated at the server-side 32,000-row limit.","title":"Records Truncated"}},"required":["sql","fields","records"],"title":"DatastoreSearchSqlResult","type":"object"},"ErrorResponse":{"properties":{"success":{"default":false,"description":"Always false for error responses.","title":"Success","type":"boolean"},"error":{"additionalProperties":true,"description":"Error detail object. Always contains a '__type' string. 403/404 errors include a 'message'; validation (409) errors instead carry structured 'query'/'info' fields.","title":"Error","type":"object"}},"required":["error"],"title":"ErrorResponse","type":"object"}}},"paths":{"/datastore_search_sql":{"post":{"operationId":"datastore_search_sql_post","summary":"Query a DataStore resource with SQL (POST)","description":"Identical to the GET form. Use POST for long SQL statements.","tags":["DataStore"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchSqlParams"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatastoreSearchSqlResponse"}}}},"403":{"description":"Forbidden — API token is missing or invalid. Authentication is required for all DataStore requests, including public resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found — the resource_id does not exist in the DataStore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict — Validation Error. The request parameters or SQL were invalid (e.g. missing required parameter, non-SELECT SQL, malformed query, or wrong parameter type).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error — unexpected server-side failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


# Code examples

Python and Javascript examples

The HDX Tabular Data endpoints can be used with many different coding languages and processes in the humanitarian sector. Be mindful of query limits and performance, especially when working with large datasets. See specific code examples below.&#x20;

Note that you can access the endpoints directly in your browser if you are signed in to HDX.

{% tabs %}
{% tab title="Python" %}
**See Python specific examples per endpoint below.**&#x20;

*These examples are tailored to the structure and field names of a specific resource, so when applying it to other resources, the filters and/or SQL will need to be adjusted to match their available columns and schema.*

#### Native query

This code searches an HDX resource where the location\_code field is exactly ‘AFG’, retrieves up to 5 results, and prints the total number of matches in the dataset.

```python
import requests

API_TOKEN = "API_TOKEN" # Replace with your actual token
RESOURCE_ID = "45036735-305b-42ae-9aef-b941d6dcb6d6"
URL = "https://data.humdata.org/api/3/action/datastore_search"


headers = {
    "Authorization": API_TOKEN,
    "Content-Type": "application/json"
}

response = requests.post(
    URL,
    headers=headers,
    json={
        "resource_id": RESOURCE_ID,
        "filters": {"location_code": "AFG"},
        "limit": 5
    }
).json()

# Native query: Get first 5 records where location is 'AFG'
print("Total results:", response["result"]["total"])
for record in response["result"]["records"]:
    print(record)
```

**SQL query**

This code runs a SQL query on an HDX resource to return the first 5 rows where the location\_field contains “AF” (case-insensitive search) and then prints how many rows were retrieved.

```python
import requests

API_TOKEN = "API_TOKEN" # Replace with your actual token
RESOURCE_ID = "45036735-305b-42ae-9aef-b941d6dcb6d6"
URL = "https://data.humdata.org/api/3/action/datastore_search_sql"

sql = f"""
SELECT location_code, sector_name, category, population_status, population,
       reference_period_start, reference_period_end
FROM "{RESOURCE_ID}"
WHERE location_code ILIKE '%AF%'
LIMIT 5
"""

headers = {
    "Authorization": API_TOKEN,
    "Content-Type": "application/json"
}

records = requests.post(URL, headers=headers, json={"sql": sql}) \
    .json().get("result", {}).get("records", [])

# SQL query: Get first 5 records where location contains 'AF'
print("Total results returned:", len(records))
for r in records:
    print(r)
```

{% endtab %}

{% tab title="Javascript" %}
**See Javascript specific examples per endpoint below.**

*These examples are tailored to the structure and field names of a specific resource, so when applying it to other resources, the filters and/or SQL will need to be adjusted to match their available columns and schema.*

#### Native Query

This code queries for rows in the given resource that contain the location code “AFG”, limits the returned rows to 5, and then logs the total number of matches across the dataset to the console.

```javascript
const RESOURCE_ID = "45036735-305b-42ae-9aef-b941d6dcb6d6";
const API_TOKEN = "API_TOKEN"; // Replace with your actual token
const URL = "https://data.humdata.org/api/3/action/datastore_search"

fetch(URL, {
  method: "POST",
  headers: {
    "Authorization": API_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    resource_id: RESOURCE_ID,
    filters: { location_code: "AFG" },
    limit: 5
  })
})
  .then(res => res.json())
  .then(data => {
    console.log("Total results:", data.result.total)
    data.result.records.forEach(record => console.log(record))
  })
```

#### SQL Query

This code runs a SQL query to fetch up to 5 rows from the given resource where the location code contains “AF”, and then logs how many rows were returned.

```javascript
const RESOURCE_ID = "45036735-305b-42ae-9aef-b941d6dcb6d6";
const API_TOKEN = "API_TOKEN"; // Replace with your actual token
const URL = "https://data.humdata.org/api/3/action/datastore_search_sql"

const sql = `
SELECT location_code, sector_name, category, population_status, population,
       reference_period_start, reference_period_end
FROM "${RESOURCE_ID}"
WHERE location_code ILIKE '%AF%'
LIMIT 5
`

fetch(URL, {
  method: "POST",
  headers: {
    "Authorization": API_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ sql })
})
  .then(res => res.json())
  .then(data => {
    const records = (data.result && data.result.records) || []
    console.log("Total results returned:", records.length)
    records.forEach(r => console.log(r))
  })
```

{% endtab %}
{% endtabs %}


# Tools and notebook

Tabular Data endpoints tool integrations and Python notebook

## Integration with tools

The Tabular Data Endpoints can be integrated into various tools to enable automated, repeatable data retrieval and analysis workflows. See examples below.&#x20;

Don’t see your tool listed but want help? Let us know by emailing [hdx@un.org](mailto:undefined)!

### Power BI

Follow this section to connect HDX’s Tabular Data endpoints to PowerBI as a data source. This can also be used as a Power Query in other Microsoft tools, such as Fabric

1. **Open PowerBI Desktop.** Within the PowerBI Desktop application (not the web version), go to Home → Get data. Select “Blank Query”. This will open the Power Query Editor window.

   <div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FsO9bQu6S7RDLAV1UXMMk%2FScreenshot%202026-01-22%20at%2011.55.07.png?alt=media&amp;token=fb4a00aa-f7b2-4b82-a028-04c025965055" alt="" width="563"><figcaption><p>Blank Query</p></figcaption></figure></div>
2. **Open Blank Query.** Click “Advanced Editor” in the top rail.

   <div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FTe9NgcKFccFmWYQxTbnZ%2FScreenshot%202026-01-22%20at%2011.55.58.png?alt=media&amp;token=3dc88c4d-0d94-46c5-b537-2df2937385df" alt="" width="563"><figcaption><p>Advanced Editor</p></figcaption></figure></div>
3. **Paste PowerQuery with Custom Fields.** In the editor, copy and paste this[ PowerQuery](https://github.com/OCHA-DAP/hdx-tabular-data-endpoints-notebook/blob/main/power_query.txt) M script. You must replace the following with your own information.

   1. `BaseUrl` (Endpoint)
   2. `ResourceID`
   3. `ApiToken` (Your own HDX API token)

   <div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2Filk3oH5Bf0RrB9UeDlTG%2FScreenshot%202026-01-22%20at%2011.56.29.png?alt=media&amp;token=e04f3255-b1a1-4a76-902d-75333df2e011" alt="" width="563"><figcaption><p>PowerQuery</p></figcaption></figure></div>
4. **Set the connection to Anonymous.** If prompted for credentials, choose “Anonymous”. If no prompt appears but there is an error, ensure you go to File → Options and settings → Data source settings. Find the entry for your data and clear permissions. Re-run the query which should prompt you to choose Anonymous.
5. **Apply the Query.** Once the preview loads in the Power Query Editor, click “Close & Apply”. Power BI should fetch the full dataset using the pagination logic and filters.

   <div align="left" data-with-frame="true"><figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FA8EWkTLsAknh8WRlDCqf%2FScreenshot%202026-01-22%20at%2011.57.20.png?alt=media&amp;token=7f55009a-0bc7-49e0-8f52-14adb8484ae0" alt="" width="563"><figcaption><p>Apply Query</p></figcaption></figure></div>
6. **\[Optional] Add a Filter.** If you would like to apply a filter, you need to update the PowerQuery to include the filter in the config. See example [here](https://gist.github.com/nadineisabel/4b624edb55763883c28149c795b58030) for an organization filter to IOM. Note this will need to be configured per the resource schema.&#x20;
   1. `OrgFilter` (Param filter)

### Python notebook

We provide a ready-to-run Python `ipynb` notebook showing how to query the Tabular Data endpoints (schema information, native and SQL) for Python scripts and pipelines. You can open it directly in your browser via GitHub and test queries without needing to install anything locally.

**Open the Python notebook** [**here**](https://github.com/OCHA-DAP/hdx-tabular-data-endpoints-notebook/tree/main)**.**

**Important:**

* You must provide your own HDX API token in the notebook.
* Never commit your token or share it publicly! Treat it like a password.

**The notebook covers:**

* Searching for resources using the HDX metadata API (`package_search` endpoint)
* Making a minimal native query “probe” call with  `limit=1`&#x20;
* Use SQL query to join two resources with a common column
* Filter in both native and SQL queries
* Fetching data with filters and pagination


# Troubleshooting and error handling

Need help with the Tabular Data endpoints? Look no further.

### Pagination

The Tabular Data Endpoints (native and SQL) support pagination which is a technique used in API design and development to retrieve large data sets in a structured and manageable manner. The default limit is 100 records with a maximum limitation of 32,000 for both native and SQL queries.

It is recommended to use pagination to retrieve larger datasets and avoid timeouts or memory issues. To further optimize performance, use the HDX API’s filtering capabilities to limit the size of the data payload returned in each request.

#### Native Query (`datastore_search`)

Pagination is supported via the limit and offset parameters:

* `limit`: Number of records to return per page (default is 100, maximum is 32,000).
* `offset`: The starting point (index) for the next page of results.

This example retrieves 100 records starting from the 201st record (offset is zero-based): `https://data.humdata.org/api/3/action/datastore_search?id=<resource_id>&`**`limit=100&offset=200`**

To paginate through the entire dataset:

1. Start with `offset=0`.
2. Increment the offset by the limit (e.g., `offset=100`, `offset=200`, etc.) until `result["records"]` is empty.

#### SQL Query (`datastore_search_sql`)

Pagination is supported via SQL's `LIMIT` and `OFFSET` clauses:

Example: `SELECT * FROM "<resource_id>" WHERE country = 'Kenya' LIMIT 100 OFFSET 200`

Encoded URL: `https://data.humdata.org/api/3/action/datastore_search_sql?sql=SELECT+*+FROM+"<resource_id>"+WHERE+country='Kenya'+LIMIT+100+OFFSET+200`

* Always use `ORDER BY` with pagination in SQL to ensure consistent result ordering across pages.
* SQL-based pagination is more flexible but puts more load on the server; use filters and limits strategically.
* Use SQL filters to retrieve only the data you need and reduce system load.

### Authentication and permissions

* **Symptom: 403 Forbidden**
* Likely cause: Missing or invalid HDX API token in the Authorization header
* Fix: Add a valid token and retry. Example with curl:

`curl -H "Authorization: <your-api-token>" \ "https://data.humdata.org/api/3/action/datastore_search?resource_id=<id>&limit=1"`

If you are testing in a browser, make sure you are logged in to HDX as described in the Authentication section.

### Resource and dataset issues

* **Symptom: 404 Not Found or `{ "success": false, "error": "Not found" }`**
* Likely cause: Wrong resource\_id or the resource was removed or unpublished
* Fix: Confirm the resource\_id from the dataset page or via package\_show and verify the resource still exists. Also verify that the resource has Tabular Data endpoint access enabled. Look for `datastore_active` in the CKAN metadata.<br>
* **Symptom: Empty records with total greater than zero**
* Likely cause: Using an offset beyond the number of rows or incompatible filter values
* Fix: Remove filters and set limit to a small value to confirm data is present: `.../datastore_search?resource_id=<id>&limit=5`
* Then add filters back one at a time.

### SQL query errors

* **Symptom: `{ "success": false, "error": "Error parsing query" }`**
* Likely cause: Unquoted resource\_id or unencoded SQL
* Fix: Quote the table name and URL encode the entire SQL: `sql=SELECT%20*%20FROM%20"%3Cresource_id%3E"%20WHERE%20country%3D'Kenya'%20LIMIT%205`<br>
* **Symptom: Syntax error near `ORDER` or `LIMIT`**
* Likely cause: `ORDER BY` must reference valid column names and comes before `LIMIT` and `OFFSET`
* Fix: Validate column names through a small select first, then add `ORDER BY`, then `LIMIT` and `OFFSET` as shown in the SQL examples.

### Performance and rate limiting

* **Symptom: 429 Too Many Requests**
* Likely cause: High request concurrency or scraping patterns
* Fix: Back off and retry with exponential backoff, reduce parallelism, and page through results. The user’s IP is rate limited at 60 requests per minute so plan for modest throughput.

### Data types and schema drift

*For alerts on any changes to the data resources used within the Tabular Data Endpoints, enable notifications to be alerted about data schema changes. See more information* [*here*](https://docs.humdata.org/find/find-data/staying-up-to-date-with-hdx)*.*

* **Symptom: Type errors or unexpected nulls**
* Likely cause: Mismatched types in filters or recent schema change in the source file
* Fix: Inspect a sample of rows first to confirm types. If `year` is stored as text, pass `"2024"` rather than `2024`. If the maintainer updated the schema, refresh your assumptions and adjust the query accordingly.<br>
* **Symptom: Date filters fail to match**
* Likely cause: Inconsistent date formats in source
* Fix: Use exact string matching that reflects the stored format, or use SQL functions where supported to normalize formats.


# Humanitarian API

Learn more about the HDX Humanitarian API.

### Introduction

The HDX Humanitarian API (HAPI) provides access to standardized humanitarian indicators from multiple sources through a single API so you can automate workflows, analysis, and visualizations. Our initial coverage aligns with the data included in the [HDX Data Grids](https://data.humdata.org/dashboards/overview-of-data-grids). HDX HAPI is designed for developers, researchers and anyone interested in accessing a centralized source of humanitarian data for analysis and decision-making.&#x20;

HAPI is a REST API. Like most web-based APIs it follows Representational State Transfer principles, so you can use it from any programming language or tool that can make an HTTP request. HAPI is currently in beta.

### Full reference and tutorials

This page set is a practical guide. For the complete, always-current list of endpoints and fields, see the API reference page and the interactive sandbox at [hapi.humdata.org/docs](https://hapi.humdata.org/docs).&#x20;

For longer tutorials and per-theme data usage guides, see the full HAPI documentation at [hdx-hapi.readthedocs.io](https://hdx-hapi.readthedocs.io/en/latest/).

### How HAPI relates to the other HDX APIs

HAPI is one of the portfolio of HDX APIs. The [Metadata endpoints](https://docs.humdata.org/build/hdx-apis/metadata-endpoints) return metadata about datasets on HDX, such as who published a dataset and when. HAPI returns the data values inside those datasets in a standard way.

The [Tabular Data Endpoints](https://docs.humdata.org/build/hdx-apis/tabular-data-endpoints) let you query the contents of one tabular resource in detail. HAPI goes a step further by standardizing selected indicators across many HDX sources so they can be combined and compared.

Use HAPI when you want interoperable indicators across multiple sources and locations. This is data maintained by HDX through standardized HAPI pipelines. Use the Tabular Data Endpoints when you want to query a single specific resource which is directly from a contributor, not standardized HAPI data.

HAPI data comes from selected datasets on HDX. Numerical values are unchanged from the source. Only supporting fields, such as sector names, are standardized so that indicators from different sources can be combined and compared. See the HDX HAPI organization [here](https://data.humdata.org/organization/hdx-hapi).

### Building a HAPI query

Every HAPI query combines four things: the base URL, a theme, an app identifier, and optional filters that narrow the results.

<figure><img src="https://1756329736-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPYX6VfEjVd6ssH4AU60M%2Fuploads%2FjvNM2k8gnzUOa2KUdUq7%2FScreenshot%202026-07-21%20at%2010.00.07.png?alt=media&amp;token=02cf854d-9938-4534-9c7a-88b30674529b" alt=""><figcaption></figcaption></figure>

`https://hapi.humdata.org/api/v2/coordination-context/operational-presence?app_identifier={your_app_identifier}&location_code=AFG`

\
The following pages explain where to find the themes and filters, how to generate an app identifier, and how to page through results.

### Feedback and support

HAPI is in beta and we are seeking feedback. To report a bug or request a feature or indicator, email <hdx@un.org>.


# Available data in HAPI

See what data is available on HAPI below.

### Themes and sub-categories

HAPI organizes indicators into themes, each with sub-categories. You query a sub-category directly through its path, for example coordination-context/operational-presence.

The current themes are:

1\. **Affected people:** Humanitarian needs, refugees and persons of concern, internally displaced persons, and returnees

2\. **Coordination and context:** Conflict events, funding, national risk, and operational presence

3\. **Food security, nutrition and poverty:** Food prices, food security phases, and poverty rate

4\. **Geography and infrastructure:** Baseline population

5\. **Climate:** Rainfall

6\. **Metadata:** Supporting tables such as administrative levels, sectors, organizations, currencies, and resources

For the full and current list of sub-categories and the fields each one returns, see the API reference page or the per-theme data usage guides at [hdx-hapi.readthedocs.io](hdx-hapi.readthedocs.iohttps://hdx-hapi.readthedocs.io/en/latest/).

### Coverage

HAPI's initial coverage aligned with the HDX Data Grids, the foundational data on HDX needed to understand a humanitarian context. Because coverage changes as sources are added, the most reliable view is the live availability dashboard, which shows which indicators are available for which locations:

Data availability dashboard: <https://ocha-dap.github.io/viz-hapi-availability/>

### Update frequency

HAPI is refreshed daily from its source datasets on HDX. The update frequency of each source dataset varies from daily to weekly, yearly, or as needed, so the freshness of a given indicator depends on its source. Every row in the data sub-categories includes a resource\_hdx\_id that links back to the source dataset, where you can check its update schedule and history. The metadata sub-categories are reference tables and do not carry it.

The time period covered also varies by indicator. Conflict events, for example, go back as far as 1997, while operational presence holds only the current year.

To be notified when a source dataset changes, see [staying up to date with HDX](https://docs.humdata.org/find/staying-up-to-date-with-hdx).

<br>


# 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](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.&#x20;

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.


# API reference

Full parameter and response reference for HAPI.

## API reference

This reference is generated directly from HAPI. It lists every endpoint, its parameters, and the fields it returns, grouped by theme in the pages below.

Every request needs an app identifier, passed as the `app_identifier` parameter or the `X-HDX-HAPI-APP-IDENTIFIER` header. You can also try any endpoint live in the interactive sandbox at hapi.humdata.org/docs.

### Browse by theme

* **Generate App Identifier:** Create the identifier every request needs
* **Affected People:** Humanitarian needs, refugees and persons of concern, IDPs, returnees
* **Coordination & Context:** Conflict events, funding, national risk, operational presence
* **Food Security, Nutrition & Poverty:** Food prices, food security phases, poverty rate
* **Geography & Infrastructure:** Baseline population
* **Climate:** Rainfall and related indicators
* **Metadata:** Supporting reference tables: admin levels, sectors, organizations, currencies, resources
* **Util:** Service and utility endpoints
* **Models:** The data schemas shared across endpoints

To generate a client or import HAPI into your own tools, use **Download OpenAPI spec**.


# Generate App Identifier

## Get an app identifier by encoding an application name and email

> Encode an application name and email address in base64 to serve as an client identifier in HDX HAPI calls.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/encode_app_identifier":{"get":{"tags":["Generate App Identifier"],"summary":"Get an app identifier by encoding an application name and email","description":"Encode an application name and email address in base64 to serve as an client identifier in HDX HAPI calls.","operationId":"get_encoded_identifier_api_v2_encode_app_identifier_get","parameters":[{"name":"application","in":"query","required":true,"schema":{"type":"string","minLength":4,"maxLength":512,"description":"A name for the calling application.","title":"Application"},"description":"A name for the calling application."},{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email","maxLength":512,"description":"An email address.","title":"Email"},"description":"An email address."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifierResponse"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"IdentifierResponse":{"properties":{"encoded_app_identifier":{"type":"string","maxLength":512,"title":"Encoded App Identifier","description":"Base64 encoded app_identifier compiled from application name and email address"}},"type":"object","required":["encoded_app_identifier"],"title":"IdentifierResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Affected People

## Get refugees data

> UNHCR's Refugee data provides information about displaced people in a crisis. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/affected\\\_people/#refugees-persons-of-concern">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/affected\\_people/#refugees-persons-of-concern">HDX) HAPI documentation\</a>, and the \<a href="[https://data.humdata.org/dataset/unhcr-population-data-for-world">original](https://data.humdata.org/dataset/unhcr-population-data-for-world">original) HDX source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/affected-people/refugees-persons-of-concern":{"get":{"tags":["Affected People"],"summary":"Get refugees data","description":"UNHCR's Refugee data provides information about displaced people in a crisis. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/affected_people/#refugees-persons-of-concern\">HDX HAPI documentation</a>, and the <a href=\"https://data.humdata.org/dataset/unhcr-population-data-for-world\">original HDX source</a> website.","operationId":"get_refugees_api_v2_affected_people_refugees_persons_of_concern_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"population_group","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/PopulationGroup","maxLength":32},{"type":"null"}],"description":"Filter the response by the population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>","title":"Population Group"},"description":"Filter the response by the population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},{"name":"population_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a lower bound for the population.","title":"Population Min"},"description":"Filter the response by a lower bound for the population."},{"name":"population_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a upper bound for the population.","title":"Population Max"},"description":"Filter the response by a upper bound for the population."},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Gender","maxLength":3},{"type":"null"}],"description":"Filter the response by the gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>","title":"Gender"},"description":"Filter the response by the gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},{"name":"age_range","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data.","title":"Age Range"},"description":"Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},{"name":"origin_location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Origin Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"origin_location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Origin Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"origin_has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Origin Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"origin_in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"Origin In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"asylum_location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Asylum Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"asylum_location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Asylum Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"asylum_has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Asylum Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"asylum_in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"Asylum In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_RefugeesResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_RefugeesResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RefugeesResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[RefugeesResponse]"},"RefugeesResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"population_group":{"$ref":"#/components/schemas/PopulationGroup","description":"The population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"origin_location_code":{"type":"string","maxLength":128,"title":"Origin Location Code","description":"Location of origin p-code (ISO-3)"},"origin_location_name":{"type":"string","maxLength":512,"title":"Origin Location Name","description":"Location of origin name"},"asylum_location_code":{"type":"string","maxLength":128,"title":"Asylum Location Code","description":"Location of asylum p-code (ISO-3)"},"asylum_location_name":{"type":"string","maxLength":512,"title":"Asylum Location Name","description":"Location of asylum name"}},"type":"object","required":["resource_hdx_id","population_group","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end","origin_location_code","origin_location_name","asylum_location_code","asylum_location_name"],"title":"RefugeesResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get humanitarian needs data

> OCHA's Humanitarian Needs data, based on the Joint and Intersectoral Analysis Framework (JIAF), provides information about the number of people in need during a crisis. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/affected\\\_people/#humanitarian-needs">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/affected\\_people/#humanitarian-needs">HDX) HAPI documentation\</a>, and the \<a href="[https://www.jiaf.info/">original](https://www.jiaf.info/">original) JIAF source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/affected-people/humanitarian-needs":{"get":{"tags":["Affected People"],"summary":"Get humanitarian needs data","description":"OCHA's Humanitarian Needs data, based on the Joint and Intersectoral Analysis Framework (JIAF), provides information about the number of people in need during a crisis. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/affected_people/#humanitarian-needs\">HDX HAPI documentation</a>, and the <a href=\"https://www.jiaf.info/\">original JIAF source</a> website.","operationId":"get_humanitarian_needs_api_v2_affected_people_humanitarian_needs_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"A category combining gender, age range, disability marker and population group information","title":"Category"},"description":"A category combining gender, age range, disability marker and population group information"},{"name":"sector_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the sector code.","title":"Sector Code"},"description":"Filter the response by the sector code."},{"name":"population_status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/PopulationStatus","maxLength":32},{"type":"null"}],"description":"Filter the response by the population status, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-status\">here.</a>","title":"Population Status"},"description":"Filter the response by the population status, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-status\">here.</a>"},{"name":"population_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a lower bound for the population.","title":"Population Min"},"description":"Filter the response by a lower bound for the population."},{"name":"population_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a upper bound for the population.","title":"Population Max"},"description":"Filter the response by a upper bound for the population."},{"name":"sector_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the sector name.","title":"Sector Name"},"description":"Filter the response by the sector name."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_HumanitarianNeedsResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"PopulationStatus":{"type":"string","enum":["AFF","INN","TGT","REA","all"],"title":"PopulationStatus"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_HumanitarianNeedsResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/HumanitarianNeedsResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[HumanitarianNeedsResponse]"},"HumanitarianNeedsResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"sector_code":{"type":"string","maxLength":32,"title":"Sector Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"category":{"type":"string","maxLength":128,"title":"Category","description":"A category combining gender, age range, disability marker and population group information"},"population_status":{"$ref":"#/components/schemas/PopulationStatus","description":"The population status, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-status\">here.</a>"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"sector_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Sector Name","description":"The name of the sector"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","sector_code","category","population_status","population","reference_period_start","reference_period_end","sector_name"],"title":"HumanitarianNeedsResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## GET /api/v2/affected-people/idps

> Get idps data

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/affected-people/idps":{"get":{"tags":["Affected People"],"summary":"Get idps data","operationId":"get_idps_api_v2_affected_people_idps_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_IdpsResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_IdpsResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/IdpsResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[IdpsResponse]"},"IdpsResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"reporting_round":{"type":"integer","title":"Reporting Round","description":"Data collection round number"},"assessment_type":{"$ref":"#/components/schemas/DTMAssessmentType","description":"Either baseline assessment (BA),site assessment (SA) or event track (ETT)"},"operation":{"type":"string","title":"Operation","description":"Name of DTM Operation for which the data was collected"},"population":{"type":"integer","title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","reporting_round","assessment_type","operation","population","reference_period_start","reference_period_end"],"title":"IdpsResponse"},"DTMAssessmentType":{"type":"string","enum":["BA","ETT","SA"],"title":"DTMAssessmentType"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## GET /api/v2/affected-people/returnees

> Get returnees data

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/affected-people/returnees":{"get":{"tags":["Affected People"],"summary":"Get returnees data","operationId":"get_returnees_api_v2_affected_people_returnees_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"population_group","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/PopulationGroup"},{"type":"null"}],"description":"Filter the response by the population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>","title":"Population Group"},"description":"Filter the response by the population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Gender"},{"type":"null"}],"description":"Filter the response by the gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>","title":"Gender"},"description":"Filter the response by the gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},{"name":"age_range","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data.","title":"Age Range"},"description":"Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},{"name":"min_age","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation","title":"Min Age"},"description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},{"name":"max_age","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range","title":"Max Age"},"description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},{"name":"origin_location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Origin Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"origin_location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Origin Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"origin_has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Origin Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"origin_in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"Origin In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"asylum_location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Asylum Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"asylum_location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Asylum Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"asylum_has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Asylum Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"asylum_in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"Asylum In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_ReturneesResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_ReturneesResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ReturneesResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[ReturneesResponse]"},"ReturneesResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"population_group":{"$ref":"#/components/schemas/PopulationGroup","description":"The population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"origin_location_code":{"type":"string","maxLength":128,"title":"Origin Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"origin_location_name":{"type":"string","maxLength":512,"title":"Origin Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"asylum_location_code":{"type":"string","maxLength":128,"title":"Asylum Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"asylum_location_name":{"type":"string","maxLength":512,"title":"Asylum Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["resource_hdx_id","population_group","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end","origin_location_code","origin_location_name","asylum_location_code","asylum_location_name"],"title":"ReturneesResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Coordination & Context

## Get the list of organizations present and in which humanitarian sectors they are working

> OCHA's 3W (Who is doing What Where) Operational Presence data provides information about which organizations are working in different locations affected by a crisis. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/coordination\\\_and\\\_context/#who-is-doing-what-where-operational-presence">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/coordination\\_and\\_context/#who-is-doing-what-where-operational-presence">HDX) HAPI documentation\</a>, and the \<a href="[https://3w.unocha.org/">original](https://3w.unocha.org/">original) OCHA 3W source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/coordination-context/operational-presence":{"get":{"tags":["Coordination & Context"],"summary":"Get the list of organizations present and in which humanitarian sectors they are working","description":"OCHA's 3W (Who is doing What Where) Operational Presence data provides information about which organizations are working in different locations affected by a crisis. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/coordination_and_context/#who-is-doing-what-where-operational-presence\">HDX HAPI documentation</a>, and the <a href=\"https://3w.unocha.org/\">original OCHA 3W source</a> website.","operationId":"get_operational_presence_api_v2_coordination_context_operational_presence_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"sector_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by sector codes, which describe the humanitarian sector to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_sector_api_v1_metadata_sector_get\" target=\"_blank\">sector endpoint</a> for details.","title":"Sector Code"},"description":"Filter the response by sector codes, which describe the humanitarian sector to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_sector_api_v1_metadata_sector_get\" target=\"_blank\">sector endpoint</a> for details."},{"name":"sector_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by sector names, which describe the humanitarian sector to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_sector_api_v1_metadata_sector_get\" target=\"_blank\">sector endpoint</a> for details.","title":"Sector Name"},"description":"Filter the response by sector names, which describe the humanitarian sector to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_sector_api_v1_metadata_sector_get\" target=\"_blank\">sector endpoint</a> for details."},{"name":"org_acronym","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the acronym of the organization to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_org_api_v1_metadata_org_get\" target=\"_blank\">org endpoint</a> for details.","title":"Org Acronym"},"description":"Filter the response by the acronym of the organization to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_org_api_v1_metadata_org_get\" target=\"_blank\">org endpoint</a> for details."},{"name":"org_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the name of the organization to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_org_api_v1_metadata_org_get\" target=\"_blank\">org endpoint</a> for details.","title":"Org Name"},"description":"Filter the response by the name of the organization to which the operational presence applies. See the <a href=\"/docs#/Metadata/get_org_api_v1_metadata_org_get\" target=\"_blank\">org endpoint</a> for details."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_OperationalPresenceResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_OperationalPresenceResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OperationalPresenceResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[OperationalPresenceResponse]"},"OperationalPresenceResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"org_acronym":{"type":"string","maxLength":32,"title":"Org Acronym","description":"The organization acronym"},"org_name":{"type":"string","maxLength":512,"title":"Org Name","description":"The organization name"},"sector_code":{"type":"string","maxLength":32,"title":"Sector Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"sector_name":{"type":"string","maxLength":512,"title":"Sector Name","description":"The name of the sector"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"org_type_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Code","description":"The code referring to the organization type"},"org_type_description":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Org Type Description","description":"A description of the organization type"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","org_acronym","org_name","sector_code","sector_name","reference_period_start","reference_period_end","org_type_code","org_type_description"],"title":"OperationalPresenceResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get funding data

> OCHA's funding data from the Financial Tracking Service provides information on humanitarian aid contributions. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/coordination\\\_and\\\_context/#funding">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/coordination\\_and\\_context/#funding">HDX) HAPI documentation\</a>, and the \<a href="[https://fts.unocha.org/home/2024/donors/view">original](https://fts.unocha.org/home/2024/donors/view">original) FTS source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/coordination-context/funding":{"get":{"tags":["Coordination & Context"],"summary":"Get funding data","description":"OCHA's funding data from the Financial Tracking Service provides information on humanitarian aid contributions. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/coordination_and_context/#funding\">HDX HAPI documentation</a>, and the <a href=\"https://fts.unocha.org/home/2024/donors/view\">original FTS source</a> website.","operationId":"get_funding_api_v2_coordination_context_funding_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"appeal_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Filter the response by a unique code given by FTS to each appeal","title":"Appeal Code"},"description":"Filter the response by a unique code given by FTS to each appeal"},{"name":"appeal_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Filter the response by the type of the appeal, such as flash or HRP","title":"Appeal Type"},"description":"Filter the response by the type of the appeal, such as flash or HRP"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_FundingResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_FundingResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FundingResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[FundingResponse]"},"FundingResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"appeal_code":{"type":"string","maxLength":64,"title":"Appeal Code","description":"A unique code given by FTS to each appeal"},"appeal_name":{"type":"string","maxLength":256,"title":"Appeal Name","description":"Name of the appeal"},"appeal_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Appeal Type","description":"The type of the appeal, such as flash or HRP"},"requirements_usd":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Requirements Usd","description":"The funding requirements in US dollars"},"funding_usd":{"type":"number","minimum":0,"title":"Funding Usd","description":"The actual funding in US dollars"},"funding_pct":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Funding Pct","description":"The percentage of required funding received by the appeal"},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["resource_hdx_id","appeal_code","appeal_name","appeal_type","requirements_usd","funding_usd","funding_pct","location_code","location_name","reference_period_start","reference_period_end"],"title":"FundingResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get the list of conflict events

> Armed Conflict Location & Events Data from ACLED. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/coordination\\\_and\\\_context/#conflict-events">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/coordination\\_and\\_context/#conflict-events">HDX) HAPI documentation\</a>, and the \<a href="[https://acleddata.com/">original](https://acleddata.com/">original) ACLED source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/coordination-context/conflict-events":{"get":{"tags":["Coordination & Context"],"summary":"Get the list of conflict events","description":"Armed Conflict Location & Events Data from ACLED. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/coordination_and_context/#conflict-events\">HDX HAPI documentation</a>, and the <a href=\"https://acleddata.com/\">original ACLED source</a> website.","operationId":"get_conflict_event_api_v2_coordination_context_conflict_events_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EventType"},{"type":"null"}],"description":"Filter the response by the ACLED event-type categories (non-mutually exclusive), available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#event-type\">here.</a>","title":"Event Type"},"description":"Filter the response by the ACLED event-type categories (non-mutually exclusive), available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#event-type\">here.</a>"},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_ConflictEventResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"EventType":{"type":"string","enum":["civilian_targeting","demonstration","political_violence"],"title":"EventType"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_ConflictEventResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ConflictEventResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[ConflictEventResponse]"},"ConflictEventResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"event_type":{"$ref":"#/components/schemas/EventType","description":"Filter the response by the ACLED event-type categories (non-mutually exclusive), available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#event-type\">here.</a>"},"events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Events","description":"The number of events with the given `event_type`"},"fatalities":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fatalities","description":"The number of fatalities due to the given `event_type`"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","event_type","events","fatalities","reference_period_start","reference_period_end"],"title":"ConflictEventResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get national risk data

> European Commission national risk data from the INFORM-risk framework. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/coordination\\\_and\\\_context/#national-risk">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/coordination\\_and\\_context/#national-risk">HDX) HAPI documentation\</a>, and the \<a href="[https://drmkc.jrc.ec.europa.eu/inform-index/INFORM-Risk">original](https://drmkc.jrc.ec.europa.eu/inform-index/INFORM-Risk">original) INFORM-risk source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/coordination-context/national-risk":{"get":{"tags":["Coordination & Context"],"summary":"Get national risk data","description":"European Commission national risk data from the INFORM-risk framework. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/coordination_and_context/#national-risk\">HDX HAPI documentation</a>, and the <a href=\"https://drmkc.jrc.ec.europa.eu/inform-index/INFORM-Risk\">original INFORM-risk source</a> website.","operationId":"get_national_risk_api_v2_coordination_context_national_risk_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"risk_class","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/RiskClass"},{"type":"null"}],"description":"Filter the response by the INFORM risk class, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#risk-class\">here.</a>","title":"Risk Class"},"description":"Filter the response by the INFORM risk class, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#risk-class\">here.</a>"},{"name":"global_rank_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a lower bound for the Global Rank.","title":"Global Rank Min"},"description":"Filter the response by a lower bound for the Global Rank."},{"name":"global_rank_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by an upper bound for the Global Rank.","title":"Global Rank Max"},"description":"Filter the response by an upper bound for the Global Rank."},{"name":"overall_risk_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by a lower bound for the Overall Risk.","title":"Overall Risk Min"},"description":"Filter the response by a lower bound for the Overall Risk."},{"name":"overall_risk_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by an upper bound for the Overall Risk.","title":"Overall Risk Max"},"description":"Filter the response by an upper bound for the Overall Risk."},{"name":"hazard_exposure_risk_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by a lower bound for the Hazard Exposure Risk.","title":"Hazard Exposure Risk Min"},"description":"Filter the response by a lower bound for the Hazard Exposure Risk."},{"name":"hazard_exposure_risk_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by an upper bound for the Hazard Exposure Risk.","title":"Hazard Exposure Risk Max"},"description":"Filter the response by an upper bound for the Hazard Exposure Risk."},{"name":"vulnerability_risk_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by a lower bound for the Vulnerability Risk.","title":"Vulnerability Risk Min"},"description":"Filter the response by a lower bound for the Vulnerability Risk."},{"name":"vulnerability_risk_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by an upper bound for the Vulnerability Risk.","title":"Vulnerability Risk Max"},"description":"Filter the response by an upper bound for the Vulnerability Risk."},{"name":"coping_capacity_risk_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by a lower bound for the Coping Capacity Risk.","title":"Coping Capacity Risk Min"},"description":"Filter the response by a lower bound for the Coping Capacity Risk."},{"name":"coping_capacity_risk_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Filter the response by a lower bound for the Coping Capacity Risk.","title":"Coping Capacity Risk Max"},"description":"Filter the response by a lower bound for the Coping Capacity Risk."},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_NationalRiskResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"RiskClass":{"type":"string","enum":["1","2","3","4","5"],"title":"RiskClass"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_NationalRiskResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/NationalRiskResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[NationalRiskResponse]"},"NationalRiskResponse":{"properties":{"risk_class":{"$ref":"#/components/schemas/RiskClass","description":"The INFORM risk class, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#risk-class\">here.</a>"},"global_rank":{"type":"integer","maximum":250,"minimum":1,"title":"Global Rank","description":"The rank of the country based on `overall_risk`. Higher rank (smaller number) is associated with more risk."},"overall_risk":{"type":"number","maximum":10,"minimum":0,"title":"Overall Risk","description":"The INFORM composite risk index, based on a combination of 54 indicators into three dimensions of risk: hazard and exposure, vulnerability, and lack of coping capacity. Risk score is given out of 10."},"hazard_exposure_risk":{"type":"number","maximum":10,"minimum":0,"title":"Hazard Exposure Risk","description":"Risk due to events that may occur, and exposure to them. Risk score is given out of 10. "},"vulnerability_risk":{"type":"number","maximum":10,"minimum":0,"title":"Vulnerability Risk","description":"Risk due to hazard susceptibility. Risk score is given out of 10."},"coping_capacity_risk":{"type":"number","maximum":10,"minimum":0,"title":"Coping Capacity Risk","description":"Risk due to lack of coping capacity to alleviate hazard impact. Risk score is given out of 10."},"meta_missing_indicators_pct":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"title":"Meta Missing Indicators Pct","description":"The average of the total number of years older than the reference year per indicator, to account for any older data used as a proxy"},"meta_avg_recentness_years":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Meta Avg Recentness Years","description":"The average of the total number of years older than the reference year per indicator, to account for any older data used as a proxy)"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["risk_class","global_rank","overall_risk","hazard_exposure_risk","vulnerability_risk","coping_capacity_risk","meta_missing_indicators_pct","meta_avg_recentness_years","reference_period_start","reference_period_end","resource_hdx_id","location_code","location_name"],"title":"NationalRiskResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Food Security, Nutrition & Poverty

## Get food security data

> Integrated Food Security Phase Classification from the IPC. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/food\\\_security\\\_and\\\_nutrition/#food-security">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/food\\_security\\_and\\_nutrition/#food-security">HDX) HAPI documentation\</a>, and the \<a href="[https://www.ipcinfo.org/ipcinfo-website/ipc-overview-and-classification-system/ipc-acute-food-insecurity-classification/en/">original](https://www.ipcinfo.org/ipcinfo-website/ipc-overview-and-classification-system/ipc-acute-food-insecurity-classification/en/">original) IPC source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/food-security-nutrition-poverty/food-security":{"get":{"tags":["Food Security, Nutrition & Poverty"],"summary":"Get food security data","description":"Integrated Food Security Phase Classification from the IPC. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/food_security_and_nutrition/#food-security\">HDX HAPI documentation</a>, and the <a href=\"https://www.ipcinfo.org/ipcinfo-website/ipc-overview-and-classification-system/ipc-acute-food-insecurity-classification/en/\">original IPC source</a> website.","operationId":"get_food_security_api_v2_food_security_nutrition_poverty_food_security_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"ipc_phase","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/IPCPhase"},{"type":"null"}],"description":"Filter the response by the IPC phase, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-code\">here.</a>","title":"Ipc Phase"},"description":"Filter the response by the IPC phase, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-code\">here.</a>"},{"name":"ipc_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/IPCType"},{"type":"null"}],"description":"Filter the response by the IPC type, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-type\">here.</a>","title":"Ipc Type"},"description":"Filter the response by the IPC type, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-type\">here.</a>"},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_FoodSecurityResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"IPCPhase":{"type":"string","enum":["1","2","3","4","5","3+","all"],"title":"IPCPhase"},"IPCType":{"type":"string","enum":["current","first projection","second projection"],"title":"IPCType"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_FoodSecurityResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FoodSecurityResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[FoodSecurityResponse]"},"FoodSecurityResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"ipc_phase":{"type":"string","maxLength":32,"title":"Ipc Phase","description":"The IPC phase, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-code\">here.</a>"},"ipc_type":{"type":"string","maxLength":32,"title":"Ipc Type","description":"The IPC type, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-type\">here.</a>"},"population_in_phase":{"type":"integer","title":"Population In Phase","description":"The number of people in the IPC phase"},"population_fraction_in_phase":{"type":"number","title":"Population Fraction In Phase","description":"The fraction of people in the IPC phase"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","ipc_phase","ipc_type","population_in_phase","population_fraction_in_phase","reference_period_start","reference_period_end"],"title":"FoodSecurityResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get food prices

> The World Food Programme (WFP) food prices data provides information about food prices for a range of commodities at markets across the world. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/food\\\_security\\\_and\\\_nutrition/#food-prices">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/food\\_security\\_and\\_nutrition/#food-prices">HDX) HAPI documentation\</a>, and the \<a href="[https://dataviz.vam.wfp.org/economic/prices">original](https://dataviz.vam.wfp.org/economic/prices">original) WFP source\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/food-security-nutrition-poverty/food-prices-market-monitor":{"get":{"tags":["Food Security, Nutrition & Poverty"],"summary":"Get food prices","description":"The World Food Programme (WFP) food prices data provides information about food prices for a range of commodities at markets across the world. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/food_security_and_nutrition/#food-prices\">HDX HAPI documentation</a>, and the <a href=\"https://dataviz.vam.wfp.org/economic/prices\">original WFP source</a> website.","operationId":"get_food_price_api_v2_food_security_nutrition_poverty_food_prices_market_monitor_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"market_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the unique code identifying the market","title":"Market Code"},"description":"Filter the response by the unique code identifying the market"},{"name":"market_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the name of the market","title":"Market Name"},"description":"Filter the response by the name of the market"},{"name":"commodity_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the unique code identifying the commodity","title":"Commodity Code"},"description":"Filter the response by the unique code identifying the commodity"},{"name":"commodity_category","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/CommodityCategory"},{"type":"null"}],"description":"Filter the response by the food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>","title":"Commodity Category"},"description":"Filter the response by the food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},{"name":"commodity_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the name of the commodity","title":"Commodity Name"},"description":"Filter the response by the name of the commodity"},{"name":"price_flag","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/PriceFlag"},{"type":"null"}],"description":"Filter the response by the pre-processing characteristics of food prices, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-flag\">here.</a>","title":"Price Flag"},"description":"Filter the response by the pre-processing characteristics of food prices, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-flag\">here.</a>"},{"name":"price_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/PriceType"},{"type":"null"}],"description":"Filter the response by the point in the supply chain at which the price is determined, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-type\">here.</a>","title":"Price Type"},"description":"Filter the response by the point in the supply chain at which the price is determined, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-type\">here.</a>"},{"name":"price_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"Filter the response by a lower bound for the price.","title":"Price Min"},"description":"Filter the response by a lower bound for the price."},{"name":"price_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"description":"Filter the response by a upper bound for the price.","title":"Price Max"},"description":"Filter the response by a upper bound for the price."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_FoodPriceResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"},"PriceFlag":{"type":"string","enum":["actual","aggregate","actual,aggregate"],"title":"PriceFlag"},"PriceType":{"type":"string","enum":["Farm Gate","Producer","Retail","Wholesale"],"title":"PriceType"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_FoodPriceResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FoodPriceResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[FoodPriceResponse]"},"FoodPriceResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Unique resource UUID on HDX"},"market_code":{"type":"string","maxLength":32,"title":"Market Code","description":"The unique code identifying the market"},"market_name":{"type":"string","maxLength":512,"title":"Market Name","description":"The name of the market"},"commodity_code":{"type":"string","maxLength":32,"title":"Commodity Code","description":"The unique code identifying the commodity"},"commodity_name":{"type":"string","maxLength":512,"title":"Commodity Name","description":"The name of the commodity"},"commodity_category":{"$ref":"#/components/schemas/CommodityCategory","description":"The food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},"currency_code":{"type":"string","maxLength":32,"title":"Currency Code","description":"ISO-4217 currency code"},"unit":{"type":"string","maxLength":32,"title":"Unit","description":"The unit of the commodity, such as weight or number"},"price_flag":{"$ref":"#/components/schemas/PriceFlag","description":"The pre-processing characteristics of food prices, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-flag\">here.</a>"},"price_type":{"$ref":"#/components/schemas/PriceType","description":"The point in the supply chain at which the price is determined, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-type\">here.</a>"},"price":{"type":"number","minimum":0,"title":"Price"},"lat":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"title":"Lat","description":"The market's latitude"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon","description":"The market's longitude"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","market_code","market_name","commodity_code","commodity_name","commodity_category","currency_code","unit","price_flag","price_type","price","lat","lon","reference_period_start","reference_period_end"],"title":"FoodPriceResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get poverty rate data

> Poverty rate data from the Oxford Department of International Development. See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/population\\\_and\\\_socio-economy/#poverty-rate">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/population\\_and\\_socio-economy/#poverty-rate">HDX) HAPI documentation\</a>, and the \<a href="[https://ophi.org.uk/global-mpi">Oxford](https://ophi.org.uk/global-mpi">Oxford) Department of International Development\</a> website.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/food-security-nutrition-poverty/poverty-rate":{"get":{"tags":["Food Security, Nutrition & Poverty"],"summary":"Get poverty rate data","description":"Poverty rate data from the Oxford Department of International Development. See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/population_and_socio-economy/#poverty-rate\">HDX HAPI documentation</a>, and the <a href=\"https://ophi.org.uk/global-mpi\">Oxford Department of International Development</a> website.","operationId":"get_poverty_rate_api_v2_food_security_nutrition_poverty_poverty_rate_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"mpi_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Multidimensional Poverty Index (MPI), lower bound.","title":"Mpi Min"},"description":"Multidimensional Poverty Index (MPI), lower bound."},{"name":"mpi_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Multidimensional Poverty Index (MPI), upper bound.","title":"Mpi Max"},"description":"Multidimensional Poverty Index (MPI), upper bound."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_PovertyRateResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_PovertyRateResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PovertyRateResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[PovertyRateResponse]"},"PovertyRateResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"mpi":{"type":"number","title":"Mpi","description":"The multidimensional poverty index, derived as a product of the `headcount_ratio` and `intensity_of_deprivation`. Note that this metric is presented as a fraction, while the others are percentages."},"headcount_ratio":{"type":"number","title":"Headcount Ratio","description":"The percentage of people deprived in 33% or more indicators"},"intensity_of_deprivation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Intensity Of Deprivation","description":"The average proportion of indicators in which people are deprived, given as a percentage."},"vulnerable_to_poverty":{"type":"number","title":"Vulnerable To Poverty","description":"The percentage of people deprived in 20-33% of indicators"},"in_severe_poverty":{"type":"number","title":"In Severe Poverty","description":"The percentage of people deprived in 50% or more indicators"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin_level","resource_hdx_id","mpi","headcount_ratio","intensity_of_deprivation","vulnerable_to_poverty","in_severe_poverty","reference_period_start","reference_period_end"],"title":"PovertyRateResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Geography & Infrastructure

## Get baseline population data

> Baseline population data sourced and maintained by UNFPA (UN Population Fund). See the more detailed technical \<a href="[https://hdx-hapi.readthedocs.io/en/latest/data\\\_usage\\\_guides/population\\\_and\\\_socio-economy/#baseline-population">HDX](https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/population\\_and\\_socio-economy/#baseline-population">HDX) HAPI documentation\</a>, and the \<a href="[https://data.humdata.org/organization/unfpa">UNFPA](https://data.humdata.org/organization/unfpa">UNFPA) on HDX\</a>.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/geography-infrastructure/baseline-population":{"get":{"tags":["Geography & Infrastructure"],"summary":"Get baseline population data","description":"Baseline population data sourced and maintained by UNFPA (UN Population Fund). See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/population_and_socio-economy/#baseline-population\">HDX HAPI documentation</a>, and the <a href=\"https://data.humdata.org/organization/unfpa\">UNFPA on HDX</a>.","operationId":"get_population_api_v2_geography_infrastructure_baseline_population_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Gender","maxLength":3},{"type":"null"}],"description":"Filter the response by the gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>","title":"Gender"},"description":"Filter the response by the gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},{"name":"age_range","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data.","title":"Age Range"},"description":"Filter the response by the age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},{"name":"population_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a lower bound for the population.","title":"Population Min"},"description":"Filter the response by a lower bound for the population."},{"name":"population_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a upper bound for the population.","title":"Population Max"},"description":"Filter the response by a upper bound for the population."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_PopulationResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_PopulationResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PopulationResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[PopulationResponse]"},"PopulationResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","title":"Population","description":"The number of people"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end"],"title":"PopulationResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Climate

## Get rainfall data

> Rainfall data . See the more detailed technical \<a href="<https://hdx-hapi.readthedocs.io/en/latest/data\\_usage\\_guides/>

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/climate/rainfall":{"get":{"tags":["Climate"],"summary":"Get rainfall data","description":"Rainfall data . See the more detailed technical <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/","operationId":"get_rainfall_api_v2_climate_rainfall_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"aggregation_period","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AggregationPeriod","maxLength":12},{"type":"null"}],"description":"Filter the response by the aggregation period, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#aggregation-period\">here.</a>","title":"Aggregation Period"},"description":"Filter the response by the aggregation period, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#aggregation-period\">here.</a>"},{"name":"version","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/Version","maxLength":16},{"type":"null"}],"description":"Version rainfall","title":"Version"},"description":"Version rainfall"},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_RainfallResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"AggregationPeriod":{"type":"string","enum":["dekad","1-month","3-month"],"title":"AggregationPeriod"},"Version":{"type":"string","enum":["final","forecast","preliminary"],"title":"Version"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_RainfallResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RainfallResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[RainfallResponse]"},"RainfallResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"aggregation_period":{"$ref":"#/components/schemas/AggregationPeriod","description":"The aggregation period, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#aggregation-period\">here.</a>"},"provider_admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Provider Admin1 Code","description":"The 1st subnational administrative divisions provided in the original data source."},"provider_admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Provider Admin2 Code","description":"The 2nd subnational administrative divisions provided in the original data source."},"rainfall":{"type":"number","minimum":0,"title":"Rainfall"},"rainfall_long_term_average":{"type":"number","minimum":0,"title":"Rainfall Long Term Average"},"rainfall_anomaly_pct":{"type":"number","minimum":0,"title":"Rainfall Anomaly Pct"},"number_pixels":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Number Pixels","description":"Rainfall number pixels"},"version":{"anyOf":[{"$ref":"#/components/schemas/Version"},{"type":"null"}],"description":"Version rainfall"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","aggregation_period","provider_admin1_code","provider_admin2_code","rainfall","rainfall_long_term_average","rainfall_anomaly_pct","number_pixels","version","reference_period_start","reference_period_end"],"title":"RainfallResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Metadata

## Get information about the sources of the data in HDX HAPI

> Get information about the \<a href="[https://data.humdata.org/dataset">HDX](https://data.humdata.org/dataset">HDX) Datasets\</a> that are used as data sources\
> for HDX HAPI. Datasets contain one or more resources, which are the sources of the data found in HDX HAPI.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/dataset":{"get":{"tags":["Metadata"],"summary":"Get information about the sources of the data in HDX HAPI","description":"Get information about the <a href=\"https://data.humdata.org/dataset\">HDX Datasets</a> that are used as data sources\nfor HDX HAPI. Datasets contain one or more resources, which are the sources of the data found in HDX HAPI.","operationId":"get_dataset_api_v2_metadata_dataset_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"dataset_hdx_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}],"description":"Filter the response by the dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX.","title":"Dataset Hdx Id"},"description":"Filter the response by the dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},{"name":"dataset_hdx_stub","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX.","title":"Dataset Hdx Stub"},"description":"Filter the response by the URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},{"name":"dataset_hdx_title","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"description":"Filter the response by the title of the dataset as it appears in the HDX interface. This name is not unique and can change.","title":"Dataset Hdx Title"},"description":"Filter the response by the title of the dataset as it appears in the HDX interface. This name is not unique and can change."},{"name":"hdx_provider_stub","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[hdx_provider_stub]` will load the provider's page on HDX.","title":"Hdx Provider Stub"},"description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[hdx_provider_stub]` will load the provider's page on HDX."},{"name":"hdx_provider_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the display name of the provider (organization) of the dataset on HDX.","title":"Hdx Provider Name"},"description":"Filter the response by the display name of the provider (organization) of the dataset on HDX."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_DatasetResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_DatasetResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DatasetResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[DatasetResponse]"},"DatasetResponse":{"properties":{"dataset_hdx_id":{"type":"string","maxLength":36,"title":"Dataset Hdx Id","description":"The dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},"dataset_hdx_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Stub","description":"The URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},"dataset_hdx_title":{"type":"string","maxLength":1024,"title":"Dataset Hdx Title","description":"The title of the dataset as it appears in the HDX interface. This name is not unique and can change."},"hdx_provider_stub":{"type":"string","maxLength":128,"title":"Hdx Provider Stub","description":"The URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[hdx_provider_stub]` will load the provider's page on HDX."},"hdx_provider_name":{"type":"string","maxLength":512,"title":"Hdx Provider Name","description":"The display name of the provider (organization) of the dataset on HDX."},"hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Link","readOnly":true},"hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Api Link","readOnly":true},"provider_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Link","readOnly":true},"provider_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Api Link","readOnly":true}},"type":"object","required":["dataset_hdx_id","dataset_hdx_stub","dataset_hdx_title","hdx_provider_stub","hdx_provider_name","hdx_link","hdx_api_link","provider_hdx_link","provider_hdx_api_link"],"title":"DatasetResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get information about the sources of the data in HDX HAPI

> Get information about the resources that are used as data sources for HDX HAPI. Datasets contain one or\
> more resources, which are the sources of the data found in HDX HAPI.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/resource":{"get":{"tags":["Metadata"],"summary":"Get information about the sources of the data in HDX HAPI","description":"Get information about the resources that are used as data sources for HDX HAPI. Datasets contain one or\nmore resources, which are the sources of the data found in HDX HAPI.","operationId":"get_resources_api_v2_metadata_resource_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"resource_hdx_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}],"description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX.","title":"Resource Hdx Id"},"description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the format of the resource on HDX. These are typically file formats (i.e. CSV, XLSX), but can also include APIs and web apps.","title":"Format"},"description":"Filter the response by the format of the resource on HDX. These are typically file formats (i.e. CSV, XLSX), but can also include APIs and web apps."},{"name":"update_date_min","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"null"}],"description":"Minimum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00","title":"Update Date Min"},"description":"Minimum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"},{"name":"update_date_max","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"null"}],"description":"Maximum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00","title":"Update Date Max"},"description":"Maximum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"},{"name":"is_hxl","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by whether or not the resource contains <a href=\"https://hxlstandard.org/\">HXL tags</a>.","title":"Is Hxl"},"description":"Filter the response by whether or not the resource contains <a href=\"https://hxlstandard.org/\">HXL tags</a>."},{"name":"dataset_hdx_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":36},{"type":"null"}],"description":"Filter the response by the dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX. See the <a href=\"/docs#/Metadata/get_dataset_api_v1_metadata_dataset_get\" target=\"_blank\">dataset endpoint</a> for details. ","title":"Dataset Hdx Id"},"description":"Filter the response by the dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX. See the <a href=\"/docs#/Metadata/get_dataset_api_v1_metadata_dataset_get\" target=\"_blank\">dataset endpoint</a> for details. "},{"name":"dataset_hdx_stub","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX. See the <a href=\"/docs#/Metadata/get_dataset_api_v1_metadata_dataset_get\" target=\"_blank\">dataset endpoint</a> for details.","title":"Dataset Hdx Stub"},"description":"Filter the response by the URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX. See the <a href=\"/docs#/Metadata/get_dataset_api_v1_metadata_dataset_get\" target=\"_blank\">dataset endpoint</a> for details."},{"name":"dataset_hdx_title","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"description":"Filter the response by the title of the dataset as it appears in the HDX interface. This name is not unique and can change. See the <a href=\"/docs#/Metadata/get_dataset_api_v1_metadata_dataset_get\" target=\"_blank\">dataset endpoint</a> for details.","title":"Dataset Hdx Title"},"description":"Filter the response by the title of the dataset as it appears in the HDX interface. This name is not unique and can change. See the <a href=\"/docs#/Metadata/get_dataset_api_v1_metadata_dataset_get\" target=\"_blank\">dataset endpoint</a> for details."},{"name":"dataset_hdx_provider_stub","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[dataset_hdx_provider_stub]` will load the provider's page on HDX.","title":"Dataset Hdx Provider Stub"},"description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[dataset_hdx_provider_stub]` will load the provider's page on HDX."},{"name":"dataset_hdx_provider_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the display name of the provider (organization) of the dataset on HDX.","title":"Dataset Hdx Provider Name"},"description":"Filter the response by the display name of the provider (organization) of the dataset on HDX."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_ResourceResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_ResourceResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ResourceResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[ResourceResponse]"},"ResourceResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"dataset_hdx_id":{"type":"string","maxLength":36,"title":"Dataset Hdx Id","description":"The dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},"name":{"type":"string","maxLength":256,"title":"Name","description":"The resource name on HDX. In combination with the dataset UUIDsfrom the `dataset_hdx_id` and `resource_hdx_id` fields respectively, it can be used to construct a URL to download the resource: `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]/download/[name]`, which can be found in the `download_url` field."},"format":{"type":"string","maxLength":32,"title":"Format","description":"The format of the resource on HDX. These are typically file formats (i.e. CSV, XLSX), but can also include APIs and web apps."},"update_date":{"type":"string","format":"date-time","title":"Update Date","description":"The date the resource was last updated"},"is_hxl":{"type":"boolean","title":"Is Hxl","description":"whether or not the resource contains <a href=\"https://hxlstandard.org/\">HXL tags</a>."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"A URL to directly download the resource file from HDX, in the format specified in the `format` field."},"hapi_updated_date":{"type":"string","format":"date-time","title":"Hapi Updated Date","description":"The date that the resource was ingested into HDX HAPI"},"dataset_hdx_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Stub","description":"The URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},"dataset_hdx_title":{"type":"string","maxLength":1024,"title":"Dataset Hdx Title","description":"The title of the dataset as it appears in the HDX interface. This name is not unique and can change."},"dataset_hdx_provider_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Provider Stub","description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[dataset_hdx_provider_stub]` will load the provider's page on HDX."},"dataset_hdx_provider_name":{"type":"string","maxLength":512,"title":"Dataset Hdx Provider Name","description":"Filter the response by the display name of the provider (organization) of the dataset on HDX."},"hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Link","readOnly":true},"hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Api Link","readOnly":true},"dataset_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Dataset Hdx Link","readOnly":true},"dataset_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Dataset Hdx Api Link","readOnly":true},"provider_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Link","readOnly":true},"provider_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Api Link","readOnly":true}},"type":"object","required":["resource_hdx_id","dataset_hdx_id","name","format","update_date","is_hxl","download_url","hapi_updated_date","dataset_hdx_stub","dataset_hdx_title","dataset_hdx_provider_stub","dataset_hdx_provider_name","hdx_link","hdx_api_link","dataset_hdx_link","dataset_hdx_api_link","provider_hdx_link","provider_hdx_api_link"],"title":"ResourceResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get the list of locations (typically countries) included in HDX HAPI

> Not all data are available for all locations. Learn more about the scope of data coverage in HDX HAPI in the \<a href="[https://hdx-hapi.readthedocs.io/en/latest/">Overview](https://hdx-hapi.readthedocs.io/en/latest/">Overview) and Getting Started\</a> documentation.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/location":{"get":{"tags":["Metadata"],"summary":"Get the list of locations (typically countries) included in HDX HAPI","description":"Not all data are available for all locations. Learn more about the scope of data coverage in HDX HAPI in the <a href=\"https://hdx-hapi.readthedocs.io/en/latest/\">Overview and Getting Started</a> documentation.","operationId":"get_location_api_v2_metadata_location_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a location (typically a country) reference number.","title":"Id"},"description":"Filter the response by a location (typically a country) reference number."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes.","title":"Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>.","title":"Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_LocationResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_LocationResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/LocationResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[LocationResponse]"},"LocationResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"A location (typically a country), using the unique identifier (id) from the location table associated with each entry."},"code":{"type":"string","maxLength":128,"title":"Code","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"has_hrp":{"type":"boolean","title":"Has Hrp","description":"The has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},"in_gho":{"type":"boolean","title":"In Gho","description":"The in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["id","code","name","has_hrp","in_gho","from_cods","reference_period_start","reference_period_end"],"title":"LocationResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get the list of first-level subnational administrative divisions available in HDX HAPI

> Not all data are available for all locations. Learn more about the scope of data coverage in HDX HAPI in the \<a href="[https://hdx-hapi.readthedocs.io/en/latest/">Overview](https://hdx-hapi.readthedocs.io/en/latest/">Overview) and Getting Started\</a> documentation.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/admin1":{"get":{"tags":["Metadata"],"summary":"Get the list of first-level subnational administrative divisions available in HDX HAPI","description":"Not all data are available for all locations. Learn more about the scope of data coverage in HDX HAPI in the <a href=\"https://hdx-hapi.readthedocs.io/en/latest/\">Overview and Getting Started</a> documentation.","operationId":"get_admin1_api_v2_metadata_admin1_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a location (typically a country), using the unique identifier (id) from the location table associated with each entry.","title":"Id"},"description":"Filter the response by a location (typically a country), using the unique identifier (id) from the location table associated with each entry."},{"name":"location_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a location (typically a country) reference number.","title":"Location Ref"},"description":"Filter the response by a location (typically a country) reference number."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>.","title":"Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source.","title":"Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_Admin1Response_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_Admin1Response_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Admin1Response"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[Admin1Response]"},"Admin1Response":{"properties":{"id":{"type":"integer","title":"Id","description":"1st subnational administrative division, using the unique identifier (id) from the admin1 table associated with each entry."},"location_ref":{"type":"integer","title":"Location Ref","description":"A location (typically a country) reference number."},"code":{"type":"string","maxLength":128,"title":"Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["id","location_ref","code","name","from_cods","reference_period_start","reference_period_end","location_code","location_name"],"title":"Admin1Response"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get the list of second-level administrative divisions available in HDX HAPI

> Not all data are available for all locations. Learn more about the scope of data coverage in HDX HAPI in the \<a href="[https://hdx-hapi.readthedocs.io/en/latest/">Overview](https://hdx-hapi.readthedocs.io/en/latest/">Overview) and Getting Started\</a> documentation.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/admin2":{"get":{"tags":["Metadata"],"summary":"Get the list of second-level administrative divisions available in HDX HAPI","description":"Not all data are available for all locations. Learn more about the scope of data coverage in HDX HAPI in the <a href=\"https://hdx-hapi.readthedocs.io/en/latest/\">Overview and Getting Started</a> documentation.","operationId":"get_admin2_api_v2_metadata_admin2_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a location (typically a country), using the unique identifier (id) from the location table associated with each entry.","title":"Id"},"description":"Filter the response by a location (typically a country), using the unique identifier (id) from the location table associated with each entry."},{"name":"admin1_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a location (typically a country) reference number.","title":"Admin1 Ref"},"description":"Filter the response by a location (typically a country) reference number."},{"name":"location_ref","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Filter the response by a location (typically a country) reference number.","title":"Location Ref"},"description":"Filter the response by a location (typically a country) reference number."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>.","title":"Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source.","title":"Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00","title":"Start Date"},"description":"Filter entries to include rows where the reference period overlaps with or extends beyond this date, e.g. 2020, 2020-01, 2020-01-01 or 2020-01-01T00:00:00"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59","title":"End Date"},"description":"Filter entries to include rows where the reference period overlaps with or begins prior to this date, e.g. 2020, 2020-01, 2020-01-01, 2020-01-01 or 2020-01-01T23:59:59"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_Admin2Response_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_Admin2Response_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Admin2Response"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[Admin2Response]"},"Admin2Response":{"properties":{"id":{"type":"integer","title":"Id","description":"2nd subnational administrative division, using the unique identifier (id) from the admin2 table associated with each entry."},"admin1_ref":{"type":"integer","title":"Admin1 Ref","description":"The 2nd subnational administrative division reference number."},"code":{"type":"string","maxLength":128,"title":"Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"admin1_code":{"type":"string","maxLength":128,"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"type":"string","maxLength":512,"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"location_ref":{"type":"integer","title":"Location Ref","description":"A location (typically a country) reference number."}},"type":"object","required":["id","admin1_ref","code","name","from_cods","reference_period_start","reference_period_end","admin1_code","admin1_name","location_code","location_name","location_ref"],"title":"Admin2Response"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get information about how currencies are classified

> Provide currency information to use in conjunction with the food-prices endpoint

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/currency":{"get":{"tags":["Metadata"],"summary":"Get information about how currencies are classified","description":"Provide currency information to use in conjunction with the food-prices endpoint","operationId":"get_currency_api_v2_metadata_currency_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the currency code.","title":"Code"},"description":"Filter the response by the currency code."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_CurrencyResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_CurrencyResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CurrencyResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[CurrencyResponse]"},"CurrencyResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"ISO-4217 currency code"},"name":{"type":"string","maxLength":512,"title":"Name","description":"Currency name"}},"type":"object","required":["code","name"],"title":"CurrencyResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## GET /api/v2/metadata/org

> Get the list of organizations represented in the data available in HDX HAPI

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/org":{"get":{"tags":["Metadata"],"summary":"Get the list of organizations represented in the data available in HDX HAPI","operationId":"get_org_api_v2_metadata_org_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"acronym","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the standard acronym used to represent the organization. When data is brought into the HDX HAPI database, an attempt is made to standardize the acronyms.","title":"Acronym"},"description":"Filter the response by the standard acronym used to represent the organization. When data is brought into the HDX HAPI database, an attempt is made to standardize the acronyms."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the standard name used to represent the organization. When data is brought into the HDX HAPI database, an attempt is made to standardize the acronyms.","title":"Name"},"description":"Filter the response by the standard name used to represent the organization. When data is brought into the HDX HAPI database, an attempt is made to standardize the acronyms."},{"name":"org_type_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the organization type code.","title":"Org Type Code"},"description":"Filter the response by the organization type code."},{"name":"org_type_description","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the organization type description. See the <a href=\"/docs#/Metadata/get_org_type_api_v1_metadata_org_type_get\" target=\"_blank\">org type endpoint</a> for details.","title":"Org Type Description"},"description":"Filter the response by the organization type description. See the <a href=\"/docs#/Metadata/get_org_type_api_v1_metadata_org_type_get\" target=\"_blank\">org type endpoint</a> for details."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_OrgResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_OrgResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrgResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[OrgResponse]"},"OrgResponse":{"properties":{"acronym":{"type":"string","maxLength":32,"title":"Acronym","description":"The organization acronym"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The organization name"},"org_type_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Code","description":"The code referring to the organization type"},"org_type_description":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Description","description":"A description of the organization type"}},"type":"object","required":["acronym","name","org_type_code","org_type_description"],"title":"OrgResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get information about how organizations are classified in HDX HAPI

> There is no agreed standard for the classification of organizations. The codes and descriptions used in HDX HAPI\
> are based on \<a href="[https://data.humdata.org/dataset/organization-types-beta">this](https://data.humdata.org/dataset/organization-types-beta">this) dataset\</a>.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/org-type":{"get":{"tags":["Metadata"],"summary":"Get information about how organizations are classified in HDX HAPI","description":"There is no agreed standard for the classification of organizations. The codes and descriptions used in HDX HAPI\nare based on <a href=\"https://data.humdata.org/dataset/organization-types-beta\">this dataset</a>.","operationId":"get_org_type_api_v2_metadata_org_type_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the organization type code.","title":"Code"},"description":"Filter the response by the organization type code."},{"name":"description","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the organization type description.","title":"Description"},"description":"Filter the response by the organization type description."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_OrgTypeResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_OrgTypeResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrgTypeResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[OrgTypeResponse]"},"OrgTypeResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":" The code referring to the organization type, derived either from the [OCHA Digital Services organization types list](https://data.humdata.org/dataset/organization-types-beta), or created for HDX HAPI"},"description":{"type":"string","maxLength":512,"title":"Description","description":"A description of the organization type"}},"type":"object","required":["code","description"],"title":"OrgTypeResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get information about how humanitarian response activities are classified

> There are a variety of standards for the naming of humanitarian sectors. The codes and descriptions used\
> in HDX HAPI are based on\
> \<a href="[https://data.humdata.org/organization/54255d0b-c6b1-4517-9722-17321f6634ab">this](https://data.humdata.org/organization/54255d0b-c6b1-4517-9722-17321f6634ab">this) dataset\</a>.

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/sector":{"get":{"tags":["Metadata"],"summary":"Get information about how humanitarian response activities are classified","description":"There are a variety of standards for the naming of humanitarian sectors. The codes and descriptions used\nin HDX HAPI are based on\n<a href=\"https://data.humdata.org/organization/54255d0b-c6b1-4517-9722-17321f6634ab\">this dataset</a>.","operationId":"get_sector_api_v2_metadata_sector_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the sector code.","title":"Code"},"description":"Filter the response by the sector code."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the sector name.","title":"Name"},"description":"Filter the response by the sector name."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_SectorResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_SectorResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SectorResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[SectorResponse]"},"SectorResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the sector"}},"type":"object","required":["code","name"],"title":"SectorResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get the list of WFP commodities

> Provide commodity information to use in conjunction with the food-prices endpoint

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/wfp-commodity":{"get":{"tags":["Metadata"],"summary":"Get the list of WFP commodities","description":"Provide commodity information to use in conjunction with the food-prices endpoint","operationId":"get_wfp_commodities_api_v2_metadata_wfp_commodity_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the unique code identifying the commodity.","title":"Code"},"description":"Filter the response by the unique code identifying the commodity."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/CommodityCategory"},{"type":"null"}],"description":"Filter the response by the food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>","title":"Category"},"description":"Filter the response by the food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the name of the commodity.","title":"Name"},"description":"Filter the response by the name of the commodity."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_WfpCommodityResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_WfpCommodityResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WfpCommodityResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[WfpCommodityResponse]"},"WfpCommodityResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"The unique code identifying the commodity"},"category":{"$ref":"#/components/schemas/CommodityCategory","description":"The food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the commodity"}},"type":"object","required":["code","category","name"],"title":"WfpCommodityResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get the list of WFP markets.

> Provide physical market location information to use in conjunction with the food-prices endpoint

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/wfp-market":{"get":{"tags":["Metadata"],"summary":"Get the list of WFP markets.","description":"Provide physical market location information to use in conjunction with the food-prices endpoint","operationId":"get_wfp_market_api_v2_metadata_wfp_market_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Filter the response by the unique code identifying the market.","title":"Code"},"description":"Filter the response by the unique code identifying the market."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the name of the market.","title":"Name"},"description":"Filter the response by the name of the market."},{"name":"has_hrp","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan.","title":"Has Hrp"},"description":"Filter the response by the has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},{"name":"in_gho","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>.","title":"In Gho"},"description":"Filter the response by the in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_WfpMarketResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"HapiGenericResponse_WfpMarketResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WfpMarketResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[WfpMarketResponse]"},"WfpMarketResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"code":{"type":"string","maxLength":32,"title":"Code","description":"The unique code identifying the market"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the market"},"lat":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"title":"Lat","description":"The market's latitude"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon","description":"The market's longitude"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","code","name","lat","lon"],"title":"WfpMarketResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## Get information about the availability of data for different geographic admin levels

> Provide currency information to use in conjunction with the food-prices endpoint

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/metadata/data-availability":{"get":{"tags":["Metadata"],"summary":"Get information about the availability of data for different geographic admin levels","description":"Provide currency information to use in conjunction with the food-prices endpoint","operationId":"get_data_availability_api_v2_metadata_data_availability_get","parameters":[{"name":"app_identifier","in":"query","required":true,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint.","title":"App Identifier"},"description":"base64 encoded application name and email, as in `base64(\"app_name:email\")`. This value can also be passed in the `X-HDX-HAPI-APP-IDENTIFIER` header. See the *encoded_app_identifier* endpoint."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a data category","title":"Category"},"description":"Filter the response by a data category"},{"name":"subcategory","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a data subcategory","title":"Subcategory"},"description":"Filter the response by a data subcategory"},{"name":"hapi_updated_date_min","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"null"}],"description":"Minimum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00","title":"Hapi Updated Date Min"},"description":"Minimum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"},{"name":"hapi_updated_date_max","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"type":"null"}],"description":"Maximum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00","title":"Hapi Updated Date Max"},"description":"Maximum date that datasets was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"},{"name":"output_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/OutputFormat","default":"json"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":0,"description":"Maximum number of records to return. The system will not return more than 10,000 records.","default":10000,"title":"Limit"},"description":"Maximum number of records to return. The system will not return more than 10,000 records."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate.","default":0,"title":"Offset"},"description":"Number of records to skip in the response. Use in conjunction with the limit parameter to paginate."},{"name":"location_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Code"},"description":"Filter the response by a location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"location_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details.","title":"Location Name"},"description":"Filter the response by a location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>. See the <a href=\"/docs#/Metadata/get_locations_api_v1_metadata_location_get\" target=\"_blank\">location endpoint</a> for details."},{"name":"admin1_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Code"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin1_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details.","title":"Admin1 Name"},"description":"Filter the response by the 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin1_api_v1_metadata_admin1_get\" target=\"_blank\">admin1 endpoint</a> for details."},{"name":"admin2_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Code"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin2_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details.","title":"Admin2 Name"},"description":"Filter the response by the 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source. See the <a href=\"/docs#/Metadata/get_admin2_api_v1_metadata_admin2_get\" target=\"_blank\">admin2 endpoint</a> for details."},{"name":"admin_level","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/AdminLevel"},{"type":"null"}],"description":"Filter the response by admin level.","title":"Admin Level"},"description":"Filter the response by admin level."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HapiGenericResponse_AvailabilityResponse_"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}},"description":"Bad Request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationResponse"}}},"description":"Internal Server Error"}}}}},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"},"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"},"HapiGenericResponse_AvailabilityResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AvailabilityResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[AvailabilityResponse]"},"AvailabilityResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"category":{"type":"string","maxLength":32,"title":"Category","description":"HAPI category"},"subcategory":{"type":"string","maxLength":512,"title":"Subcategory","description":"HAPI subcategory"},"hapi_updated_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Hapi Updated Date","description":"Date that dataset was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","category","subcategory","hapi_updated_date"],"title":"AvailabilityResponse"},"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```


# Util

## GET /api/v2/util/version

> Display the API and SQL Alchemy versions

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"servers":[{"url":"https://hapi.humdata.org","description":"Production"}],"paths":{"/api/v2/util/version":{"get":{"tags":["Util"],"summary":"Display the API and SQL Alchemy versions","operationId":"get_version_api_v2_util_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}}}}},"components":{"schemas":{"VersionResponse":{"properties":{"api_version":{"type":"string","maxLength":16,"title":"Api Version"},"hapi_sqlalchemy_schema_version":{"type":"string","maxLength":16,"title":"Hapi Sqlalchemy Schema Version"}},"type":"object","required":["api_version","hapi_sqlalchemy_schema_version"],"title":"VersionResponse"}}}}
```


# Models

## The Admin1Response object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"Admin1Response":{"properties":{"id":{"type":"integer","title":"Id","description":"1st subnational administrative division, using the unique identifier (id) from the admin1 table associated with each entry."},"location_ref":{"type":"integer","title":"Location Ref","description":"A location (typically a country) reference number."},"code":{"type":"string","maxLength":128,"title":"Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["id","location_ref","code","name","from_cods","reference_period_start","reference_period_end","location_code","location_name"],"title":"Admin1Response"}}}}
```

## The Admin2Response object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"Admin2Response":{"properties":{"id":{"type":"integer","title":"Id","description":"2nd subnational administrative division, using the unique identifier (id) from the admin2 table associated with each entry."},"admin1_ref":{"type":"integer","title":"Admin1 Ref","description":"The 2nd subnational administrative division reference number."},"code":{"type":"string","maxLength":128,"title":"Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"admin1_code":{"type":"string","maxLength":128,"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"type":"string","maxLength":512,"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"location_ref":{"type":"integer","title":"Location Ref","description":"A location (typically a country) reference number."}},"type":"object","required":["id","admin1_ref","code","name","from_cods","reference_period_start","reference_period_end","admin1_code","admin1_name","location_code","location_name","location_ref"],"title":"Admin2Response"}}}}
```

## The AdminLevel object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"AdminLevel":{"type":"string","enum":["0","1","2"],"title":"AdminLevel"}}}}
```

## The AggregationPeriod object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"AggregationPeriod":{"type":"string","enum":["dekad","1-month","3-month"],"title":"AggregationPeriod"}}}}
```

## The AvailabilityResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"AvailabilityResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"category":{"type":"string","maxLength":32,"title":"Category","description":"HAPI category"},"subcategory":{"type":"string","maxLength":512,"title":"Subcategory","description":"HAPI subcategory"},"hapi_updated_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Hapi Updated Date","description":"Date that dataset was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","category","subcategory","hapi_updated_date"],"title":"AvailabilityResponse"}}}}
```

## The BadRequestResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"BadRequestResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"BadRequestResponse"}}}}
```

## The CommodityCategory object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"}}}}
```

## The ConflictEventResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"ConflictEventResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"event_type":{"$ref":"#/components/schemas/EventType","description":"Filter the response by the ACLED event-type categories (non-mutually exclusive), available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#event-type\">here.</a>"},"events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Events","description":"The number of events with the given `event_type`"},"fatalities":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fatalities","description":"The number of fatalities due to the given `event_type`"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","event_type","events","fatalities","reference_period_start","reference_period_end"],"title":"ConflictEventResponse"},"EventType":{"type":"string","enum":["civilian_targeting","demonstration","political_violence"],"title":"EventType"}}}}
```

## The CurrencyResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"CurrencyResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"ISO-4217 currency code"},"name":{"type":"string","maxLength":512,"title":"Name","description":"Currency name"}},"type":"object","required":["code","name"],"title":"CurrencyResponse"}}}}
```

## The DTMAssessmentType object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"DTMAssessmentType":{"type":"string","enum":["BA","ETT","SA"],"title":"DTMAssessmentType"}}}}
```

## The DatasetResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"DatasetResponse":{"properties":{"dataset_hdx_id":{"type":"string","maxLength":36,"title":"Dataset Hdx Id","description":"The dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},"dataset_hdx_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Stub","description":"The URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},"dataset_hdx_title":{"type":"string","maxLength":1024,"title":"Dataset Hdx Title","description":"The title of the dataset as it appears in the HDX interface. This name is not unique and can change."},"hdx_provider_stub":{"type":"string","maxLength":128,"title":"Hdx Provider Stub","description":"The URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[hdx_provider_stub]` will load the provider's page on HDX."},"hdx_provider_name":{"type":"string","maxLength":512,"title":"Hdx Provider Name","description":"The display name of the provider (organization) of the dataset on HDX."},"hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Link","readOnly":true},"hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Api Link","readOnly":true},"provider_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Link","readOnly":true},"provider_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Api Link","readOnly":true}},"type":"object","required":["dataset_hdx_id","dataset_hdx_stub","dataset_hdx_title","hdx_provider_stub","hdx_provider_name","hdx_link","hdx_api_link","provider_hdx_link","provider_hdx_api_link"],"title":"DatasetResponse"}}}}
```

## The EventType object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"EventType":{"type":"string","enum":["civilian_targeting","demonstration","political_violence"],"title":"EventType"}}}}
```

## The FoodPriceResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"FoodPriceResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Unique resource UUID on HDX"},"market_code":{"type":"string","maxLength":32,"title":"Market Code","description":"The unique code identifying the market"},"market_name":{"type":"string","maxLength":512,"title":"Market Name","description":"The name of the market"},"commodity_code":{"type":"string","maxLength":32,"title":"Commodity Code","description":"The unique code identifying the commodity"},"commodity_name":{"type":"string","maxLength":512,"title":"Commodity Name","description":"The name of the commodity"},"commodity_category":{"$ref":"#/components/schemas/CommodityCategory","description":"The food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},"currency_code":{"type":"string","maxLength":32,"title":"Currency Code","description":"ISO-4217 currency code"},"unit":{"type":"string","maxLength":32,"title":"Unit","description":"The unit of the commodity, such as weight or number"},"price_flag":{"$ref":"#/components/schemas/PriceFlag","description":"The pre-processing characteristics of food prices, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-flag\">here.</a>"},"price_type":{"$ref":"#/components/schemas/PriceType","description":"The point in the supply chain at which the price is determined, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-type\">here.</a>"},"price":{"type":"number","minimum":0,"title":"Price"},"lat":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"title":"Lat","description":"The market's latitude"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon","description":"The market's longitude"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","market_code","market_name","commodity_code","commodity_name","commodity_category","currency_code","unit","price_flag","price_type","price","lat","lon","reference_period_start","reference_period_end"],"title":"FoodPriceResponse"},"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"},"PriceFlag":{"type":"string","enum":["actual","aggregate","actual,aggregate"],"title":"PriceFlag"},"PriceType":{"type":"string","enum":["Farm Gate","Producer","Retail","Wholesale"],"title":"PriceType"}}}}
```

## The FoodSecurityResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"FoodSecurityResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"ipc_phase":{"type":"string","maxLength":32,"title":"Ipc Phase","description":"The IPC phase, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-code\">here.</a>"},"ipc_type":{"type":"string","maxLength":32,"title":"Ipc Type","description":"The IPC type, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-type\">here.</a>"},"population_in_phase":{"type":"integer","title":"Population In Phase","description":"The number of people in the IPC phase"},"population_fraction_in_phase":{"type":"number","title":"Population Fraction In Phase","description":"The fraction of people in the IPC phase"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","ipc_phase","ipc_type","population_in_phase","population_fraction_in_phase","reference_period_start","reference_period_end"],"title":"FoodSecurityResponse"}}}}
```

## The FundingResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"FundingResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"appeal_code":{"type":"string","maxLength":64,"title":"Appeal Code","description":"A unique code given by FTS to each appeal"},"appeal_name":{"type":"string","maxLength":256,"title":"Appeal Name","description":"Name of the appeal"},"appeal_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Appeal Type","description":"The type of the appeal, such as flash or HRP"},"requirements_usd":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Requirements Usd","description":"The funding requirements in US dollars"},"funding_usd":{"type":"number","minimum":0,"title":"Funding Usd","description":"The actual funding in US dollars"},"funding_pct":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Funding Pct","description":"The percentage of required funding received by the appeal"},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["resource_hdx_id","appeal_code","appeal_name","appeal_type","requirements_usd","funding_usd","funding_pct","location_code","location_name","reference_period_start","reference_period_end"],"title":"FundingResponse"}}}}
```

## The Gender object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The HTTPValidationError object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## The HapiGenericResponse\_Admin1Response\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_Admin1Response_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Admin1Response"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[Admin1Response]"},"Admin1Response":{"properties":{"id":{"type":"integer","title":"Id","description":"1st subnational administrative division, using the unique identifier (id) from the admin1 table associated with each entry."},"location_ref":{"type":"integer","title":"Location Ref","description":"A location (typically a country) reference number."},"code":{"type":"string","maxLength":128,"title":"Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["id","location_ref","code","name","from_cods","reference_period_start","reference_period_end","location_code","location_name"],"title":"Admin1Response"}}}}
```

## The HapiGenericResponse\_Admin2Response\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_Admin2Response_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Admin2Response"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[Admin2Response]"},"Admin2Response":{"properties":{"id":{"type":"integer","title":"Id","description":"2nd subnational administrative division, using the unique identifier (id) from the admin2 table associated with each entry."},"admin1_ref":{"type":"integer","title":"Admin1 Ref","description":"The 2nd subnational administrative division reference number."},"code":{"type":"string","maxLength":128,"title":"Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"admin1_code":{"type":"string","maxLength":128,"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"type":"string","maxLength":512,"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"location_ref":{"type":"integer","title":"Location Ref","description":"A location (typically a country) reference number."}},"type":"object","required":["id","admin1_ref","code","name","from_cods","reference_period_start","reference_period_end","admin1_code","admin1_name","location_code","location_name","location_ref"],"title":"Admin2Response"}}}}
```

## The HapiGenericResponse\_AvailabilityResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_AvailabilityResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AvailabilityResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[AvailabilityResponse]"},"AvailabilityResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"category":{"type":"string","maxLength":32,"title":"Category","description":"HAPI category"},"subcategory":{"type":"string","maxLength":512,"title":"Subcategory","description":"HAPI subcategory"},"hapi_updated_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Hapi Updated Date","description":"Date that dataset was last updated, e.g. 2020-01-01 or 2020-01-01T00:00:00"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","category","subcategory","hapi_updated_date"],"title":"AvailabilityResponse"}}}}
```

## The HapiGenericResponse\_ConflictEventResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_ConflictEventResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ConflictEventResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[ConflictEventResponse]"},"ConflictEventResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"event_type":{"$ref":"#/components/schemas/EventType","description":"Filter the response by the ACLED event-type categories (non-mutually exclusive), available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#event-type\">here.</a>"},"events":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Events","description":"The number of events with the given `event_type`"},"fatalities":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fatalities","description":"The number of fatalities due to the given `event_type`"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","event_type","events","fatalities","reference_period_start","reference_period_end"],"title":"ConflictEventResponse"},"EventType":{"type":"string","enum":["civilian_targeting","demonstration","political_violence"],"title":"EventType"}}}}
```

## The HapiGenericResponse\_CurrencyResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_CurrencyResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CurrencyResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[CurrencyResponse]"},"CurrencyResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"ISO-4217 currency code"},"name":{"type":"string","maxLength":512,"title":"Name","description":"Currency name"}},"type":"object","required":["code","name"],"title":"CurrencyResponse"}}}}
```

## The HapiGenericResponse\_DatasetResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_DatasetResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DatasetResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[DatasetResponse]"},"DatasetResponse":{"properties":{"dataset_hdx_id":{"type":"string","maxLength":36,"title":"Dataset Hdx Id","description":"The dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},"dataset_hdx_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Stub","description":"The URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},"dataset_hdx_title":{"type":"string","maxLength":1024,"title":"Dataset Hdx Title","description":"The title of the dataset as it appears in the HDX interface. This name is not unique and can change."},"hdx_provider_stub":{"type":"string","maxLength":128,"title":"Hdx Provider Stub","description":"The URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[hdx_provider_stub]` will load the provider's page on HDX."},"hdx_provider_name":{"type":"string","maxLength":512,"title":"Hdx Provider Name","description":"The display name of the provider (organization) of the dataset on HDX."},"hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Link","readOnly":true},"hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Api Link","readOnly":true},"provider_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Link","readOnly":true},"provider_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Api Link","readOnly":true}},"type":"object","required":["dataset_hdx_id","dataset_hdx_stub","dataset_hdx_title","hdx_provider_stub","hdx_provider_name","hdx_link","hdx_api_link","provider_hdx_link","provider_hdx_api_link"],"title":"DatasetResponse"}}}}
```

## The HapiGenericResponse\_FoodPriceResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_FoodPriceResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FoodPriceResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[FoodPriceResponse]"},"FoodPriceResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Unique resource UUID on HDX"},"market_code":{"type":"string","maxLength":32,"title":"Market Code","description":"The unique code identifying the market"},"market_name":{"type":"string","maxLength":512,"title":"Market Name","description":"The name of the market"},"commodity_code":{"type":"string","maxLength":32,"title":"Commodity Code","description":"The unique code identifying the commodity"},"commodity_name":{"type":"string","maxLength":512,"title":"Commodity Name","description":"The name of the commodity"},"commodity_category":{"$ref":"#/components/schemas/CommodityCategory","description":"The food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},"currency_code":{"type":"string","maxLength":32,"title":"Currency Code","description":"ISO-4217 currency code"},"unit":{"type":"string","maxLength":32,"title":"Unit","description":"The unit of the commodity, such as weight or number"},"price_flag":{"$ref":"#/components/schemas/PriceFlag","description":"The pre-processing characteristics of food prices, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-flag\">here.</a>"},"price_type":{"$ref":"#/components/schemas/PriceType","description":"The point in the supply chain at which the price is determined, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#price-type\">here.</a>"},"price":{"type":"number","minimum":0,"title":"Price"},"lat":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"title":"Lat","description":"The market's latitude"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon","description":"The market's longitude"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","market_code","market_name","commodity_code","commodity_name","commodity_category","currency_code","unit","price_flag","price_type","price","lat","lon","reference_period_start","reference_period_end"],"title":"FoodPriceResponse"},"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"},"PriceFlag":{"type":"string","enum":["actual","aggregate","actual,aggregate"],"title":"PriceFlag"},"PriceType":{"type":"string","enum":["Farm Gate","Producer","Retail","Wholesale"],"title":"PriceType"}}}}
```

## The HapiGenericResponse\_FoodSecurityResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_FoodSecurityResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FoodSecurityResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[FoodSecurityResponse]"},"FoodSecurityResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"ipc_phase":{"type":"string","maxLength":32,"title":"Ipc Phase","description":"The IPC phase, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-code\">here.</a>"},"ipc_type":{"type":"string","maxLength":32,"title":"Ipc Type","description":"The IPC type, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#ipc-type\">here.</a>"},"population_in_phase":{"type":"integer","title":"Population In Phase","description":"The number of people in the IPC phase"},"population_fraction_in_phase":{"type":"number","title":"Population Fraction In Phase","description":"The fraction of people in the IPC phase"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","ipc_phase","ipc_type","population_in_phase","population_fraction_in_phase","reference_period_start","reference_period_end"],"title":"FoodSecurityResponse"}}}}
```

## The HapiGenericResponse\_FundingResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_FundingResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FundingResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[FundingResponse]"},"FundingResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"Filter the response by the resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"appeal_code":{"type":"string","maxLength":64,"title":"Appeal Code","description":"A unique code given by FTS to each appeal"},"appeal_name":{"type":"string","maxLength":256,"title":"Appeal Name","description":"Name of the appeal"},"appeal_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Appeal Type","description":"The type of the appeal, such as flash or HRP"},"requirements_usd":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Requirements Usd","description":"The funding requirements in US dollars"},"funding_usd":{"type":"number","minimum":0,"title":"Funding Usd","description":"The actual funding in US dollars"},"funding_pct":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Funding Pct","description":"The percentage of required funding received by the appeal"},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["resource_hdx_id","appeal_code","appeal_name","appeal_type","requirements_usd","funding_usd","funding_pct","location_code","location_name","reference_period_start","reference_period_end"],"title":"FundingResponse"}}}}
```

## The HapiGenericResponse\_HumanitarianNeedsResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_HumanitarianNeedsResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/HumanitarianNeedsResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[HumanitarianNeedsResponse]"},"HumanitarianNeedsResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"sector_code":{"type":"string","maxLength":32,"title":"Sector Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"category":{"type":"string","maxLength":128,"title":"Category","description":"A category combining gender, age range, disability marker and population group information"},"population_status":{"$ref":"#/components/schemas/PopulationStatus","description":"The population status, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-status\">here.</a>"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"sector_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Sector Name","description":"The name of the sector"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","sector_code","category","population_status","population","reference_period_start","reference_period_end","sector_name"],"title":"HumanitarianNeedsResponse"},"PopulationStatus":{"type":"string","enum":["AFF","INN","TGT","REA","all"],"title":"PopulationStatus"}}}}
```

## The HapiGenericResponse\_IdpsResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_IdpsResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/IdpsResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[IdpsResponse]"},"IdpsResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"reporting_round":{"type":"integer","title":"Reporting Round","description":"Data collection round number"},"assessment_type":{"$ref":"#/components/schemas/DTMAssessmentType","description":"Either baseline assessment (BA),site assessment (SA) or event track (ETT)"},"operation":{"type":"string","title":"Operation","description":"Name of DTM Operation for which the data was collected"},"population":{"type":"integer","title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","reporting_round","assessment_type","operation","population","reference_period_start","reference_period_end"],"title":"IdpsResponse"},"DTMAssessmentType":{"type":"string","enum":["BA","ETT","SA"],"title":"DTMAssessmentType"}}}}
```

## The HapiGenericResponse\_LocationResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_LocationResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/LocationResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[LocationResponse]"},"LocationResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"A location (typically a country), using the unique identifier (id) from the location table associated with each entry."},"code":{"type":"string","maxLength":128,"title":"Code","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"has_hrp":{"type":"boolean","title":"Has Hrp","description":"The has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},"in_gho":{"type":"boolean","title":"In Gho","description":"The in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["id","code","name","has_hrp","in_gho","from_cods","reference_period_start","reference_period_end"],"title":"LocationResponse"}}}}
```

## The HapiGenericResponse\_NationalRiskResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_NationalRiskResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/NationalRiskResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[NationalRiskResponse]"},"NationalRiskResponse":{"properties":{"risk_class":{"$ref":"#/components/schemas/RiskClass","description":"The INFORM risk class, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#risk-class\">here.</a>"},"global_rank":{"type":"integer","maximum":250,"minimum":1,"title":"Global Rank","description":"The rank of the country based on `overall_risk`. Higher rank (smaller number) is associated with more risk."},"overall_risk":{"type":"number","maximum":10,"minimum":0,"title":"Overall Risk","description":"The INFORM composite risk index, based on a combination of 54 indicators into three dimensions of risk: hazard and exposure, vulnerability, and lack of coping capacity. Risk score is given out of 10."},"hazard_exposure_risk":{"type":"number","maximum":10,"minimum":0,"title":"Hazard Exposure Risk","description":"Risk due to events that may occur, and exposure to them. Risk score is given out of 10. "},"vulnerability_risk":{"type":"number","maximum":10,"minimum":0,"title":"Vulnerability Risk","description":"Risk due to hazard susceptibility. Risk score is given out of 10."},"coping_capacity_risk":{"type":"number","maximum":10,"minimum":0,"title":"Coping Capacity Risk","description":"Risk due to lack of coping capacity to alleviate hazard impact. Risk score is given out of 10."},"meta_missing_indicators_pct":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"title":"Meta Missing Indicators Pct","description":"The average of the total number of years older than the reference year per indicator, to account for any older data used as a proxy"},"meta_avg_recentness_years":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Meta Avg Recentness Years","description":"The average of the total number of years older than the reference year per indicator, to account for any older data used as a proxy)"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["risk_class","global_rank","overall_risk","hazard_exposure_risk","vulnerability_risk","coping_capacity_risk","meta_missing_indicators_pct","meta_avg_recentness_years","reference_period_start","reference_period_end","resource_hdx_id","location_code","location_name"],"title":"NationalRiskResponse"},"RiskClass":{"type":"string","enum":["1","2","3","4","5"],"title":"RiskClass"}}}}
```

## The HapiGenericResponse\_OperationalPresenceResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_OperationalPresenceResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OperationalPresenceResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[OperationalPresenceResponse]"},"OperationalPresenceResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"org_acronym":{"type":"string","maxLength":32,"title":"Org Acronym","description":"The organization acronym"},"org_name":{"type":"string","maxLength":512,"title":"Org Name","description":"The organization name"},"sector_code":{"type":"string","maxLength":32,"title":"Sector Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"sector_name":{"type":"string","maxLength":512,"title":"Sector Name","description":"The name of the sector"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"org_type_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Code","description":"The code referring to the organization type"},"org_type_description":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Org Type Description","description":"A description of the organization type"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","org_acronym","org_name","sector_code","sector_name","reference_period_start","reference_period_end","org_type_code","org_type_description"],"title":"OperationalPresenceResponse"}}}}
```

## The HapiGenericResponse\_OrgResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_OrgResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrgResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[OrgResponse]"},"OrgResponse":{"properties":{"acronym":{"type":"string","maxLength":32,"title":"Acronym","description":"The organization acronym"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The organization name"},"org_type_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Code","description":"The code referring to the organization type"},"org_type_description":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Description","description":"A description of the organization type"}},"type":"object","required":["acronym","name","org_type_code","org_type_description"],"title":"OrgResponse"}}}}
```

## The HapiGenericResponse\_OrgTypeResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_OrgTypeResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrgTypeResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[OrgTypeResponse]"},"OrgTypeResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":" The code referring to the organization type, derived either from the [OCHA Digital Services organization types list](https://data.humdata.org/dataset/organization-types-beta), or created for HDX HAPI"},"description":{"type":"string","maxLength":512,"title":"Description","description":"A description of the organization type"}},"type":"object","required":["code","description"],"title":"OrgTypeResponse"}}}}
```

## The HapiGenericResponse\_PopulationResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_PopulationResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PopulationResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[PopulationResponse]"},"PopulationResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","title":"Population","description":"The number of people"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end"],"title":"PopulationResponse"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The HapiGenericResponse\_PovertyRateResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_PovertyRateResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PovertyRateResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[PovertyRateResponse]"},"PovertyRateResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"mpi":{"type":"number","title":"Mpi","description":"The multidimensional poverty index, derived as a product of the `headcount_ratio` and `intensity_of_deprivation`. Note that this metric is presented as a fraction, while the others are percentages."},"headcount_ratio":{"type":"number","title":"Headcount Ratio","description":"The percentage of people deprived in 33% or more indicators"},"intensity_of_deprivation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Intensity Of Deprivation","description":"The average proportion of indicators in which people are deprived, given as a percentage."},"vulnerable_to_poverty":{"type":"number","title":"Vulnerable To Poverty","description":"The percentage of people deprived in 20-33% of indicators"},"in_severe_poverty":{"type":"number","title":"In Severe Poverty","description":"The percentage of people deprived in 50% or more indicators"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin_level","resource_hdx_id","mpi","headcount_ratio","intensity_of_deprivation","vulnerable_to_poverty","in_severe_poverty","reference_period_start","reference_period_end"],"title":"PovertyRateResponse"}}}}
```

## The HapiGenericResponse\_RainfallResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_RainfallResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RainfallResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[RainfallResponse]"},"RainfallResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"aggregation_period":{"$ref":"#/components/schemas/AggregationPeriod","description":"The aggregation period, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#aggregation-period\">here.</a>"},"provider_admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Provider Admin1 Code","description":"The 1st subnational administrative divisions provided in the original data source."},"provider_admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Provider Admin2 Code","description":"The 2nd subnational administrative divisions provided in the original data source."},"rainfall":{"type":"number","minimum":0,"title":"Rainfall"},"rainfall_long_term_average":{"type":"number","minimum":0,"title":"Rainfall Long Term Average"},"rainfall_anomaly_pct":{"type":"number","minimum":0,"title":"Rainfall Anomaly Pct"},"number_pixels":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Number Pixels","description":"Rainfall number pixels"},"version":{"anyOf":[{"$ref":"#/components/schemas/Version"},{"type":"null"}],"description":"Version rainfall"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","aggregation_period","provider_admin1_code","provider_admin2_code","rainfall","rainfall_long_term_average","rainfall_anomaly_pct","number_pixels","version","reference_period_start","reference_period_end"],"title":"RainfallResponse"},"AggregationPeriod":{"type":"string","enum":["dekad","1-month","3-month"],"title":"AggregationPeriod"},"Version":{"type":"string","enum":["final","forecast","preliminary"],"title":"Version"}}}}
```

## The HapiGenericResponse\_RefugeesResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_RefugeesResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RefugeesResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[RefugeesResponse]"},"RefugeesResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"population_group":{"$ref":"#/components/schemas/PopulationGroup","description":"The population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"origin_location_code":{"type":"string","maxLength":128,"title":"Origin Location Code","description":"Location of origin p-code (ISO-3)"},"origin_location_name":{"type":"string","maxLength":512,"title":"Origin Location Name","description":"Location of origin name"},"asylum_location_code":{"type":"string","maxLength":128,"title":"Asylum Location Code","description":"Location of asylum p-code (ISO-3)"},"asylum_location_name":{"type":"string","maxLength":512,"title":"Asylum Location Name","description":"Location of asylum name"}},"type":"object","required":["resource_hdx_id","population_group","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end","origin_location_code","origin_location_name","asylum_location_code","asylum_location_name"],"title":"RefugeesResponse"},"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The HapiGenericResponse\_ResourceResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_ResourceResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ResourceResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[ResourceResponse]"},"ResourceResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"dataset_hdx_id":{"type":"string","maxLength":36,"title":"Dataset Hdx Id","description":"The dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},"name":{"type":"string","maxLength":256,"title":"Name","description":"The resource name on HDX. In combination with the dataset UUIDsfrom the `dataset_hdx_id` and `resource_hdx_id` fields respectively, it can be used to construct a URL to download the resource: `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]/download/[name]`, which can be found in the `download_url` field."},"format":{"type":"string","maxLength":32,"title":"Format","description":"The format of the resource on HDX. These are typically file formats (i.e. CSV, XLSX), but can also include APIs and web apps."},"update_date":{"type":"string","format":"date-time","title":"Update Date","description":"The date the resource was last updated"},"is_hxl":{"type":"boolean","title":"Is Hxl","description":"whether or not the resource contains <a href=\"https://hxlstandard.org/\">HXL tags</a>."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"A URL to directly download the resource file from HDX, in the format specified in the `format` field."},"hapi_updated_date":{"type":"string","format":"date-time","title":"Hapi Updated Date","description":"The date that the resource was ingested into HDX HAPI"},"dataset_hdx_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Stub","description":"The URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},"dataset_hdx_title":{"type":"string","maxLength":1024,"title":"Dataset Hdx Title","description":"The title of the dataset as it appears in the HDX interface. This name is not unique and can change."},"dataset_hdx_provider_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Provider Stub","description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[dataset_hdx_provider_stub]` will load the provider's page on HDX."},"dataset_hdx_provider_name":{"type":"string","maxLength":512,"title":"Dataset Hdx Provider Name","description":"Filter the response by the display name of the provider (organization) of the dataset on HDX."},"hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Link","readOnly":true},"hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Api Link","readOnly":true},"dataset_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Dataset Hdx Link","readOnly":true},"dataset_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Dataset Hdx Api Link","readOnly":true},"provider_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Link","readOnly":true},"provider_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Api Link","readOnly":true}},"type":"object","required":["resource_hdx_id","dataset_hdx_id","name","format","update_date","is_hxl","download_url","hapi_updated_date","dataset_hdx_stub","dataset_hdx_title","dataset_hdx_provider_stub","dataset_hdx_provider_name","hdx_link","hdx_api_link","dataset_hdx_link","dataset_hdx_api_link","provider_hdx_link","provider_hdx_api_link"],"title":"ResourceResponse"}}}}
```

## The HapiGenericResponse\_ReturneesResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_ReturneesResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ReturneesResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[ReturneesResponse]"},"ReturneesResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"population_group":{"$ref":"#/components/schemas/PopulationGroup","description":"The population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"origin_location_code":{"type":"string","maxLength":128,"title":"Origin Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"origin_location_name":{"type":"string","maxLength":512,"title":"Origin Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"asylum_location_code":{"type":"string","maxLength":128,"title":"Asylum Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"asylum_location_name":{"type":"string","maxLength":512,"title":"Asylum Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["resource_hdx_id","population_group","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end","origin_location_code","origin_location_name","asylum_location_code","asylum_location_name"],"title":"ReturneesResponse"},"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The HapiGenericResponse\_SectorResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_SectorResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SectorResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[SectorResponse]"},"SectorResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the sector"}},"type":"object","required":["code","name"],"title":"SectorResponse"}}}}
```

## The HapiGenericResponse\_WfpCommodityResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_WfpCommodityResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WfpCommodityResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[WfpCommodityResponse]"},"WfpCommodityResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"The unique code identifying the commodity"},"category":{"$ref":"#/components/schemas/CommodityCategory","description":"The food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the commodity"}},"type":"object","required":["code","category","name"],"title":"WfpCommodityResponse"},"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"}}}}
```

## The HapiGenericResponse\_WfpMarketResponse\_ object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HapiGenericResponse_WfpMarketResponse_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WfpMarketResponse"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"HapiGenericResponse[WfpMarketResponse]"},"WfpMarketResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"code":{"type":"string","maxLength":32,"title":"Code","description":"The unique code identifying the market"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the market"},"lat":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"title":"Lat","description":"The market's latitude"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon","description":"The market's longitude"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","code","name","lat","lon"],"title":"WfpMarketResponse"}}}}
```

## The HumanitarianNeedsResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"HumanitarianNeedsResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"sector_code":{"type":"string","maxLength":32,"title":"Sector Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"category":{"type":"string","maxLength":128,"title":"Category","description":"A category combining gender, age range, disability marker and population group information"},"population_status":{"$ref":"#/components/schemas/PopulationStatus","description":"The population status, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-status\">here.</a>"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"sector_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Sector Name","description":"The name of the sector"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","sector_code","category","population_status","population","reference_period_start","reference_period_end","sector_name"],"title":"HumanitarianNeedsResponse"},"PopulationStatus":{"type":"string","enum":["AFF","INN","TGT","REA","all"],"title":"PopulationStatus"}}}}
```

## The IPCPhase object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"IPCPhase":{"type":"string","enum":["1","2","3","4","5","3+","all"],"title":"IPCPhase"}}}}
```

## The IPCType object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"IPCType":{"type":"string","enum":["current","first projection","second projection"],"title":"IPCType"}}}}
```

## The IdentifierResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"IdentifierResponse":{"properties":{"encoded_app_identifier":{"type":"string","maxLength":512,"title":"Encoded App Identifier","description":"Base64 encoded app_identifier compiled from application name and email address"}},"type":"object","required":["encoded_app_identifier"],"title":"IdentifierResponse"}}}}
```

## The IdpsResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"IdpsResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"reporting_round":{"type":"integer","title":"Reporting Round","description":"Data collection round number"},"assessment_type":{"$ref":"#/components/schemas/DTMAssessmentType","description":"Either baseline assessment (BA),site assessment (SA) or event track (ETT)"},"operation":{"type":"string","title":"Operation","description":"Name of DTM Operation for which the data was collected"},"population":{"type":"integer","title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","reporting_round","assessment_type","operation","population","reference_period_start","reference_period_end"],"title":"IdpsResponse"},"DTMAssessmentType":{"type":"string","enum":["BA","ETT","SA"],"title":"DTMAssessmentType"}}}}
```

## The LocationResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"LocationResponse":{"properties":{"id":{"type":"integer","title":"Id","description":"A location (typically a country), using the unique identifier (id) from the location table associated with each entry."},"code":{"type":"string","maxLength":128,"title":"Code","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"name":{"type":"string","maxLength":512,"title":"Name","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"has_hrp":{"type":"boolean","title":"Has Hrp","description":"The has_hrp flag. The has_hrp flag indicates whether a country has a Humanitarian Response Plan."},"in_gho":{"type":"boolean","title":"In Gho","description":"The in_gho flag. The in_gho flag indicates whether a country is in the <a href=\"https://humanitarianaction.info/\">Global Humanitarian Overview</a>."},"from_cods":{"type":"boolean","title":"From Cods"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["id","code","name","has_hrp","in_gho","from_cods","reference_period_start","reference_period_end"],"title":"LocationResponse"}}}}
```

## The NationalRiskResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"NationalRiskResponse":{"properties":{"risk_class":{"$ref":"#/components/schemas/RiskClass","description":"The INFORM risk class, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#risk-class\">here.</a>"},"global_rank":{"type":"integer","maximum":250,"minimum":1,"title":"Global Rank","description":"The rank of the country based on `overall_risk`. Higher rank (smaller number) is associated with more risk."},"overall_risk":{"type":"number","maximum":10,"minimum":0,"title":"Overall Risk","description":"The INFORM composite risk index, based on a combination of 54 indicators into three dimensions of risk: hazard and exposure, vulnerability, and lack of coping capacity. Risk score is given out of 10."},"hazard_exposure_risk":{"type":"number","maximum":10,"minimum":0,"title":"Hazard Exposure Risk","description":"Risk due to events that may occur, and exposure to them. Risk score is given out of 10. "},"vulnerability_risk":{"type":"number","maximum":10,"minimum":0,"title":"Vulnerability Risk","description":"Risk due to hazard susceptibility. Risk score is given out of 10."},"coping_capacity_risk":{"type":"number","maximum":10,"minimum":0,"title":"Coping Capacity Risk","description":"Risk due to lack of coping capacity to alleviate hazard impact. Risk score is given out of 10."},"meta_missing_indicators_pct":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"title":"Meta Missing Indicators Pct","description":"The average of the total number of years older than the reference year per indicator, to account for any older data used as a proxy"},"meta_avg_recentness_years":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Meta Avg Recentness Years","description":"The average of the total number of years older than the reference year per indicator, to account for any older data used as a proxy)"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["risk_class","global_rank","overall_risk","hazard_exposure_risk","vulnerability_risk","coping_capacity_risk","meta_missing_indicators_pct","meta_avg_recentness_years","reference_period_start","reference_period_end","resource_hdx_id","location_code","location_name"],"title":"NationalRiskResponse"},"RiskClass":{"type":"string","enum":["1","2","3","4","5"],"title":"RiskClass"}}}}
```

## The OperationalPresenceResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"OperationalPresenceResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"org_acronym":{"type":"string","maxLength":32,"title":"Org Acronym","description":"The organization acronym"},"org_name":{"type":"string","maxLength":512,"title":"Org Name","description":"The organization name"},"sector_code":{"type":"string","maxLength":32,"title":"Sector Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"sector_name":{"type":"string","maxLength":512,"title":"Sector Name","description":"The name of the sector"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"org_type_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Code","description":"The code referring to the organization type"},"org_type_description":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Org Type Description","description":"A description of the organization type"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","org_acronym","org_name","sector_code","sector_name","reference_period_start","reference_period_end","org_type_code","org_type_description"],"title":"OperationalPresenceResponse"}}}}
```

## The OrgResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"OrgResponse":{"properties":{"acronym":{"type":"string","maxLength":32,"title":"Acronym","description":"The organization acronym"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The organization name"},"org_type_code":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Code","description":"The code referring to the organization type"},"org_type_description":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Org Type Description","description":"A description of the organization type"}},"type":"object","required":["acronym","name","org_type_code","org_type_description"],"title":"OrgResponse"}}}}
```

## The OrgTypeResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"OrgTypeResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":" The code referring to the organization type, derived either from the [OCHA Digital Services organization types list](https://data.humdata.org/dataset/organization-types-beta), or created for HDX HAPI"},"description":{"type":"string","maxLength":512,"title":"Description","description":"A description of the organization type"}},"type":"object","required":["code","description"],"title":"OrgTypeResponse"}}}}
```

## The OutputFormat object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"OutputFormat":{"type":"string","enum":["csv","json"],"title":"OutputFormat"}}}}
```

## The PopulationGroup object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"}}}}
```

## The PopulationResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"PopulationResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","title":"Population","description":"The number of people"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end"],"title":"PopulationResponse"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The PopulationStatus object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"PopulationStatus":{"type":"string","enum":["AFF","INN","TGT","REA","all"],"title":"PopulationStatus"}}}}
```

## The PovertyRateResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"PovertyRateResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"mpi":{"type":"number","title":"Mpi","description":"The multidimensional poverty index, derived as a product of the `headcount_ratio` and `intensity_of_deprivation`. Note that this metric is presented as a fraction, while the others are percentages."},"headcount_ratio":{"type":"number","title":"Headcount Ratio","description":"The percentage of people deprived in 33% or more indicators"},"intensity_of_deprivation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Intensity Of Deprivation","description":"The average proportion of indicators in which people are deprived, given as a percentage."},"vulnerable_to_poverty":{"type":"number","title":"Vulnerable To Poverty","description":"The percentage of people deprived in 20-33% of indicators"},"in_severe_poverty":{"type":"number","title":"In Severe Poverty","description":"The percentage of people deprived in 50% or more indicators"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin_level","resource_hdx_id","mpi","headcount_ratio","intensity_of_deprivation","vulnerable_to_poverty","in_severe_poverty","reference_period_start","reference_period_end"],"title":"PovertyRateResponse"}}}}
```

## The PriceFlag object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"PriceFlag":{"type":"string","enum":["actual","aggregate","actual,aggregate"],"title":"PriceFlag"}}}}
```

## The PriceType object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"PriceType":{"type":"string","enum":["Farm Gate","Producer","Retail","Wholesale"],"title":"PriceType"}}}}
```

## The RainfallResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"RainfallResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"aggregation_period":{"$ref":"#/components/schemas/AggregationPeriod","description":"The aggregation period, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#aggregation-period\">here.</a>"},"provider_admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Provider Admin1 Code","description":"The 1st subnational administrative divisions provided in the original data source."},"provider_admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Provider Admin2 Code","description":"The 2nd subnational administrative divisions provided in the original data source."},"rainfall":{"type":"number","minimum":0,"title":"Rainfall"},"rainfall_long_term_average":{"type":"number","minimum":0,"title":"Rainfall Long Term Average"},"rainfall_anomaly_pct":{"type":"number","minimum":0,"title":"Rainfall Anomaly Pct"},"number_pixels":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Number Pixels","description":"Rainfall number pixels"},"version":{"anyOf":[{"$ref":"#/components/schemas/Version"},{"type":"null"}],"description":"Version rainfall"},"reference_period_start":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","resource_hdx_id","aggregation_period","provider_admin1_code","provider_admin2_code","rainfall","rainfall_long_term_average","rainfall_anomaly_pct","number_pixels","version","reference_period_start","reference_period_end"],"title":"RainfallResponse"},"AggregationPeriod":{"type":"string","enum":["dekad","1-month","3-month"],"title":"AggregationPeriod"},"Version":{"type":"string","enum":["final","forecast","preliminary"],"title":"Version"}}}}
```

## The RefugeesResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"RefugeesResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"population_group":{"$ref":"#/components/schemas/PopulationGroup","description":"The population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"origin_location_code":{"type":"string","maxLength":128,"title":"Origin Location Code","description":"Location of origin p-code (ISO-3)"},"origin_location_name":{"type":"string","maxLength":512,"title":"Origin Location Name","description":"Location of origin name"},"asylum_location_code":{"type":"string","maxLength":128,"title":"Asylum Location Code","description":"Location of asylum p-code (ISO-3)"},"asylum_location_name":{"type":"string","maxLength":512,"title":"Asylum Location Name","description":"Location of asylum name"}},"type":"object","required":["resource_hdx_id","population_group","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end","origin_location_code","origin_location_name","asylum_location_code","asylum_location_name"],"title":"RefugeesResponse"},"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The ResourceResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"ResourceResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"dataset_hdx_id":{"type":"string","maxLength":36,"title":"Dataset Hdx Id","description":"The dataset ID (dataset_hdx_id), which is a unique and fixed identifier of a Dataset on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]` will load the dataset page on HDX."},"name":{"type":"string","maxLength":256,"title":"Name","description":"The resource name on HDX. In combination with the dataset UUIDsfrom the `dataset_hdx_id` and `resource_hdx_id` fields respectively, it can be used to construct a URL to download the resource: `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]/download/[name]`, which can be found in the `download_url` field."},"format":{"type":"string","maxLength":32,"title":"Format","description":"The format of the resource on HDX. These are typically file formats (i.e. CSV, XLSX), but can also include APIs and web apps."},"update_date":{"type":"string","format":"date-time","title":"Update Date","description":"The date the resource was last updated"},"is_hxl":{"type":"boolean","title":"Is Hxl","description":"whether or not the resource contains <a href=\"https://hxlstandard.org/\">HXL tags</a>."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"A URL to directly download the resource file from HDX, in the format specified in the `format` field."},"hapi_updated_date":{"type":"string","format":"date-time","title":"Hapi Updated Date","description":"The date that the resource was ingested into HDX HAPI"},"dataset_hdx_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Stub","description":"The URL-safe name (dataset_hdx_stub) of the dataset as displayed on HDX. This name is unique but can change. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_stub]` will load the dataset page on HDX."},"dataset_hdx_title":{"type":"string","maxLength":1024,"title":"Dataset Hdx Title","description":"The title of the dataset as it appears in the HDX interface. This name is not unique and can change."},"dataset_hdx_provider_stub":{"type":"string","maxLength":128,"title":"Dataset Hdx Provider Stub","description":"Filter the response by the URL-safe name of the provider (organization) of the dataset on HDX. A URL in the pattern of `https://data.humdata.org/organization/[dataset_hdx_provider_stub]` will load the provider's page on HDX."},"dataset_hdx_provider_name":{"type":"string","maxLength":512,"title":"Dataset Hdx Provider Name","description":"Filter the response by the display name of the provider (organization) of the dataset on HDX."},"hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Link","readOnly":true},"hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Hdx Api Link","readOnly":true},"dataset_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Dataset Hdx Link","readOnly":true},"dataset_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Dataset Hdx Api Link","readOnly":true},"provider_hdx_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Link","readOnly":true},"provider_hdx_api_link":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Provider Hdx Api Link","readOnly":true}},"type":"object","required":["resource_hdx_id","dataset_hdx_id","name","format","update_date","is_hxl","download_url","hapi_updated_date","dataset_hdx_stub","dataset_hdx_title","dataset_hdx_provider_stub","dataset_hdx_provider_name","hdx_link","hdx_api_link","dataset_hdx_link","dataset_hdx_api_link","provider_hdx_link","provider_hdx_api_link"],"title":"ResourceResponse"}}}}
```

## The ResponseValidationResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"ResponseValidationResponse":{"properties":{"error_sample_list":{"items":{},"type":"array","title":"Error Sample List"},"error":{"type":"string","title":"Error"}},"type":"object","required":["error_sample_list","error"],"title":"ResponseValidationResponse"}}}}
```

## The ReturneesResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"ReturneesResponse":{"properties":{"resource_hdx_id":{"type":"string","maxLength":36,"title":"Resource Hdx Id","description":"The resource ID, which is a unique and fixed identifier of a resource on HDX. A URL in the pattern of `https://data.humdata.org/dataset/[dataset_hdx_id]/resource/[resource_hdx_id]` will load the resource page on HDX."},"population_group":{"$ref":"#/components/schemas/PopulationGroup","description":"The population group, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#population-group\">here.</a>"},"gender":{"$ref":"#/components/schemas/Gender","description":"The gender, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#gender\">here.</a>"},"age_range":{"type":"string","maxLength":32,"title":"Age Range","description":"The age range. These are expressed as [start age]-[end age], or [start age]+ for an age range starting at [start age] or above. The end age is assumed to be inclusive, though that is not always explicit in the source data."},"min_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Age","description":"The minimum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation"},"max_age":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Max Age","description":"The maximum age from `age_range`, set to `null` if `age_range` is \"all\" and there is no age disaggregation, or if there is no upper limit to the age range"},"population":{"type":"integer","minimum":0,"title":"Population","description":"The number of people"},"reference_period_start":{"type":"string","format":"date-time","title":"Reference Period Start","description":"The start date for which the data are applicable"},"reference_period_end":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Period End","description":"The end date for which the data are applicable"},"origin_location_code":{"type":"string","maxLength":128,"title":"Origin Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"origin_location_name":{"type":"string","maxLength":512,"title":"Origin Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"asylum_location_code":{"type":"string","maxLength":128,"title":"Asylum Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"asylum_location_name":{"type":"string","maxLength":512,"title":"Asylum Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."}},"type":"object","required":["resource_hdx_id","population_group","gender","age_range","min_age","max_age","population","reference_period_start","reference_period_end","origin_location_code","origin_location_name","asylum_location_code","asylum_location_name"],"title":"ReturneesResponse"},"PopulationGroup":{"type":"string","enum":["REF","ROC","ASY","OIP","IDP","IOC","STA","OOC","HST","RET","RST","NAT","RDP","RRI","all"],"title":"PopulationGroup"},"Gender":{"type":"string","enum":["f","m","x","u","o","all"],"title":"Gender"}}}}
```

## The RiskClass object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"RiskClass":{"type":"string","enum":["1","2","3","4","5"],"title":"RiskClass"}}}}
```

## The SectorResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"SectorResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"The sector code, derived either from the [Global Coordination Groups](https://data.humdata.org/dataset/global-coordination-groups-beta?) dataset, or created for HDX HAPI"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the sector"}},"type":"object","required":["code","name"],"title":"SectorResponse"}}}}
```

## The ValidationError object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## The Version object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"Version":{"type":"string","enum":["final","forecast","preliminary"],"title":"Version"}}}}
```

## The VersionResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"VersionResponse":{"properties":{"api_version":{"type":"string","maxLength":16,"title":"Api Version"},"hapi_sqlalchemy_schema_version":{"type":"string","maxLength":16,"title":"Hapi Sqlalchemy Schema Version"}},"type":"object","required":["api_version","hapi_sqlalchemy_schema_version"],"title":"VersionResponse"}}}}
```

## The WfpCommodityResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"WfpCommodityResponse":{"properties":{"code":{"type":"string","maxLength":32,"title":"Code","description":"The unique code identifying the commodity"},"category":{"$ref":"#/components/schemas/CommodityCategory","description":"The food group that the commodity belongs to, available values are described <a href=\"https://hdx-hapi.readthedocs.io/en/latest/data_usage_guides/enums/#commodity-category\">here.</a>"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the commodity"}},"type":"object","required":["code","category","name"],"title":"WfpCommodityResponse"},"CommodityCategory":{"type":"string","enum":["cereals and tubers","meat, fish and eggs","milk and dairy","miscellaneous food","non-food","oil and fats","pulses and nuts","vegetables and fruits"],"title":"CommodityCategory"}}}}
```

## The WfpMarketResponse object

```json
{"openapi":"3.1.0","info":{"title":"HDX HAPI","version":"0.9.13"},"components":{"schemas":{"WfpMarketResponse":{"properties":{"location_code":{"type":"string","maxLength":128,"title":"Location Code","description":"A location (typically a country). The location codes use the ISO-3 (ISO 3166 alpha-3) codes."},"location_name":{"type":"string","maxLength":512,"title":"Location Name","description":"A location (typically a country). The location names are based on the \"short name\" from the <a href=\"https://unstats.un.org/unsd/methodology/m49/#fn2\">UN M49 Standard</a>."},"admin1_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin1 Code","description":"The 1st subnational administrative divisions. The admin1 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin1_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin1 Name","description":"The 1st subnational administrative divisions. The admin1 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin2_code":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Admin2 Code","description":"The 2nd subnational administrative divisions. The admin2 codes refer to the p-codes in the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a>."},"admin2_name":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Admin2 Name","description":"The 2nd subnational administrative divisions. The admin2 names refer to either the <a href=\"https://data.humdata.org/dashboards/cod?\">Common Operational Datasets</a> or those provided in the original data source."},"admin_level":{"type":"integer","title":"Admin Level","description":"Admin level."},"code":{"type":"string","maxLength":32,"title":"Code","description":"The unique code identifying the market"},"name":{"type":"string","maxLength":512,"title":"Name","description":"The name of the market"},"lat":{"anyOf":[{"type":"number","maximum":90,"minimum":-90},{"type":"null"}],"title":"Lat","description":"The market's latitude"},"lon":{"anyOf":[{"type":"number","maximum":180,"minimum":-180},{"type":"null"}],"title":"Lon","description":"The market's longitude"}},"type":"object","required":["location_code","location_name","admin1_code","admin1_name","admin2_code","admin2_name","admin_level","code","name","lat","lon"],"title":"WfpMarketResponse"}}}}
```


# Examples and use-cases

Python examples with tools and integrations

These examples show common tasks in Python. The full documentation at hdx-hapi.readthedocs.io has the same patterns in JavaScript, Node.js, and R. In every example, replace {your app identifier} with the identifier you generated in How to query HAPI.

**A note on pagination.** Queries are capped at 10,000 rows. Larger results are silently truncated to the first 10,000 with no warning, and a higher `limit` just returns a `422`. Page through anything you don't know to be small: request pages until one comes back shorter than your page size.&#x20;

### 1. Who is doing what where

List the organizations active in a country by querying operational presence. This example returns operational presence for Afghanistan. Add a sector filter, such as sector\_name, to narrow the results to a single sector.

```python
import json
from urllib import request

APP_IDENTIFIER = "{your app identifier}"
THEME = "coordination-context/operational-presence"
LOCATION = "AFG"
LIMIT = 1000

def fetch_all(base_url, limit):
    results = []
    idx = 0
    while True:
        offset = idx * limit
        url = f"{base_url}&offset={offset}&limit={limit}"
        with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
        if len(page) < limit:
            break
        idx += 1
    return results

base_url = (
    f"https://hapi.humdata.org/api/v2/{THEME}"
    f"?location_code={LOCATION}"
    f"&output_format=json"
    f"&app_identifier={APP_IDENTIFIER}"
)

data = fetch_all(base_url, LIMIT)
print(f"Retrieved {len(data)} records")
```

### 2. Combine two sources for a food security snapshot

Since HAPI standardizes indicators across sources, you can pull food prices and food security phases for the same country and analyze them together, without learning two separate APIs. Query each sub-category with the same location\_code, then join the results in your own code.

```python
import json
from urllib import request

APP_IDENTIFIER = "{your app identifier}"
LOCATION = "AFG"
LIMIT = 1000

def fetch_all(base_url, limit):
    results = []
    idx = 0
    while True:
        offset = idx * limit
        url = f"{base_url}&offset={offset}&limit={limit}"
        with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
        if len(page) < limit:
            break
        idx += 1
    return results

def get(theme):
    base_url = (
        f"https://hapi.humdata.org/api/v2/{theme}"
        f"?location_code={LOCATION}"
        f"&output_format=json"
        f"&app_identifier={APP_IDENTIFIER}"
    )
    return fetch_all(base_url, LIMIT)

food_prices = get("food-security-nutrition-poverty/food-prices-market-monitor")
food_security = get("food-security-nutrition-poverty/food-security")
```

### 3. Population by admin level, with pagination

This loop shows the paging pattern in full: it pulls the baseline population for a country and keeps requesting pages until a page comes back shorter than the limit, meaning it has everything. Use `admin_level` and the admin filters shown in the API reference to focus on a specific administrative level.

```python
import json
from urllib import request
 
APP_IDENTIFIER = "{your app identifier}"
THEME = "geography-infrastructure/baseline-population"
LOCATION = "AFG"
LIMIT = 1000
 
def fetch_all(base_url, limit):
	results = []
	idx = 0
	while True:
    	offset = idx * limit
    	url = f"{base_url}&offset={offset}&limit={limit}"
    	with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
    	if len(page) < limit:
            break
    	idx += 1
	return results
 
base_url = (
    f"https://hapi.humdata.org/api/v2/{THEME}"
    f"?location_code={LOCATION}"
    f"&output_format=json"
    f"&app_identifier={APP_IDENTIFIER}"
)
 
records = fetch_all(base_url, LIMIT)
print(f"Retrieved {len(records)} records")
```

### 4. Conflict events over time

Conflict event data goes back to 1997, so it is useful for a simple time series. Query the conflict events sub-category for a location and group the results by date in your own code. Once you have the data array, group by the date field to build a monthly or yearly trend.

```python
import json
from collections import Counter
from urllib import request

APP_IDENTIFIER = "{your app identifier}"
THEME = "coordination-context/conflict-events"
LOCATION = "AFG"
LIMIT = 1000

def fetch_all(base_url, limit):
    results = []
    idx = 0
    while True:
        offset = idx * limit
        url = f"{base_url}&offset={offset}&limit={limit}"
        with request.urlopen(url) as response:
            page = json.loads(response.read())["data"]
        results.extend(page)
        if len(page) < limit:
            break
        idx += 1
    return results

base_url = (
    f"https://hapi.humdata.org/api/v2/{THEME}"
    f"?location_code={LOCATION}"
    f"&output_format=json"
    f"&app_identifier={APP_IDENTIFIER}"
)

events = fetch_all(base_url, LIMIT)

# Group by year to build a yearly trend.
by_year = Counter(e["reference_period_start"][:4] for e in events)
for year in sorted(by_year):
    print(year, by_year[year])
```

### See it in action

For live examples built on HAPI, explore the [data availability dashboard](https://ocha-dap.github.io/viz-hapi-availability/), and the example dashboard linked on Tools and integrations.

Do you have an example you’d like to share? Reach out to us!

## Tools and integrations

You do not need to write code to use HAPI. These integrations and resources help you pull data into common tools.

* [API sandbox](https://hapi.humdata.org/docs): build and test a query and see the response.
* [Dashboard](https://ocha-dap.github.io/hdx-hapi-example/): an example dashboard with key figures, charts, and a map for all countries in HAPI.


# Troubleshooting and error handling

Need help with the HAPI? Look no further.

### Pagination

* **Symptom: Your result set stops at exactly 10,000 records.**
* Likely cause: HAPI returns at most 10,000 records per call. A query with more matches than that is truncated without an error, so the missing records are easy to miss.
* Fix: Page through the results with limit and offset, and loop until a page returns fewer records than your limit. Keep the same query parameters across every page so the result set stays consistent. See Pagination under How to query HAPI for the full explanation, and Examples and use-cases for a ready-to-run loop.

### Missing or invalid app identifier

* **Symptom: Your request is rejected with a 403 or returns an error about the app identifier.**
* Likely cause: The app\_identifier parameter is missing, malformed, or was not URL encoded.
* Fix: Generate an identifier as shown in How to query HAPI and include it on every request, either as app\_identifier or as the header X-HDX-HAPI-APP-IDENTIFIER.

### Too many results, or the wrong ones

* **Symptom: A text filter returns more rows than expected.**
* Likely cause: Filters on text fields are case insensitive and match as wildcards, so location\_name=Mali also matches Somalia.
* Fix: Filter on a code field such as location\_code for exact matches.

### No results

* **Symptom: A successful request returns an empty data array.**
* Likely cause: A filter value that does not match, or an offset beyond the end of the data.
* Fix: Remove filters and request a small limit to confirm data exists, then add filters back one at a time. Check the availability dashboard to confirm the indicator is available for that location.

### Wrong theme or code

* **Symptom: 404 Not Found.**
* Likely cause: A mistyped theme path. A code that does not exist, such as an unknown ISO3 or p-code, does not cause a 404. That request succeeds and returns an empty data array, so see No results above.
* Fix: Confirm the theme path against the API reference page, and confirm codes using the metadata sub-categories, for example metadata/admin1.

### JSON versus CSV

* **Symptom: You expected a file but received JSON, or the reverse.**
* Fix: Set output\_format=csv to download a CSV, or use the default output\_format=json for JSON.

### Rate limiting

* **Symptom: Your request is rejected with a 429.**
* Likely cause: HAPI allows roughly 60 requests per minute. A retry loop with no delay between attempts, or an app identifier shared across several users or systems, will reach that ceiling quickly.
* Fix: Keep your request rate under the limit, add a delay between retries rather than retrying immediately, and generate your own app identifier rather than reusing one copied from an example.

<br>


# HDX Python library

Learn about the HDX library to contribute data to the platform.

The [HDX Python API](https://github.com/OCHA-DAP/hdx-python-api) is a library for reading data from HDX and creating or updating datasets in code, instead of through the website. It is maintained by the HDX team and is the recommended way to automate work on HDX.

Full usage documentation lives on [ReadTheDocs](https://hdx-python-api.readthedocs.io/en/latest/).

**Reading vs. writing:** To read metadata or data from HDX, use read-only mode with no API token. To create or update datasets, you need an API token and editor or admin rights on your organization (see [Before you write code](https://claude.ai/chat/3a208b9f-6ae2-4b39-9022-a0576d65416e#before-you-write-code)).

### When to use it

| Your situation                                                  | Best option                                    |
| --------------------------------------------------------------- | ---------------------------------------------- |
| One-off or occasional upload                                    | [HDX web interface](https://data.humdata.org/) |
| Recurring or scheduled dataset updates                          | Python library                                 |
| Managing many datasets at once                                  | Python library                                 |
| Reading HDX metadata or data for analysis (no API token needed) | Python library, read-only mode                 |
| Not using Python                                                | [rhdx](https://github.com/dickoa/rhdx) for R   |

### Before you write code

* Your organization must exist on HDX, and you need to be an editor or admin of it.
* Find your user ID and organization ID (the values passed to `set_maintainer` and `set_organization`). Look up your user ID at `https://data.humdata.org/api/3/action/user_show?id=USERNAME` and your organization ID at `https://data.humdata.org/api/3/action/organization_show?id=ORG-NAME`, replacing the placeholders with your HDX username and organization name.
* Get an API token from your [HDX profile page](https://data.humdata.org/) ([instructions](https://hdx-python-api.readthedocs.io/en/latest/#obtaining-your-api-key)).
* Test against the stage server before writing to production. Contact <hdx@un.org> for access.
* Dataset tags must come from HDX's [approved list](https://hdx-python-api.readthedocs.io/en/latest/#tags).

### Code examples

#### Create a dataset with a file resource

Install first with `pip install hdx-python-api`. Note running the same code again updates the dataset rather than creating a duplicate.

```python
from hdx.api.configuration import Configuration
from hdx.data.dataset import Dataset
from hdx.data.resource import Resource

# Connect. Use hdx_site="stage" while testing; "prod" to go live.
Configuration.create(hdx_site="stage", user_agent="MyOrg_MyProject")

# Core metadata fields
dataset = Dataset({
    "name": "my-dataset-name",       # lowercase, no spaces; becomes the URL
    "title": "My Dataset Title",     # shown on the dataset page
    "notes": "Description of the data.",
    "dataset_source": "Where the data comes from",
    "license_id": "cc-by",
    "methodology": "Other",
    "methodology_other": "How the data was collected.",
    "private": False,
})
dataset.set_organization("my-org-id")          # org the dataset belongs to
dataset.set_maintainer("my-user-id")           # who to contact about it
dataset.set_expected_update_frequency("Every month")
dataset.set_time_period("2026-01-01", "2026-06-30")  # dates the data covers
dataset.add_country_location("AFG")            # ISO3 code or country name
dataset.add_tags(["displacement", "refugees"]) # from the approved list

# Attach a file, then create
resource = Resource({"name": "mydata.csv", "description": "The data file"})
resource.set_format("csv")
resource.set_file_to_upload("path/to/mydata.csv")
dataset.add_update_resource(resource)
dataset.create_in_hdx()
```

#### Update an existing dataset

This pattern fits recurring updates: read the dataset, swap in the new file, and push the change back to HDX. To run this on a schedule, use the scraper template under [Going further](https://claude.ai/chat/3a208b9f-6ae2-4b39-9022-a0576d65416e#going-further).

```python
dataset = Dataset.read_from_hdx("my-dataset-name")
resource = dataset.get_resource(0)
resource.set_file_to_upload("path/to/new-file.csv")
dataset.update_in_hdx()
```

### Going further

* [Full usage guide and API reference](https://hdx-python-api.readthedocs.io/en/latest/): configuration, all operations, project structure.
* [Scraper template](https://github.com/OCHA-DAP/hdx-scraper-template): starting point for scheduled update pipelines.
* [IDMC scraper](https://github.com/OCHA-DAP/hdx-scraper-idmc): a complete real-world example.
* Related libraries: [hdx-python-country](https://github.com/OCHA-DAP/hdx-python-country) (country codes and names) and [hdx-python-utilities](https://github.com/OCHA-DAP/hdx-python-utilities) (downloading and data helpers).

### Questions or problems?

Email us at <hdx@un.org> or raise a [GitHub issue](https://github.com/OCHA-DAP/hdx-python-api/issues).


# HDX pipeline recommendations

Read more for HDX data standards and naming conventions

When you build a pipeline that publishes data to HDX, a few shared recommendations keep datasets consistent and discoverable. This page summarizes transformations best practices, and ideal conventions to name and describe datasets and resources.

These conventions apply to new pipelines and to existing ones that are actively being updated. These are recommendations for any developer or data contributor adding data programmatically through the [HDX Python API](https://hdx-python-api.readthedocs.io/en/latest/) or even manual uploads through the UI, and they're written with the assumption that contributors will use the HDX Python API wrapper.

### Preparing source data

Before applying any transformations, normalize raw source data to a consistent structure:

* Remove blank rows before processing.
* Remove merged cells from Excel sources before reading them. Merged cells cause misaligned data when parsed.
* Make sure column names are in the first row. If a source file has metadata rows, titles, or blank rows above the header, strip them before parsing.

*We deprecated the Humanitarian Exchange Language (HXL) standard in early 2026. Read our blog* [*here*](https://centre.humdata.org/retiring-hxl-services/) *for more information.*

### Standard transformations

The transformations below apply broadly across HDX data. Other transformations like filtering, merging, deduplication, aggregation, and type casting are applied selectively depending on the source format and the output you need.

#### Dates and times

* Store date-only values in `YYYY-MM-DD` format.
* For datetime values, include the time in UTC. Use a time component for event-based data; a date is enough for data that updates daily or less often.
* Store year-only and year-month values as full date ranges, not single dates. For example, store year-only `2026` as `2026-01-01` to `2026-12-31`, and year-month `July 2026` as `2026-07-01` to `2026-07-31`. Use `parse_date_range()` from[ hdx.utilities.dateparse](https://hdx-python-utilities.readthedocs.io/en/latest/src/hdx/utilities/dateparse/) to convert partial dates into these start/end pairs.
* Always store start and end dates in separate columns. Use a start\_date/end\_date pair when period boundaries matter, and a single date column when one reference point is enough.

#### Locations and administrative areas

* Normalize country identifiers to ISO3. Use the `Country` class from[ HDX Python Country](https://hdx-python-country.readthedocs.io/en/latest/src/hdx/location/country/#hdx.location.country.Country) for country code lookup, validation, and name-to-ISO3 resolution. It draws on the[ Countries and Territories dataset](https://data.humdata.org/dataset/countries-and-territories) on HDX, which covers name variants, aliases, and non-English names.
* For subnational data, use p-codes (`admin1_pcode`, `admin2_pcode`, and so on) as administrative identifiers, validated against the[ Global P-Codes dataset](https://data.humdata.org/dataset/global-pcodes) on HDX. Keep source admin names alongside the p-codes, but don't use the names as the primary key.
* Where p-codes are added, note the p-code version in the dataset's *Caveats* or *Methodology* metadata field.

#### String cleaning

* Strip leading and trailing whitespace from all string fields before writing output.
* Represent missing values as empty cells in CSV output (nothing between the commas).[ Frictionless](https://specs.frictionlessdata.io/), which underlies the tabular reading in HDX Python Utilities, returns empty cells as `None` in Python regardless of field type. Don't write `None`, `null`, or empty strings explicitly.
* For categorical fields such as country names or indicator codes, normalize to a consistent case before lookup or comparison, matching the convention of the target field. For example, ISO3 codes are uppercase.
* Leave non-ASCII characters as they are. Encode CSV output as `UTF-8-sig`.

### Output formats

Choose the format that best matches your data type.

| **Format**           | **When to use**                                                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| CSV                  | Most common for tabular data.                                                                                                                     |
| GeoJSON / Shapefile  | Geospatial data with geometry. GeoJSON for interoperability; Shapefile for compatibility with legacy GIS tools.                                   |
| GeoPackage           | Best performance when using QGIS.                                                                                                                 |
| File Geodatabase     | Best performance when using ArcGIS. For large datasets, produce zipped files roughly 2–3x smaller than the next alternative.                      |
| Parquet / GeoParquet | Large tabular datasets where file size and query performance matter. Use the[ geoparquet-io](https://geoparquet.io/) library with a v2.0 profile. |
| JSON                 | Nested data that doesn't fit a flat CSV structure. Document the schema.                                                                           |
| Excel                | Only when explicitly required. Output plain tabular data meaning no merged cells, colors, or formatting.                                          |

#### File size

The file size limit per resource is 300 MB. If a dataset needs a file larger than this, contact the HDX team at <hdx@un.org>.

#### Linking to external resources

Uploading files to HDX is the most common approach, but some organizations prefer to link directly to data hosted elsewhere. To do this, create the resource with a `url` field pointing to the external location instead of uploading a file. The HDX Python API sets `url_type` and `resource_type` automatically.

The minimum fields for an external resource are:

```
resource = {
    "name": "my_file.tif",
    "description": "Brief description of the resource",
    "url": "https://example.com/data.tif",
    "format": "GeoTIFF",
}
dataset.add_update_resources([resource])
```

### Naming conventions

Consistent naming improves discoverability, keeps the platform predictable, and helps datasets work together. Follow these conventions when naming and describing datasets, resources, and files.

#### Dataset title

The dataset title is the human-readable name shown on the dataset page, in search results, in HDX listings, and in external search engines.

* Start country-specific titles with the country name followed by a hyphen. For datasets that aren't country-specific, begin with the broadest meaningful scope. For example "Global" or the relevant region name.
* Use title case.
* Don't include dates or version numbers.
* Avoid organization names in titles; the data partner is already identified by its logo and metadata on the page. **Exception**: if the organization name is part of a recognized product or series (for example "WFP HungerMap" or "ACLED Conflict Data"), keep it as it identifies the product, not just the contributor.
* Avoid the word "data" as it's implicit.

| **Pattern**                 | **Example**                         |
| --------------------------- | ----------------------------------- |
| `[Country] - [Description]` | Somalia - Acute Food Insecurity     |
| `[Region] - [Description]`  | Sahel - Humanitarian Needs Overview |
| `Global - [Description]`    | Global - Requirements and Funding   |

#### Dataset name

The dataset name is the HDX URL slug for the dataset page. Use lowercase with hyphens as separators. Where the name includes a location, use the ISO3 code rather than the full name. This keeps slugs short and avoids ambiguity between name variants.

| **Dataset title**               | **Dataset name**          |
| ------------------------------- | ------------------------- |
| Somalia - Acute Food Insecurity | som-acute-food-insecurity |

#### Dataset description

The dataset description briefly summarizes what the dataset contains.

* Keep it concise in one to two paragraphs.
* Use plain language. Describe the content; leave out methodology.
* Leave the time period and geographic area to the metadata fields.
* Include useful links where relevant, such as a partner survey.

**Example:** "This dataset contains data obtained from the [HDX Humanitarian API](https://hapi.humdata.org/) (HDX HAPI), which provides standardized humanitarian indicators designed for seamless interoperability from multiple sources. The data facilitates automated workflows and visualizations to support humanitarian decision making. For more information, please see the HDX HAPI [landing page](https://data.humdata.org/hapi) and [documentation](https://hdx-hapi.readthedocs.io/en/latest/)."

#### Dataset metadata

* **Time Period:** Set the start and end dates to match the actual date range of the data.
* **Update Frequency:** Reflect how often the pipeline refreshes the data. Avoid "As needed" and "Live"; use a specific frequency such as "Every day", "Every week", or "Every month" where possible.

#### Resource name and filename

Use the same value for both the resource name and the filename.

* Use lowercase with underscores as separators to be machine-readable.
* For country-specific files, begin with the ISO3 code.
* For organization-specific files, begin with the organisation acronym.
* Use `global` in place of an ISO3 code for files covering all countries.
* Don't include dates or version numbers, unless the pipeline maintains a versioned archive, or the date is part of the identity of a specific event. For event-based data where multiple instances of the same event type can occur in the same place (for example, disaster alerts), a date suffix may be needed to avoid filename conflicts.
* Avoid the word "data" as it's implicit.

| **Pattern**                                   | **Example**                            |
| --------------------------------------------- | -------------------------------------- |
| `[iso3]_[org]_[description].[ext]`            | yem\_wfp\_hungermap.csv                |
| `global_[org]_[description].[ext]`            | global\_fts\_requirements\_funding.csv |
| `[org]_[description].[ext]`                   | wfp\_hungermap.csv                     |
| `[iso3]_[org]_[description]_[YYYYMMDD].[ext]` | yem\_wfp\_adam\_20230206.csv           |

#### Resource descriptions

Write one to three sentences describing what the file contains and any qualifiers that set it apart from other resources in the same dataset. Include the reference period and the geographic or administrative level when relevant.

* If a dataset has multiple resources, make the differences between them clear in each description.
* Spell out acronyms on first use, with the abbreviation in parentheses.

**Example:** "United States Virgin Islands carbon dioxide equivalent (CO2e) emissions on a 20-year time horizon, over the past two years, at the source level."

### Need help?

If you have questions about building a pipeline for HDX or applying these standards, contact the HDX team at <hdx@un.org>.

<br>