Countryinfo
A lightweight Python library for accessing comprehensive country data — including ISO codes, states/provinces, capital cities, currencies, languages, and other geographic information.
Install / Use
/learn @porimol/CountryinfoREADME
Countryinfo
A lightweight Python library for accessing comprehensive country data — including ISO codes, states/provinces, capital cities, currencies, languages, and other geographic information.
<div align="center"> <a href="https://pypi.org/project/countryinfo/"> <img src="https://img.shields.io/pypi/v/countryinfo?style=for-the-badge&logo=pypi&logoColor=white&color=blue" alt="PyPI Version" height="30"> </a> <a href="https://pypi.org/project/countryinfo/"> <img src="https://img.shields.io/pypi/pyversions/countryinfo?style=for-the-badge&logo=python&logoColor=white" alt="Python Versions" height="30"> </a> <a href="LICENSE"> <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="License: MIT" height="30"> </a> <h3>☕ Support This Project</h3> <p> This project is developed and maintained during the author's free time. If you find it useful and would like to support its continued development, consider buying a coffee or sponsoring the project. Every bit of support helps keep the project maintained and improving ❤️ </p> <a href="https://pepy.tech/projects/countryinfo"> <img src="https://static.pepy.tech/badge/countryinfo/week?style=for-the-badge&color=darkgreen" alt="Weekly Downloads" height="30"> </a> <a href="https://pepy.tech/projects/countryinfo"> <img src="https://static.pepy.tech/badge/countryinfo/month?style=for-the-badge&color=green" alt="Monthly Downloads" height="30"> </a> <a href="https://pepy.tech/projects/countryinfo"> <img src="https://static.pepy.tech/badge/countryinfo?style=for-the-badge&color=brightgreen" alt="Total Downloads" height="30"> </a> <br> <a href="https://buymeacoffee.com/porimolchad"> <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="45"> </a> <a href="https://github.com/sponsors/porimol"> <img src="https://img.shields.io/badge/GitHub%20Sponsors-%E2%9D%A4%EF%B8%8F%20Sponsor-ea4aaa?style=for-the-badge&logo=github-sponsors&logoColor=white" alt="GitHub Sponsors" height="45"> </a> </div>Table of Contents
- Countryinfo
- Table of Contents
- Install
- Quick Start
- Constructor
- API Reference
- Country lookup
- .info()
- .name()
- .iso()
- .alt_spellings()
- .area()
- .borders()
- .neighbors()
- .calling_codes()
- .capital()
- .capital_latlng()
- .currencies()
- .demonym()
- .geo_json()
- .languages()
- .latlng()
- .native_name()
- .population()
- .provinces()
- .region()
- .subregion()
- .timezones()
- .timezone_names()
- .current_utc_offset()
- .tld()
- .translations()
- .wiki()
- .google()
- Filter & Reverse Queries
- Optional Extras
- CLI
- Errors
- Contributing
- Special Thanks
- Disclaimer
- License
Install
pip install countryinfo
With optional extras:
pip install "countryinfo[fuzzy]" # typo-tolerant country lookup
pip install "countryinfo[pydantic]" # Pydantic v2 typed models
pip install "countryinfo[all]" # everything above
Using Poetry:
poetry add countryinfo
poetry add "countryinfo[fuzzy,pydantic]"
Install from source:
git clone https://github.com/porimol/countryinfo.git
cd countryinfo
poetry install
Quick Start
from countryinfo import CountryInfo
country = CountryInfo("Singapore")
print(country.capital()) # Singapore
print(country.iso(2)) # SG
print(country.population()) # 5469700
print(country.neighbors()) # [] — island, no land borders
Constructor
CountryInfo accepts any of the following identifiers (case-insensitive):
CountryInfo("Singapore") # English name
CountryInfo("singapore") # lowercase — OK
CountryInfo("SG") # ISO alpha-2
CountryInfo("SGP") # ISO alpha-3
CountryInfo("702") # ISO numeric (string or int)
CountryInfo(702) # ISO numeric (int)
CountryInfo("Singapura") # native / alternate name
CountryInfo("Republic of Singapore") # full official name
Raises ValueError if no identifier is supplied.
Raises CountryNotFoundError (a LookupError) if the identifier cannot be resolved.
API Reference
To access country details, first create a CountryInfo instance using a country name or code. Then, use the methods listed below to retrieve specific properties.
Country lookup
from countryinfo import CountryInfo
sg = CountryInfo("SG") # ISO alpha-2
de = CountryInfo("DEU") # ISO alpha-3
fr = CountryInfo(250) # ISO numeric
.info()
Returns all available data for the country.
CountryInfo("Singapore").info()
# {
# 'name': 'Singapore',
# 'ISO': {'alpha2': 'SG', 'alpha3': 'SGP', 'numeric': '702'},
# 'altSpellings': ['SG', 'Singapura', 'Republic of Singapore', ...],
# 'area': 710,
# 'borders': [],
# 'callingCodes': ['65'],
# 'capital': 'Singapore',
# 'capital_latlng': [1.357107, 103.819499],
# 'currencies': ['SGD'],
# 'demonym': 'Singaporean',
# 'languages': ['en', 'ms', 'ta', 'zh'],
# 'latlng': [1.36666666, 103.8],
# 'nativeName': 'Singapore',
# 'population': 5469700,
# 'provinces': ['Singapore'],
# 'region': 'Asia',
# 'subregion': 'South-eastern Asia',
# 'timezones': ['UTC+08:00'],
# 'timezoneNames': ['Asia/Singapore'],
# 'tld': ['.sg'],
# 'translations': {'de': 'Singapur', 'es': 'Singapur', ...},
# 'wiki': 'http://en.wikipedia.org/wiki/singapore',
# 'google': 'https://www.google.com/search?q=Singapore',
# }
# Similar can also be achieved via country code or any
# alternate name of a country. For example, Singapur
# would be:
country = CountryInfo('SG')
country.info()
.name()
Returns the English country name (proper casing).
CountryInfo("SG").name() # 'Singapore'
CountryInfo("SGP").name() # 'Singapore'
.iso()
Returns ISO 3166-1 codes. Now includes numeric code.
country = CountryInfo("Singapore")
country.iso() # {'alpha2': 'SG', 'alpha3': 'SGP', 'numeric': '702'}
country.iso(2) # 'SG'
country.iso(3) # 'SGP'
.alt_spellings()
Returns alternate spellings for the name of a specified country
CountryInfo("Singapore").alt_spellings()
# ['SG', 'Singapura', 'Republic of Singapore', ...]
.area()
Returns area (km²) for a specified country
CountryInfo("Singapore").area() # 710
# or
country = CountryInfo("Singapore")
country.area() # 710
.borders()
Bordering countries as ISO alpha-3 codes.
CountryInfo("Germany").borders()
# ['AUT', 'BEL', 'CHE', 'CZE', 'DNK', 'FRA', 'LUX', 'NLD', 'POL']
# or
country = CountryInfo("Singapore")
country.borders()
.neighbors()
Bordering countries as CountryInfo objects. New in v1.0.0.
for neighbor in CountryInfo("France").neighbors():
print(neighbor.name(), neighbor.capital())
# Germany Berlin
# Belgium Brussels
# ...
.calling_codes()
Returns international calling codes for a specified country
CountryInfo("Singapore").calling_codes() # ['65']
# or
country = CountryInfo("Singapore")
country.calling_codes() # ['65']
.capital()
Returns capital city for a specified country
CountryInfo("Singapore").capital() # 'Singapore'
# or
country = CountryInfo("Singapore")
country.capital() # 'Singapore'
.capital_latlng()
Returns capital city latitude and longitude for a specified country
CountryInfo("Singapore").capital_latlng() # [1.357107, 103.819499]
# or
country = CountryInfo("Singapore")
country.capital_latlng() # [1.357107, 103.819499]
.currencies()
CountryInfo("Singapore").currencies() # ['SGD']
# or
country = CountryInfo("Singapore")
country.currencies() # ['SGD']
.demonym()
CountryInfo("Singapore").demonym() # 'Singaporean'
# or
country = CountryInfo("Singapore")
country.demonym() # 'Singaporean'
.geo_json()
Returns GeoJSON FeatureCollection for the country boundary.
CountryInfo("Bangladesh").geo_json()
# {'type': 'FeatureCollection', 'features': [...]}
# or
country = CountryInfo("Singapore")
country.geo_json()
# {'type': 'FeatureCollection', 'features': [...]}
.languages()
ISO 639-1 language codes.
CountryInfo("Singapore").languages() # ['en', 'ms', 'ta', 'zh']
# or
country = CountryInfo("Singapore")
country.languages() # ['en', 'ms', 'ta', 'zh']
.latlng()
Approximate country centre coordinates.
CountryInfo("Singapore").latlng() # [1.36666666, 103.8]
# or
country = CountryInfo("Singapore")
country.latlng()
.native_name()
Returns the name of the country in its native tongue
CountryInfo("Germany").native_name() # 'Deutschland'
# or
country = CountryInfo("Germany")
country.n
