> For the complete documentation index, see [llms.txt](https://docs.humdata.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humdata.org/build/hdx-python-library.md).

# HDX Python library

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.humdata.org/build/hdx-python-library.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.