HDX Python library

Learn about the HDX library to contribute data to the platform.

The 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.

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).

When to use it

Your situation	Best option
One-off or occasional upload	HDX web interface
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 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 (instructions).
• Test against the stage server before writing to production. Contact [e-mail] for access.
• Dataset tags must come from HDX's approved list.

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.

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.

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: configuration, all operations, project structure.
• Scraper template: starting point for scheduled update pipelines.
• IDMC scraper: a complete real-world example.
• Related libraries: hdx-python-country (country codes and names) and hdx-python-utilities (downloading and data helpers).

Questions or problems?

Email us at [e-mail] or raise a GitHub issue.