API Reference

This section provides a detailed overview of the available methods and their usage in pyworldatlas. Each method is designed to retrieve specific data about countries, with simple and intuitive interfaces.

Note

Throughout the examples, we will assume pyworldatlas has been imported as pwa.

import pyworldatlas as pwa
atlas = pwa.Atlas()

Classes and Methods

Atlas Class

The Atlas class is the main interface for accessing country data. It provides several methods to retrieve specific country profiles, lists of countries, and other data.

get_country_profile

Fetches detailed profile information for a specific country.

Parameters: - name (str) – The name or ISO 3166 Alpha-2 code of the country.

Returns: - dict – A dictionary containing detailed information about the country’s official names, capital, largest city, area, population, government, and more.

Example:

profile = atlas.get_country_profile("Algeria")
print(profile)

Example Output:

{
    "capital": {
        "name": "Algiers",
        "coordinates_degree_east": 3.13,
        "coordinates_degree_north": 36.42,
        "is_largest_city": True
    },
    "area": {
        "total_km2_including_disputed_territories": None,
        "total_km2_internationally_recognized": 2381741.0,
        "water_percentage": 1.1
    },
    "driving_side": "Right",
    "calling_code": "+213",
    "iso_3166_code": "DZ",
    "internet_tld": ".dz",
    "population": {
        "total": 44700000,
        "density_km2": 17.7,
        "date_year": 2021
    },
    "gini_index": {
        "value": 27.6,
        "year": 2011
    },
    "gdp": {
        "ppp_trillions": 0.684649,
        "ppp_per_capita": "15,765",
        "nominal_total_trillions": 0.183687,
        "nominal_per_capita": "4,229",
        "ppp_gdp_year": 2019,
        "nominal_gdp_year": 2019
    },
    "government": {
        "president": "Abdelmadjid Tebboune",
        "prime_minister": "Nadir Larbaoui",
        "declaration_of_state_sovereignty": "1962-07-05",
        "other_leader_title": None,
        "other_leader": None,
        "government_type": "Unitary semi-presidential constitutional republic",
        "president_assumed_office": "2019-12-19",
        "prime_minister_assumed_office": None,
        "other_leader_assumed_office": None
    },
    "official_names": {
        "English": "People's Democratic Republic of Algeria",
        "Arabic": "الجمهورية الجزائرية الديمقراطية الشعبية",
        "French": "République algérienne démocratique et populaire",
        "Berber": "ⵜⴰⴳⴷⵓⴷⴰ ⵜⴰⵎⴳⴷⴰⵢⵜ ⵜⴰⵖⵔⴼⴰⵏⵜ ⵜⴰⴷⵣⴰⵢⵔⵉⵢⵜ"
    },
    "anthem": {
        "English": "We Pledge"
    },
    "motto": {
        "Arabic": "بالشّعب وللشّعب",
        "English": "By the people and for the people"
    },
    "religion": {
        "Islam": 99.0,
        "Others": 1.0
    },
    "ethnic_groups": {
        "Arab-Berber": 99.0,
        "Others": 1.0
    },
    "languages": {
        "official_languages": ["Arabic", "Berber"],
        "recognized_languages": ["French", "Algerian Arabic (Darja)", "Kabyle"]
    },
    "currency": {
        "name": "Dinar",
        "symbol": "دج",
        "iso_code": "DA"
    },
    "continent": ["Africa"],
    "timezones": {
        "UTC+1": {
            "DST": 0
        }
    }
}

get_countries (WIP)

Fetches a list of countries, optionally filtered by continents or population/GDP ranges.

Parameters:

continents (list of str, optional) – The continents to filter by (e.g., ["Asia", "Europe"]).
min_population (float, optional) – The minimum population to filter by.
max_population (float, optional) – The maximum population to filter by.
min_gdp (float, optional) – The minimum GDP to filter by.
max_gdp (float, optional) – The maximum GDP to filter by.

Returns:

list of str – A list of country names that match the criteria.

Example:

countries = atlas.get_countries(continents=["Europe"], min_population=1000000)
print(countries)

Example Output:

['France', 'Germany', 'Italy', 'Spain']

get_progress

Returns the percentage of data that the package currently contains.

Returns: - float – The percentage of the dataset that is complete.

Example:

progress = atlas.get_progress()

Example Output:

"Current data size: 3, Total data size: 285, Progress: 1.1%"

Error Handling

pyworldatlas provides custom exceptions to help identify and handle errors efficiently.

CountryNotFoundError

Raised when a country is not found in the dataset.

Example:

try:
    profile = atlas.get_country_profile("Nonexistentland")
except pwa.Atlas.CountryNotFoundError:
    print("Country not found.")

Additional Features

pyworldatlas is continually evolving. Refer to the Roadmap for upcoming features and improvements.