What is an SDK for Humanitarian Data Exchange?

An SDK (Software Development Kit) for Humanitarian Data Exchange is a collection of tools and libraries that simplify interacting with the HDX API, allowing developers to programmatically access, search, and download humanitarian datasets directly from their applications or scripts.

Which programming languages are supported by official HDX SDKs?

The Humanitarian Data Exchange officially supports a Python SDK, named `hdx-python-api`, which is the primary tool for developers and data scientists working with HDX data.

How do I install the Python SDK for HDX?

You can install the official Python SDK using `pip`, the Python package installer. Open your terminal and run `pip install hdx-python-api`.

Do I need an API key to use the HDX SDKs?

While many public datasets on HDX can be accessed without an API key, it is generally recommended to configure one for consistent access, higher rate limits, and certain specific API operations. Check the official HDX API documentation for details.

Are there community-contributed libraries for other languages?

Yes, while not officially supported, the open nature of the HDX API allows developers to create community-contributed libraries in various languages. You can often find these on public code repositories like GitHub, but their quality and maintenance may vary.

Can I access HDX data without using an SDK?

Yes, you can access the HDX API directly using any standard HTTP client library in your preferred programming language. The SDK primarily abstracts the complexities of direct API calls, offering a more convenient and idiomatic interface.

Where can I find documentation for the HDX API and SDKs?

The primary documentation for the HDX API is available on the Humanitarian Data Exchange website at data.humdata.org/about/api. This resource includes API specifications and guidance for using the official Python SDK.

Humanitarian Data Exchange SDKs & Libraries (2026)

SDKs overview

The Humanitarian Data Exchange (HDX) platform offers programmatic access to its extensive collection of humanitarian datasets through a RESTful API. Software Development Kits (SDKs) and client libraries simplify interaction with this API, abstracting HTTP requests and JSON parsing into language-specific functions and objects. These tools facilitate tasks such as searching for datasets, retrieving metadata, and downloading data files directly into development environments. The HDX API is designed to provide access to data for humanitarian crisis response, research, and analysis.

While the HDX API can be accessed using any HTTP client, SDKs improve developer experience by providing idiomatic interfaces for common operations. Developers can integrate humanitarian data into custom applications, dashboards, or analytical scripts, supporting various use cases from real-time crisis monitoring to long-term trend analysis. The primary focus for official tooling is Python, reflecting its prevalence in data science and analytical workflows.

The HDX platform emphasizes open data principles, providing all data access free of charge. This commitment extends to its API and associated tools, ensuring that developers and organizations can integrate critical humanitarian information without financial barriers. The API documentation serves as the authoritative guide for all endpoints and data models, enabling developers to build robust integrations whether using an SDK or direct API calls. For detailed information on the API, refer to the Humanitarian Data Exchange API documentation.

Official SDKs by language

The Humanitarian Data Exchange primarily supports a Python SDK, reflecting the platform's user base of data scientists, researchers, and analysts who frequently utilize Python for data manipulation and statistical computing. This official SDK is maintained to align with the latest HDX API specifications and provides a streamlined interface for common tasks.

The official Python SDK provides methods for authenticating with the API, searching for datasets, retrieving dataset metadata, accessing resource lists, and downloading data files. It handles pagination and error handling, reducing the boilerplate code required for API interactions. This makes it suitable for both interactive data exploration in notebooks and integration into larger applications.

Language	Package Name	Install Command	Maturity
Python	`hdx-python-api`	`pip install hdx-python-api`	Stable

The official Python library aims to encapsulate the complexities of the HDX API, allowing developers to focus on data utilization rather than API mechanics. For example, it simplifies the process of finding specific datasets related to a crisis or country and retrieving their associated data resources. Maintaining an up-to-date SDK is critical for ensuring developers can reliably access the most current humanitarian data available on the platform.

Installation

Installing the official Python SDK for Humanitarian Data Exchange typically involves using pip, the standard package installer for Python. Before installation, it is recommended to use a virtual environment to manage dependencies and avoid conflicts with other Python projects. Tools like venv or conda can create isolated environments.

Python

To install the hdx-python-api package, open your terminal or command prompt and execute the following command:

pip install hdx-python-api

This command downloads the package and its dependencies from the Python Package Index (PyPI) and installs them into your active Python environment. After successful installation, you can import the library into your Python scripts or interactive sessions.

