pycountry

pycountry provides the ISO databases for the standards:

• 639-3 Languages
• 3166 Countries
• 3166-3 Deleted countries
• 3166-2 Subdivisions of countries
• 4217 Currencies
• 15924 Scripts

The package includes a copy from Debian's pkg-isocodes and makes the data accessible through a Python API.

Translation files for the various strings are included as well.

Data update policy

No changes to the data will be accepted into pycountry. This is a pure wrapper around the ISO standard using the pkg-isocodes database from Debian as is. If you need changes to the political situation in the world, please talk to the ISO or Debian people, not me.

Donations / Monetary Support

This is a small project that I maintain in my personal time. I am not interested in personal financial gain. However, if you would like to support the project then I would love if you would donate to Feminist Frequency instead. Also, let the world know you did so, so that others can follow your path.

Contributions

The code lives in a git repository on GitHub, and issues must be reported in there as well.

Countries (ISO 3166)

Countries are accessible through a database object that is already configured upon import of pycountry and works as an iterable:

>>> import pycountry
>>> len(pycountry.countries)
249
>>> list(pycountry.countries)[0]
Country(alpha_2='AF', alpha_3='AFG', name='Afghanistan', numeric='004', official_name='Islamic Republic of Afghanistan')

Specific countries can be looked up by their various codes and provide the information included in the standard as attributes:

>>> germany = pycountry.countries.get(alpha_2='DE')
>>> germany
Country(alpha_2='DE', alpha_3='DEU', name='Germany', numeric='276', official_name='Federal Republic of Germany')
>>> germany.alpha_2
'DE'
>>> germany.alpha_3
'DEU'
>>> germany.numeric
'276'
>>> germany.name
'Germany'
>>> germany.official_name
'Federal Republic of Germany'

The historic_countries database contains former countries that have been removed from the standard and are now included in ISO 3166-3, excluding existing ones:

>>> ussr = pycountry.historic_countries.get(alpha_3='SUN')
>>> ussr
Country(alpha_3='SUN', alpha_4='SUHH', withdrawal_date='1992-08-30', name='USSR, Union of Soviet Socialist Republics', numeric='810')
>>> ussr.alpha_4
'SUHH'
>>> ussr.alpha_3
'SUN'
>>> ussr.name
'USSR, Union of Soviet Socialist Republics'
>>> ussr.withdrawal_date
'1992-08-30'

There's also a "fuzzy" search to help people discover "proper" countries for names that might only actually be subdivisions. The fuzziness also includes normalizing unicode accents. There's also a bit of prioritization included to prefer matches on country names before subdivision names and have countries with more matches be listed before ones with fewer matches:

>>> pycountry.countries.search_fuzzy('England')
[Country(alpha_2='GB', alpha_3='GBR', name='United Kingdom', numeric='826', official_name='United Kingdom of Great Britain and Northern Ireland')]

>>> pycountry.countries.search_fuzzy('Cote')
[Country(alpha_2='CI', alpha_3='CIV', name="Côte d'Ivoire", numeric='384', official_name="Republic of Côte d'Ivoire"),
 Country(alpha_2='FR', alpha_3='FRA', name='France', numeric='250', official_name='French Republic'),
 Country(alpha_2='HN', alpha_3='HND', name='Honduras', numeric='340', official_name='Republic of Honduras')]

Country subdivisions (ISO 3166-2)

The country subdivisions are a little more complex than the countries itself because they provide a nested and typed structure.

All subdivisons can be accessed directly:

>>> len(pycountry.subdivisions)
4847
>>> list(pycountry.subdivisions)[0]
Subdivision(code='AD-07', country_code='AD', name='Andorra la Vella', parent_code=None, type='Parish')

Subdivisions can be accessed using their unique code and provide at least their code, name and type:

>>> de_st = pycountry.subdivisions.get(code='DE-ST')
>>> de_st.code
'DE-ST'
>>> de_st.name
'Sachsen-Anhalt'
>>> de_st.type
'State'
>>> de_st.country
Country(alpha_2='DE', alpha_3='DEU', name='Germany', numeric='276', official_name='Federal Republic of Germany')

Some subdivisions specify another subdivision as a parent:

>>> al_br = pycountry.subdivisions.get(code='AL-BU')
>>> al_br.code
'AL-BU'
>>> al_br.name
'Bulqiz\xeb'
>>> al_br.type
'District'
>>> al_br.parent_code
'AL-09'
>>> al_br.parent
Subdivision(code='AL-09', country_code='AL', name='Dib\xebr', parent_code=None, type='County')
>>> al_br.parent.name
'Dib\xebr'

The divisions of a single country can be queried using the country_code index:

>>> len(pycountry.subdivisions.get(country_code='DE'))
16

>>> len(pycountry.subdivisions.get(country_code='US'))
57

Scripts (ISO 15924)

Scripts are available from a database similar to the countries:

>>> len(pycountry.scripts)
169
>>> list(pycountry.scripts)[0]
Script(alpha_4='Afak', name='Afaka', numeric='439')

>>> latin = pycountry.scripts.get(name='Latin')
>>> latin
Script(alpha_4='Latn', name='Latin', numeric='215')
>>> latin.alpha4
'Latn'
>>> latin.name
'Latin'
>>> latin.numeric
'215'

Currencies (ISO 4217)

The currencies database is, again, similar to the ones before:

>>> len(pycountry.currencies)
182
>>> list(pycountry.currencies)[0]
Currency(alpha_3='AED', name='UAE Dirham', numeric='784')
>>> argentine_peso = pycountry.currencies.get(alpha_3='ARS')
>>> argentine_peso
Currency(alpha_3='ARS', name='Argentine Peso', numeric='032')
>>> argentine_peso.alpha_3
'ARS'
>>> argentine_peso.name
'Argentine Peso'
>>> argentine_peso.numeric
'032'

Languages (ISO 639-3)

The languages database is similar too:

>>> len(pycountry.languages)
7874
>>> list(pycountry.languages)[0]
Language(alpha_3='aaa', name='Ghotuo', scope='I', type='L')

>>> aragonese = pycountry.languages.get(alpha_2='an')
>>> aragonese.alpha_2
'an'
>>> aragonese.alpha_3
'arg'
>>> aragonese.name
'Aragonese'

>>> bengali = pycountry.languages.get(alpha_2='bn')
>>> bengali.name
'Bengali'
>>> bengali.common_name
'Bangla'

Locales

Locales are available in the pycountry.LOCALES_DIR subdirectory of this package. The translation domains are called isoXXX according to the standard they provide translations for. The directory is structured in a way compatible to Python's gettext module.

Here is an example translating language names:

>>> import gettext
>>> german = gettext.translation('iso3166', pycountry.LOCALES_DIR,
...                              languages=['de'])
>>> german.install()
>>> _('Germany')
'Deutschland'

Lookups

For each database (countries, languages, scripts, etc.), you can also look up entities case insensitively without knowing which key the value may match. For example:

>>> pycountry.countries.lookup('de')
<pycountry.db.Country object at 0x...>

The search ends with the first match, which is returned.