Skip to content

hdx.location.country

Country location

Country Objects

class Country()

[view_source]

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

set_countriesdata

@classmethod
def set_countriesdata(cls, countries: str) -> None

[view_source]

Set up countries data from data in form provided by UNStats and World Bank

Arguments:

  • countries str - Countries data in HTML format provided by UNStats

Returns:

None

countriesdata

@classmethod
def countriesdata(cls,
                  use_live: bool = True,
                  country_name_overrides: Dict = None,
                  country_name_mappings: Dict = None) -> List[Dict[str, Dict]]

[view_source]

Read countries data from OCHA countries feed (falling back to file)

Arguments:

  • use_live bool - Try to get use latest data from web rather than file in package. Defaults to True.
  • country_name_overrides Dict - Dictionary of mappings from iso3 to country name
  • country_name_mappings Dict - Dictionary of mappings from country name to iso3

Returns:

  • List[Dict[str,Dict]] - Countries dictionaries

set_ocha_url

@classmethod
def set_ocha_url(cls, url: Optional[str] = None) -> None

[view_source]

Set OCHA url from which to retrieve countries data

Arguments:

  • url Optional[str] - OCHA url from which to retrieve countries data. Defaults to internal value.

Returns:

None

set_country_name_overrides

@classmethod
def set_country_name_overrides(cls, country_name_overrides: Dict) -> None

[view_source]

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

Arguments:

  • country_name_overrides Dict - Dictionary of mappings from iso3 to country name

Returns:

None

set_country_name_mappings

@classmethod
def set_country_name_mappings(cls, country_name_mappings: Dict) -> None

[view_source]

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

Arguments:

  • country_name_mappings Dict - Dictionary of mappings from country name to iso3

Returns:

None

get_country_info_from_iso3

@classmethod
def get_country_info_from_iso3(
    cls,
    iso3: str,
    use_live: bool = True,
    exception: Optional[ExceptionUpperBound] = None
) -> Optional[Dict[str, str]]

[view_source]

Get country information from ISO3 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[Dict[str,str]] - country information

get_country_name_from_iso3

@classmethod
def get_country_name_from_iso3(cls,
                               iso3: str,
                               use_live: bool = True,
                               exception: Optional[ExceptionUpperBound] = None,
                               formal: bool = False) -> Optional[str]

[view_source]

Get country name from ISO3 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - 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.

Returns:

  • Optional[str] - Country name

get_currency_from_iso3

@classmethod
def get_currency_from_iso3(
        cls,
        iso3: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[int]

[view_source]

Get currency code from ISO3 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - Currency code

get_iso2_from_iso3

@classmethod
def get_iso2_from_iso3(
        cls,
        iso3: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[str]

[view_source]

Get ISO2 from ISO3 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - ISO2 code

get_iso3_from_iso2

@classmethod
def get_iso3_from_iso2(
        cls,
        iso2: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[str]

[view_source]

Get ISO3 from ISO2 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - ISO3 code

get_country_info_from_iso2

@classmethod
def get_country_info_from_iso2(
    cls,
    iso2: str,
    use_live: bool = True,
    exception: Optional[ExceptionUpperBound] = None
) -> Optional[Dict[str, str]]

[view_source]

Get country name from ISO2 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[Dict[str,str]] - Country information

get_country_name_from_iso2

@classmethod
def get_country_name_from_iso2(cls,
                               iso2: str,
                               use_live: bool = True,
                               exception: Optional[ExceptionUpperBound] = None,
                               formal: bool = False) -> Optional[str]

[view_source]

Get country name from ISO2 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - 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.

Returns:

  • Optional[str] - Country name

get_currency_from_iso2

@classmethod
def get_currency_from_iso2(
        cls,
        iso2: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[str]

[view_source]

Get currency from ISO2 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - Currency

get_m49_from_iso3

@classmethod
def get_m49_from_iso3(
        cls,
        iso3: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[int]

[view_source]

Get M49 from ISO3 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[int] - M49 code

get_iso3_from_m49

@classmethod
def get_iso3_from_m49(
        cls,
        m49: int,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[str]

[view_source]

Get ISO3 from M49 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - ISO3 code

get_country_info_from_m49

@classmethod
def get_country_info_from_m49(
    cls,
    m49: int,
    use_live: bool = True,
    exception: Optional[ExceptionUpperBound] = None
) -> Optional[Dict[str, str]]

[view_source]

Get country name from M49 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[Dict[str,str]] - Country information

get_country_name_from_m49

@classmethod
def get_country_name_from_m49(cls,
                              m49: int,
                              use_live: bool = True,
                              exception: Optional[ExceptionUpperBound] = None,
                              formal: bool = False) -> Optional[str]

[view_source]

Get country name from M49 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - 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.

Returns:

  • Optional[str] - Country name

get_currency_from_m49

@classmethod
def get_currency_from_m49(
        cls,
        m49: int,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[str]

[view_source]

Get currency from M49 code

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - Currency

expand_countryname_abbrevs

@classmethod
def expand_countryname_abbrevs(cls, country: str) -> List[str]

[view_source]

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

Arguments:

  • country str - Country with abbreviation(s)to expand

Returns:

  • List[str] - Uppercase country name with abbreviation(s) expanded in various ways

simplify_countryname

@classmethod
def simplify_countryname(cls, country: str) -> (str, List[str])

[view_source]

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

Arguments:

  • country str - Country name to simplify

Returns:

Tuple[str, List[str]]: Uppercase simplified country name and list of removed words

get_iso3_country_code

@classmethod
def get_iso3_country_code(
        cls,
        country: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> Optional[str]

[view_source]

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

Arguments:

  • 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 Optional[ExceptionUpperBound] - An exception to raise if country not found. Defaults to None.

Returns:

  • Optional[str] - ISO3 country code or None

get_iso3_country_code_fuzzy

@classmethod
def get_iso3_country_code_fuzzy(
        cls,
        country: str,
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None,
        min_chars: int = 5) -> Tuple[Optional[str], bool]

[view_source]

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.

Arguments:

  • 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 Optional[ExceptionUpperBound] - 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.

Returns:

Tuple[Optional[str], bool]]: ISO3 code and if the match is exact or (None, False).

get_countries_in_region

@classmethod
def get_countries_in_region(
        cls,
        region: Union[int, str],
        use_live: bool = True,
        exception: Optional[ExceptionUpperBound] = None) -> List[str]

[view_source]

Get countries (ISO3 codes) in region

Arguments:

  • region Union[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 Optional[ExceptionUpperBound] - An exception to raise if region not found. Defaults to None.

Returns:

  • List(str) - Sorted list of ISO3 country names