For development environments or specific versions, you might install directly from the source repository if provided, though pip is the recommended method for most users. Ensure your Python version meets the requirements specified by the SDK to avoid compatibility issues. Python's official documentation provides further guidance on installing Python packages.

Quickstart example

This quickstart example demonstrates how to use the hdx-python-api to search for datasets related to a specific country and retrieve basic information about them. This example assumes you have already installed the SDK as described in the installation section.

First, you need to initialize the HDX API connection. While an API key is not always mandatory for public data access, it's good practice to configure it if you have one, especially for rate limits or specific operations. For this example, we will perform a basic search that typically does not require an API key.

from hdx.api.configuration import Configuration
from hdx.data.dataset import Dataset

# Initialize HDX Configuration (replace 'your_user_agent' with a descriptive string)
# An API key might be necessary for certain operations or higher rate limits.
# Configuration.setup(hdx_site='prod', user_agent='my_humanitarian_app', api_key='YOUR_API_KEY')
Configuration.setup(hdx_site='prod', user_agent='my_humanitarian_app')

# Search for datasets related to 'Syria'
search_term = 'Syria'
datasets = Dataset.search_in_hdx(search_term)

if datasets:
    print(f"Found {len(datasets)} datasets related to '{search_term}':")
    for dataset in datasets[:5]: # Print details for the first 5 datasets
        print(f"  Title: {dataset['title']}")
        print(f"  Organization: {dataset['organization']['title']}")
        print(f"  Update Frequency: {dataset.get('update_frequency', 'N/A')}")
        print(f"  HDX URL: {dataset.get('hdx_link')}")
        print("\n")
else:
    print(f"No datasets found for '{search_term}'.")

# Example of retrieving a specific dataset by ID or name
# If you know the ID or name, you can get the full dataset object
# dataset_name = 'syria-conflict-data'
# try:
#     syria_dataset = Dataset.read_from_hdx(dataset_name)
#     print(f"Details for dataset '{dataset_name}':")
#     print(f"  Tags: {[tag['name'] for tag in syria_dataset['tags']]}")
# except Exception as e:
#     print(f"Error reading dataset '{dataset_name}': {e}")

This script first configures the HDX API client with a user agent, which is important for identifying your application to the HDX servers. It then performs a search for datasets containing the term 'Syria' and iterates through the first five results, printing their titles, organizations, update frequencies, and HDX links. This provides a quick way to explore available data programmatically.

For more advanced usage, such as downloading specific resources, filtering by tags, or handling different data formats, consult the official HDX API documentation and the hdx-python-api library's examples.

Community libraries

While the Humanitarian Data Exchange maintains an official Python SDK, the open nature of its API allows for the development of community-contributed libraries and tools in various programming languages. These community efforts extend the reach of HDX data to developers working in ecosystems not officially supported by the HDX team.

Community libraries often arise from specific project needs or developer preferences. They can range from simple API wrappers to more comprehensive tools that integrate HDX data with other platforms or provide specialized data visualization capabilities. The quality, maintenance, and features of these libraries can vary significantly, as they are not officially supported or guaranteed by the Humanitarian Data Exchange.

Developers interested in using or contributing to community libraries should consult public code repositories, such as GitHub, and community forums. Searching for terms like "HDX API client" or "Humanitarian Data Exchange" alongside a programming language (e.g., "HDX API R" or "HDX API JavaScript") can yield relevant results. When evaluating community libraries, consider:

Active Maintenance: Is the library regularly updated to reflect API changes or bug fixes?
Documentation: Is there clear and sufficient documentation for installation and usage?
Community Support: Does the project have an active community for questions and issue resolution?
License: Is the library released under an open-source license compatible with your project?

Though not an SDK, a common way to consume web APIs is through generic HTTP client libraries available in almost every programming language. For example, JavaScript developers might use fetch or axios to interact with the HDX API, while Java developers might use OkHttp or Apache HttpClient, as documented by Mozilla's Fetch API guide. These clients provide the foundational capabilities to build custom integrations when a dedicated SDK is not available or desired.

Engaging with the broader developer community through platforms like Stack Overflow or dedicated HDX user groups can also provide insights into existing community-developed tools and best practices for integrating with the HDX API using various programming languages and frameworks. While the official Python SDK is the recommended starting point, community initiatives play a vital role in expanding access to humanitarian data.