hdx-python-country

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 on this page — 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

hdx-python-country on PyPI

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

Evidence: hdx_python_country-4.1.4-py3-none-any.whl

Keywords: HDX, country, country code, currencies, currency, exchange rate, foreign exchange, fx, iso 3166, iso2, iso3, location, region

Tags

More Python Modules packages