Mundi is a simple package that provides information about all countries in the world as as a convenient set of classes and Pandas dataframes. It uses information provided by the popular pycountry package and supplement it with several other data sources using plugins.
Mundi is still in an early stage of development and thus is changing very quickly. New users should expect some risks in terms of API changes and general breakage. We suggest that if you want to take that risk, install it from git and keep in touch with the developers (and better yet, contribute to the project).
Install Mundi using pip install mundi or your method of choice. Now, you can just import
it and load the desired information. Mundi exposes collections of entries as dataframes,
and single entries (rows in those dataframes) as Series objects.
>>> import mundi
>>> df = mundi.countries(); df # DOCTEST: +ELLIPSIS
name
id
AD Andorra
AE United Arab Emirates
AF Afghanistan
AG Antigua and Barbuda
AI Anguilla
...The mundi.countries() function is just an alias to mundi.regions(type="country").
The more generic mundi.region() function may be used to query countries and
subdivisions inside a country.
>>> br_states = mundi.regions(country="BR", type="state"); br_states # DOCTEST: +ELLIPSIS
name
id
BR-AC Acre
BR-AL Alagoas
BR-AM Amazonas
BR-AP Amapá
BR-BA Bahia
...If you want a single country or single region, use the mundi.region() function,
which returns a Region object, that in many ways behave like a row of a dataframe.
>>> br = mundi.region("BR"); br
Region("BR", name="Brazil")The library creates a custom .mundi accessor that exposes additional
methods not present in regular data frames. The most important of those is
the ability to extend the data frame with additional columns available from Mundi
itself or from plugins.
>>> extra = df.mundi[["region", "income_group"]]; extra # DOCTEST: +ELLIPSIS
region income_group
id
AD europe high
AE middle-east high
AF south-asia low
AG latin-america high
AI NaN NaN
...Each region also exhibit those values as attributes
>>> br.region
'latin-america'
>>> br.income_group
'upper-middle'It is also possible to keep the columns of the original dataframe using the ellipsis syntax
>>> df = df.mundi[..., "region", "income_group"]; df # DOCTEST: +ELLIPSIS
name region income_group
id
AD Andorra europe high
AE United Arab Emirates middle-east high
AF Afghanistan south-asia low
AG Antigua and Barbuda latin-america high
AI Anguilla NaN NaN
...The .mundi accessor is also able to select countries over mundi columns,
even if those columns are not in the original dataframe.
>>> countries = mundi.countries()
>>> countries.mundi.filter(income_group="upper-middle") # DOCTEST: +ELLIPSIS
name
id
AD Andorra
AE United Arab Emirates
AG Antigua and Barbuda
AT Austria
AU Australia
...The basic data in the mundi package is centered around a table describing many world regions with the following structure:
| Column | Description |
|---|---|
| id (index) | Dataframe indexes are strings and correspond to the ISO code of a region, when available. |
| name | Region name in English |
| type | Type of region. There are too many types to list here, but it will be something like "country", "state", "municipality", etc. |
| subtype | A sub-division of the given type (e.g. a state can also be a "federal district") |
| short_code | Short code for region. Those are unique in the same country, but may repeat elsewhere. For Countries, this is the ISO alpha-2 code. |
| long_code | Alternative long version of the code. For countries, this is the ISO alpha-3 code. Other sub-regions may optionally leave this column empty. |
| numeric_code | Numeric code for region, when it exists. ISO assign a numeric code to each country and the official geographical bureau of each country frequently works with numerical codes too. Mundi will try to use those codes whenever possible, or will leave this column empty when no numerical convention is available. |
| country_code | Country code for the selected region. If region is a country, this column is empty. |
| parent_id | The id string for the parent element. Countries are considered to be root elements and therefore do not fill this column. The parent might be an intermediate region between the current row and the corresponding country. A city, for instance, may have a parent state, which have a parent country. |
| alt_parents | List of ids separated by semi-colons with alternative parents that do not belong to the main hierarchy. |
| income_group | Country classification according to UN's income groups. |
| region | Region of the globe according to UN's classification. |