The HDX CKAN API is the primary API provided by HDX for accessing data stored on the HDX platform.

• CKAN is an open-source data management platform used by HDX to collect and share data.
• It allows users to perform various operations such as searching for datasets, retrieving dataset metadata, downloading datasets, updating datasets and accessing other platform functionalities.
• While the API allows users to find resources, accessing the data and searching inside it is not possible without downloading the data or employing external tools (such as HXL Proxy). For guidance on using the API effectively, please refer to the HDX CKAN API Cookbook, which provides many practical examples.
• This API is based on the standard CKAN API and is used for data integration and automation. For advanced search functionality including metadata filtering, see our Solr Search Reference.

HDX has a RESTful API largely unchanged from the underlying CKAN API which can be used from any programming language that supports HTTP GET and POST requests. However, the terminology that CKAN uses is a little different to the HDX user interface. Hence, we have developed wrappers for specific languages that harmonise the nomenclature and simplify the interaction with HDX.
These APIs allow various operations such as searching, reading and writing dataset metadata, but not the direct querying of data within resources which can point to files or urls and of which there can be more than one per dataset.

The recommended way of developing against HDX is to use the HDX Python API. This is a mature library that supports Python 3 with tests that have a high level of code coverage. The major goal of the library is to make pushing and pulling data from HDX as simple as possible for the end user. There are several ways this is achieved. It provides a simple interface that communicates with HDX using the CKAN Python API, a thin wrapper around the CKAN REST API. The HDX objects, such as datasets and resources, are represented by Python classes. This should make the learning curve gentle and enable users to quickly get started with using HDX programmatically. For example, to read a dataset and get its resources, you would simply do:

from hdx.api.configuration import Configuration
from hdx.data.dataset import Dataset
Configuration.create(hdx_site="prod", user_agent="A_Quick_Example", hdx_read_only=True)
dataset = Dataset.read_from_hdx("novel-coronavirus-2019-ncov-cases")
resources = dataset.get_resources()

There is library API-level documentation available online.
If you intend to push data to HDX, then it may be helpful to start with this scraper template which shows what needs to be done to create datasets on HDX. It should be straightforward to adapt the template for your needs.

If you wish to read data from HDX for analysis in R, then you can use the rhdx package. The goal of this package is to provide a simple interface to interact with HDX. Like the Python API, it is a wrapper around the CKAN REST API. rhdx is not yet fully mature and some breaking changes are expected.

If you need to use another language or simply want to examine dataset metadata in detail in your web browser, then you can use CKAN’s RESTful API, a powerful, RPC-style interface that exposes all of CKAN’s core features to clients.

HDX HAPI is a newer API provided by HDX specifically designed to serve humanitarian data needs.

• It provides direct access to curated and standardised data focused on humanitarian operations and crises.
• It includes features that support querying data based on humanitarian themes, locations, and other relevant criteria.
• Read the documentation.

Humanitarian projects frequently require handling countries, locations and regions in particular dealing with inconsistent country naming between different data sources and different coding standards like ISO3 and M49. The HDX Python Country library was created to fulfill these requirements. It provides utilities to map between country and region codes and names and to match administrative level names from different sources. It also provides utilities for foreign exchange enabling obtaining current and historic FX rates for different currencies. It has library API-level documentation available online.

All kinds of utility functions have been coded over time for use internally, so since we think these have value externally, it was decided that they should be packaged into the HDX Python Utilities library. It provides a range of helpful utilities for Python developers including streaming tabular data, date parsing, JSON and YAML handling, dictionary and list utilities. It has library API-level documentation available online.

If you have any questions about these resources, we will do our best to answer them. We would also love to hear about how you are using them for your work.

Please contact us at: [email protected]. Sign up to receive our newsletter here.