countryguess 0.4.9

countryguess looks up country information by country codes or name matching. It tries to be lean (but not mean) and fast: All dependencies are in the Python Standard Library and country data is loaded lazily on demand.

Code: Codeberg
Package: PyPI

Usage

guess_country() uses the default country data that is already packaged.

>>> from countryguess import guess_country
>>> guess_country("britain")
{
    'name_short': 'United Kingdom',
    'name_official': 'United Kingdom of Great Britain and Northern Ireland',
    'iso2': 'GB',
    'iso3': 'GBR',
    ...
}
>>> guess_country("no such country")
None
>>> guess_country("no such country", default="Oh, well.")
'Oh, well.'
>>> guess_country("PoRtUgAl", attribute="iso2")
'PT'
>>> guess_country("TW", attribute="name_official")  # 2-letter code lookup
'Republic of China'
>>> guess_country("tWn", attribute="name_short")    # 3-letter code lookup
'Taiwan'

Matching by regular expression can be extended by mapping ISO2 codes to re.Pattern objects.

>>> regex_map = {
...     "MN": re.compile(r'^mongol\s+uls$', flags=re.IGNORECASE),
...     "JP": re.compile(r'^ni(?:pp|h)on', flags=re.IGNORECASE),
... }
>>> guess_country("Mongol Uls", attribute="name_short", regex_map=regex_map)
'Mongolia'
>>> guess_country("Nippon", attribute="name_short", regex_map=regex_map)
'Japan'

You can also create a CountryData instance yourself to provide your own country data in a JSON file.

>>> from countryguess import CountryData
>>> countries = CountryData("path/to/countries.json")
>>> countries["vIeTnAm"]
{'name_short': 'Vietnam', ...}
>>> countries["vn"]
{'name_short': 'Vietnam', ...}
>>> countries["asdf"]
KeyError: 'asdf'
>>> countries.get("asdf")
None
>>> countries.get("kuwait")
{'name_short': 'Kuwait', ...}

On CountryData instances, every key in the JSON data is accessible as a method.

>>> countries.name_official("portugal")
'Portuguese Republic'
>>> countries.continent("vanuatu")
'Oceania'

Country Lookup

Countries are identified by name, 2-letter code (ISO 3166-1 alpha-2) or 3-letter code (ISO 3166-1 alpha-3). All identifiers are matched case-insensitively.

Names are matched with regular expressions that are stored in the JSON data. If that fails, fuzzy matching against name_short and name_official is done with difflib.

Country Data

Country information is read from a JSON file. One is shipped with the package, but you can also provide your own to the CountryData class as described above. The information in the default file was gratefully extracted from country-converter. (Many thanks!)

The country data file must contain a list of JSON objects. Each object represents a country that must contain at least the following keys:

• name_short
• name_official
• iso2
• iso3
• regex

Packaged Classification Schemes

The following classification schemes are available in the included country data.

1. ISO2 (ISO 3166-1 alpha-2) - including UK/EL for Britain/Greece (but always convert to GB/GR)
2. ISO3 (ISO 3166-1 alpha-3)
3. ISO - numeric (ISO 3166-1 numeric)
4. UN numeric code (M.49 - follows to a large extend ISO-numeric)
5. A standard or short name
6. The "official" name
7. Continent: 6 continent classification with Africa, Antarctica, Asia, Europe, America, Oceania
8. Continent_7 classification - 7 continent classification spliting North/South America
9. UN region
10. EXIOBASE 1 classification (2 and 3 letters)
11. EXIOBASE 2 classification (2 and 3 letters)
12. EXIOBASE 3 classification (2 and 3 letters)
13. WIOD classification
14. Eora
15. OECD membership (per year)
16. MESSAGE 11-region classification
17. IMAGE
18. REMIND
19. UN membership (per year)
20. EU membership (including EU12, EU15, EU25, EU27, EU27_2007, EU28)
21. CoE (Council of Europe) membership
22. EEA membership
23. Schengen region
24. Cecilia 2050 classification
25. APEC
26. BRIC
27. BASIC
28. CIS (as by 2019, excl. Turkmenistan)
29. G7
30. G20 (listing all EU member states as individual members)
31. FAOcode (numeric)
32. GBDcode (numeric - Global Burden of Disease country codes)
33. IEA (World Energy Balances 2021)
34. DACcode (numeric - OECD Development Assistance Committee)
35. ccTLD - country code top-level domains
36. GWcode - Gledisch & Ward numerical codes as published in https://www.andybeger.com/states/articles/statelists.html
37. CC41 - common classification for MRIOs (list of countries found in all public MRIOs)
38. IOC - International Olympic Committee (IOC) country codes
39. BACI - BACI: International Trade Database at the Product-Level
40. UNIDO - UNIDO INDSTAT database
41. EXIOBASE hybrid 3 classification
42. EXIOBASE hybrid 3 consequential classification
43. GEOnumeric GEO numerical codes (also used in Prodcom)
44. FIFA List of FIFA country codes
45. IEA v2025 Country classification used in IEA World Extended Energy Balances for v2025 of the dataset.

Command Line Interface

countryguess comes with a simple CLI with the same name. It takes one or two arguments:

$ countryguess oman
{
    "name_short": "Oman",
    "name_official": "Sultanate of Oman",
    ...
}
$ countryguess 'puerto ricco' name_official
Puerto Rico

Contributing

All kinds of bug reports, feature requests and suggestions are welcome!