https://github.com/kwzrd/pypopulation
Population lookup via ISO 3166 country codes
https://github.com/kwzrd/pypopulation
country country-codes iso-3166 iso3166 population python
Last synced: 6 months ago
JSON representation
Population lookup via ISO 3166 country codes
- Host: GitHub
- URL: https://github.com/kwzrd/pypopulation
- Owner: kwzrd
- License: other
- Created: 2020-08-22T21:17:59.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2021-06-22T16:40:11.000Z (about 5 years ago)
- Last Synced: 2025-09-20T04:09:58.205Z (10 months ago)
- Topics: country, country-codes, iso-3166, iso3166, population, python
- Language: Python
- Homepage: https://pypi.org/project/pypopulation/
- Size: 107 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pypopulation
Lightweight population lookup using [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) alpha-1/2 country codes for **Python 3.6.1** and higher.
```python
>>> import pypopulation
>>>
>>> pypopulation.get_population("DE") # Germany
83132799
```
The aim is to provide a minimalist package with no dependencies that does one thing only, as best as possible. Population figures are read from a JSON file into Python dictionaries at import time. The API then only exposes the dictionaries.
**The given figures are estimates at best.** Read below for more details on the data source.
## Interface
The API is formed by 3 functions:
* `get_population_a2`: population for a 2-letter country code
* `get_population_a3`: population for a 3-letter country code
* `get_population`: population for either a 2-letter or a 3-letter country code
All functions return `None` if no country is found for the given country code. **Lookup is case insensitive**, i.e. `"DE"` and `"de"` give same results.
Lookups using country names are difficult & not currently supported, but the source JSON file does contain them. This is to make the source file more comprehensible. If all you have to work with is a country name, consider using [`pycountry`](https://pypi.org/project/pycountry/) to resolve your names to ISO 3166 codes first.
If you would like to build your own wrapper around the source JSON, you can do:
```python
countries: t.List[t.Dict] = pypopulation._load_file()
```
## Installation
With `pip` from [PyPI](https://pypi.org/):
```
pip install pypopulation
```
## Development
I'm using [`Poetry`](https://python-poetry.org/) to maintain development dependencies. These dependencies are only used to assure code quality. They are not necessary to use the package, and are not installed in a production environment.
Replicate the development environment:
```
poetry install
```
Run lint, tests and produce a `.coverage` file:
```
poetry run flake8
poetry run coverage run -m unittest
```
These commands run in CI (GH Actions) on pull requests against `main`. Tests are ran on all supported Python versions. Refer to the [`Checks`](.github/workflows/checks.yml) workflow for more information. New releases trigger the [`Publish`](.github/workflows/publish.yml) workflow, which builds a distribution and pushes it to PyPI.
## Data source
The population figures were sourced from [The World Bank](https://data.worldbank.org/indicator/SP.POP.TOTL) (`2020-07-01`). This dataset provides the country name, alpha-3 code, and population figures found in the resource JSON file. The data was enriched with alpha-2 country codes for each row. Rows not corresponding to political countries were removed, e.g. "Middle East & North Africa (excluding high income)". Some country names were adjusted for readability, e.g. expanded abbreviations. **No adjustments were made to the population figures**. Please refer to the linked page for a more detailed description of the dataset.
This projects aims to expose the linked data to Python code. It does not guarantee correctness of the provided figures.