---
id: hdx-python-country
version: "4.1.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# hdx-python-country — HDX Python country code and exchange rate (fx) utilities

License: permissive · Maintenance: active · Downloads: 295.5K/mo

## What it is and what it does

The HDX Python Country Library is a utility package for working with country and region identifiers, administrative boundaries, and foreign exchange data. It maps between country names and ISO 2/3 letter codes (ISO 3166) using live official data from the UN OCHA feed with fallback to internal static files, and supports exact matching in English, French, Spanish, Russian, Chinese, and Arabic, plus fuzzy matching with abbreviation handling for English. It also handles mapping administrative level names across different sources with phonetic fuzzy matching.

Beyond geography, the package provides foreign exchange rate lookup and currency conversion, pulling current rates from Yahoo Finance with fallback to currency-api, and historic daily rates from Yahoo Finance with fallback to IMF data via IATI (with interpolation). It is part of the Humanitarian Data Exchange (HDX) project and is actively maintained with support for Python 3.10 through 3.14.

Use it for:

- Normalize country names and codes from multiple data sources into a consistent ISO 3166 format for data integration pipelines
- Perform fuzzy matching on country names with abbreviation handling to reconcile messy or informal country references in datasets
- Convert monetary amounts between local currencies and USD using current or historical exchange rates for financial analysis
- Map administrative region names from different reporting systems to a canonical base set for geographic data harmonization
- Build humanitarian data workflows that require standardized country and region identifiers aligned with UN OCHA vocabulary

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Maps country and region codes and names, matches administrative level names across sources, and provides foreign exchange rates and currency conversion.

Yes. The package is actively maintained, has low install friction, carries a permissive MIT license, and solves a real problem for data integration and humanitarian workflows. No known vulnerabilities. Use it if you need reliable country/region code mapping, multilingual name matching, or FX rate conversion backed by official data sources.

## Install

pip install hdx-python-country
uv add hdx-python-country
poetry add hdx-python-country

## Installing hdx-python-country

Before you install: Low install friction with only two runtime dependencies (hdx-python-utilities and tenacity). Active maintenance with a release 9 days ago and commits through 2026-08-05.

License in practice: MIT license permits commercial and private use with minimal restrictions; you must include a copy of the license and copyright notice.

Quickstart:

pip install hdx-python-country

from hdx.location.country import Country

country = Country.get_by_iso2('US')
print(country.name)  # 'United States'

Requires Python 3.10 or later. FX rate features depend on external data sources (Yahoo Finance, currency-api, IMF); network access required.

Verify before relying:

- Whether fuzzy matching accuracy and performance are suitable for your data volume and language mix
- Whether the fallback chain for FX rates (Yahoo Finance → currency-api → IMF) meets your SLA for rate freshness

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 295.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

country code lookup iso 3166, currency exchange rates conversion, administrative region name matching, fx rates historical data, country name fuzzy matching, geospatial-data, currency-conversion, data-integration

[View on SkillFed](https://skillfed.io/packages/hdx-python-country) · [View on PyPI](https://pypi.org/project/hdx-python-country/)