Need help with pycountry?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

flyingcircusio
260 Stars 49 Forks GNU Lesser General Public License v2.1 367 Commits 44 Opened issues

Description

A Python library to access ISO country, subdivision, language, currency and script definitions and their translations.

Services available

!
?

Need anything else?

Contributors list

pycountry

.. image:g: https://travis-ci.org/flyingcircusio/pycountry.svg?branch=master

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:

.. code:: pycon

import pycountry len(pycountry.countries) 249 list(pycountry.countries)[0] Country(alpha2='AF', alpha3='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:

.. code:: pycon

germany = pycountry.countries.get(alpha2='DE') germany Country(alpha2='DE', alpha3='DEU', name='Germany', numeric='276', officialname='Federal Republic of Germany') germany.alpha2 'DE' germany.alpha3 '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:

.. code:: pycon

ussr = pycountry.historiccountries.get(alpha3='SUN') ussr Country(alpha3='SUN', alpha4='SUHH', withdrawaldate='1992-08-30', name='USSR, Union of Soviet Socialist Republics', numeric='810') ussr.alpha4 'SUHH' ussr.alpha3 'SUN' ussr.name 'USSR, Union of Soviet Socialist Republics' ussr.withdrawaldate '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:

.. code:: pycon

pycountry.countries.searchfuzzy('England') [Country(alpha2='GB', alpha3='GBR', name='United Kingdom', numeric='826', officialname='United Kingdom of Great Britain and Northern Ireland')]

pycountry.countries.searchfuzzy('Cote') [Country(alpha2='CI', alpha3='CIV', name="Côte d'Ivoire", numeric='384', officialname="Republic of Côte d'Ivoire"), Country(alpha2='FR', alpha3='FRA', name='France', numeric='250', officialname='French Republic'), Country(alpha2='HN', alpha3='HND', name='Honduras', numeric='340', officialname='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:

.. code:: pycon

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

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

.. code:: pycon

dest = pycountry.subdivisions.get(code='DE-ST') dest.code 'DE-ST' dest.name 'Sachsen-Anhalt' dest.type 'State' dest.country Country(alpha2='DE', alpha3='DEU', name='Germany', numeric='276', officialname='Federal Republic of Germany')

Some subdivisions specify another subdivision as a parent:

.. code:: pycon

albr = pycountry.subdivisions.get(code='AL-BU') albr.code 'AL-BU' albr.name 'Bulqiz\xeb' albr.type 'District' albr.parentcode 'AL-09' albr.parent Subdivision(code='AL-09', countrycode='AL', name='Dib\xebr', parentcode=None, type='County') albr.parent.name 'Dib\xebr'

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

.. code:: pycon

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:

.. code:: pycon

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:

.. code:: pycon

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

Languages (ISO 639-3)

The languages database is similar too:

.. code:: pycon

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

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

bengali = pycountry.languages.get(alpha2='bn') bengali.name 'Bengali' bengali.commonname '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:

.. code:: pycon

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:

.. code:: pycon

pycountry.countries.lookup('de')

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.