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`.

.. code-block:: python

   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**:

.. code-block:: python

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

**Example Output**:

.. code-block:: python

    {
        "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**:

.. code-block:: python

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

**Example Output**:

.. code-block:: python

    ['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**:

.. code-block:: python

   progress = atlas.get_progress()

**Example Output**:

.. code-block:: python

    "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**:

.. code-block:: python

   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 <roadmap.html>`_ for upcoming features and improvements.