hdx.location.country

Country location

Classes

CountryError
Country — Country class with various methods to help with mapping between country and region names and codes. Uses OCHA's countries and territories feed.

Bases : Exception

Country class with various methods to help with mapping between country and region names and codes. Uses OCHA's countries and territories feed.

Methods

set_countriesdata — Set up countries data from OCHA countries and territories dataset
countriesdata — Read countries data from OCHA countries feed (falling back to file). include_unofficial, use_live, country_name_overrides and country_name_mappings are taken from internal defaults if they are None, otherwise the internal defaults are overridden.
set_include_unofficial_default — Set the default for include_unofficial which defines if unofficial alpha2 and alpha3 codes such as AN and XKX will be included.
set_use_live_default — Set the default for use_live which defines if latest data is obtained from the web rather than taking data from a static file in the package.
set_ocha_url — Set OCHA url from which to retrieve countries data
set_ocha_path — Set local path from which to retrieve OCHA countries data
set_country_name_overrides — Setup name overrides using dictionary of mappings from iso3 to country name
set_country_name_mappings — Setup additional name mappings using dictionary of mappings from country name to iso3
get_country_info_from_iso3 — Get country information from ISO3 code
get_country_name_from_iso3 — Get country name from ISO3 code
get_currency_from_iso3 — Get currency code from ISO3 code
get_iso2_from_iso3 — Get ISO2 from ISO3 code
get_iso3_from_iso2 — Get ISO3 from ISO2 code
get_country_info_from_iso2 — Get country name from ISO2 code
get_country_name_from_iso2 — Get country name from ISO2 code
get_currency_from_iso2 — Get currency from ISO2 code
get_m49_from_iso3 — Get M49 from ISO3 code
get_iso3_from_m49 — Get ISO3 from M49 code
get_country_info_from_m49 — Get country name from M49 code
get_country_name_from_m49 — Get country name from M49 code
get_currency_from_m49 — Get currency from M49 code
expand_countryname_abbrevs — Expands abbreviation(s) in country name in various ways (eg. FED -> FEDERATED, FEDERAL etc.)
simplify_countryname — Simplifies country name by removing descriptive text eg. DEMOCRATIC, REPUBLIC OF etc.
get_iso3_country_code — Get ISO3 code for cls. Only exact matches or None are returned.
get_iso3_country_code_fuzzy — Get ISO3 code for cls. A tuple is returned with the first value being the ISO3 code and the second showing if the match is exact or not.
get_countries_in_region — Get countries (ISO3 codes) in region
get_hrp_status_from_iso3 — Get HRP status from ISO3 code
get_gho_status_from_iso3 — Get GHO status from ISO3 code

classmethod Country.set_countriesdata(countries: Iterator[dict]) → None

Set up countries data from OCHA countries and territories dataset

Parameters

countries : Iterator[dict] — Countries data from countries and territories dataset

Returns

None — None

Read countries data from OCHA countries feed (falling back to file). include_unofficial, use_live, country_name_overrides and country_name_mappings are taken from internal defaults if they are None, otherwise the internal defaults are overridden.

Parameters

include_unofficial : bool | None — Include unofficial country alpha codes. Defaults to False.
use_live : bool | None — Try to get latest data from web rather than file in package. Defaults to True.
country_name_overrides : dict | None — Dictionary of mappings from iso3 to country name
country_name_mappings : dict | None — Dictionary of mappings from country name to iso3
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

list[dict[str, dict]] — Countries dictionaries

classmethod Country.set_include_unofficial_default(include_unofficial: bool | None = None) → None

Set the default for include_unofficial which defines if unofficial alpha2 and alpha3 codes such as AN and XKX will be included.

Parameters

include_unofficial : bool | None — Default value to use for include_unofficial. Defaults to internal value (False).

Returns

None — None

classmethod Country.set_use_live_default(use_live: bool | None = None) → None

Set the default for use_live which defines if latest data is obtained from the web rather than taking data from a static file in the package.

Parameters

use_live : bool | None — Default value to use for use_live. Defaults to internal value (True).

Returns

None — None

classmethod Country.set_ocha_url(url: str = None) → None

Set OCHA url from which to retrieve countries data

Parameters

url : str — OCHA url from which to retrieve countries data. Defaults to internal value.

Returns

None — None

classmethod Country.set_ocha_path(path: Path | str | None = None) → None

Set local path from which to retrieve OCHA countries data

Parameters

path : Path | str | None — Local path from which to retrieve countries data. Defaults to None.

Returns

None — None

classmethod Country.set_country_name_overrides(country_name_overrides: dict) → None

Setup name overrides using dictionary of mappings from iso3 to country name

Parameters

country_name_overrides : dict — Dictionary of mappings from iso3 to country name

Returns

None — None

classmethod Country.set_country_name_mappings(country_name_mappings: dict) → None

Setup additional name mappings using dictionary of mappings from country name to iso3

Parameters

country_name_mappings : dict — Dictionary of mappings from country name to iso3

Returns

None — None

classmethod Country.get_country_info_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → dict[str, str] | None

Get country information from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get country information
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

dict[str, str] | None — country information

Raises

exception

classmethod Country.get_country_name_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, formal: bool = False, downloader: BaseDownload | None = None) → str | None

Get country name from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get country name
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
formal : bool — Return preferred name if False, formal name if True. Defaults to False.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — Country name

classmethod Country.get_currency_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → int | None

Get currency code from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get M49 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

int | None — Currency code

Raises

exception

classmethod Country.get_iso2_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → str | None

Get ISO2 from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get ISO2 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — ISO2 code

Raises

exception

classmethod Country.get_iso3_from_iso2(iso2: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → str | None

Get ISO3 from ISO2 code

Parameters

iso2 : str — ISO2 code for which to get ISO3 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — ISO3 code

Raises

exception

classmethod Country.get_country_info_from_iso2(iso2: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → dict[str, str] | None

Get country name from ISO2 code

Parameters

iso2 : str — ISO2 code for which to get country information
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

dict[str, str] | None — Country information

classmethod Country.get_country_name_from_iso2(iso2: str, use_live: bool = None, exception: Exception | None = None, formal: bool = False, downloader: BaseDownload | None = None) → str | None

Get country name from ISO2 code

Parameters

iso2 : str — ISO2 code for which to get country name
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
formal : bool — Return preferred name if False, formal name if True. Defaults to False.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — Country name

classmethod Country.get_currency_from_iso2(iso2: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → str | None

Get currency from ISO2 code

Parameters

iso2 : str — ISO2 code for which to get country information
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — Currency

classmethod Country.get_m49_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → int | None

Get M49 from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get M49 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

int | None — M49 code

Raises

exception

classmethod Country.get_iso3_from_m49(m49: int, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → str | None

Get ISO3 from M49 code

Parameters

m49 : int — M49 numeric code for which to get ISO3 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — ISO3 code

Raises

exception

classmethod Country.get_country_info_from_m49(m49: int, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → dict[str, str] | None

Get country name from M49 code

Parameters

m49 : int — M49 numeric code for which to get country information
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

dict[str, str] | None — Country information

classmethod Country.get_country_name_from_m49(m49: int, use_live: bool = None, exception: Exception | None = None, formal: bool = False, downloader: BaseDownload | None = None) → str | None

Get country name from M49 code

Parameters

m49 : int — M49 numeric code for which to get country name
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
formal : bool — Return preferred name if False, formal name if True. Defaults to False.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — Country name

classmethod Country.get_currency_from_m49(m49: int, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → str | None

Get currency from M49 code

Parameters

m49 : int — M49 numeric code for which to get country name
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — Currency

classmethod Country.expand_countryname_abbrevs(country: str) → list[str]

Expands abbreviation(s) in country name in various ways (eg. FED -> FEDERATED, FEDERAL etc.)

Parameters

country : str — Country with abbreviation(s)to expand

Returns

list[str] — Uppercase country name with abbreviation(s) expanded in various ways

classmethod Country.simplify_countryname(country: str) → tuple[str, list[str]]

Simplifies country name by removing descriptive text eg. DEMOCRATIC, REPUBLIC OF etc.

Parameters

country : str — Country name to simplify

Returns

tuple[str, list[str]] — Uppercase simplified country name and list of removed words

classmethod Country.get_iso3_country_code(country: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → str | None

Get ISO3 code for cls. Only exact matches or None are returned.

Parameters

country : str — Country for which to get ISO3 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

str | None — ISO3 country code or None

Raises

exception

classmethod Country.get_iso3_country_code_fuzzy(country: str, use_live: bool = None, exception: Exception | None = None, min_chars: int = 5, downloader: BaseDownload | None = None) → tuple[str | None, bool]

Get ISO3 code for cls. A tuple is returned with the first value being the ISO3 code and the second showing if the match is exact or not.

Parameters

country : str — Country for which to get ISO3 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
min_chars : int — Minimum number of characters for fuzzy matching to be tried. Defaults to 5.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

tuple[str | None, bool] — ISO3 code and if the match is exact or (None, False).

Raises

exception

classmethod Country.get_countries_in_region(region: int | str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → list[str]

Get countries (ISO3 codes) in region

Parameters

region : int | str — Three digit UNStats M49 region code or region name
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if region not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

list[str] — Sorted list of ISO3 country names

Raises

exception

classmethod Country.get_hrp_status_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → bool | None

Get HRP status from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get M49 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

bool | None — Has HRP (True, False or None)

classmethod Country.get_gho_status_from_iso3(iso3: str, use_live: bool = None, exception: Exception | None = None, downloader: BaseDownload | None = None) → bool | None

Get GHO status from ISO3 code

Parameters

iso3 : str — ISO3 code for which to get M49 code
use_live : bool — Try to get use latest data from web rather than file in package. Defaults to True.
exception : Exception | None — An exception to raise if country not found. Defaults to None.
downloader : BaseDownload | None — Download or Retrieve object. Defaults to None.

Returns

bool | None — In GHO (True, False or None)