Countries
=========

Look up, search, and validate ISO 3166-1 country codes. Covers all UN member
states with names, regions, currencies, and subdivisions.

.. contents:: Tools on this page
   :local:
   :depth: 1


apicrate-lookup-country
-----------------------

Look up a single country by its ISO 3166-1 code. Accepts alpha-2, alpha-3, or
numeric codes.

**Credit cost:** 1 credit per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``code``
     - str
     - Yes
     - ISO 3166-1 code: alpha-2 (``US``), alpha-3 (``USA``), or numeric
       (``840``).

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-lookup-country",
     "arguments": {
       "code": "US"
     }
   }

Response:

.. code-block:: json

   {
     "alpha2": "US",
     "alpha3": "USA",
     "numeric": "840",
     "name": "United States",
     "official_name": "United States of America",
     "region": "Americas",
     "sub_region": "Northern America",
     "capital": "Washington, D.C.",
     "currencies": ["USD"],
     "languages": ["en"],
     "calling_codes": ["+1"]
   }

Errors
^^^^^^

- **Country not found** -- the ``code`` does not match any ISO 3166-1 alpha-2,
  alpha-3, or numeric code.


apicrate-search-countries
-------------------------

Search and filter countries by region, sub-region, or free-text name query.

**Credit cost:** 3 credits per call. Returns up to 250 results.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``region``
     - str
     - No
     - Filter by region (e.g. ``Europe``, ``Americas``, ``Asia``).
   * - ``sub_region``
     - str
     - No
     - Filter by sub-region (e.g. ``Northern America``, ``Western Europe``).
   * - ``query``
     - str
     - No
     - Free-text search against country names (e.g. ``united``).

Example
^^^^^^^

Filter by region -- request:

.. code-block:: json

   {
     "name": "apicrate-search-countries",
     "arguments": {
       "region": "Europe"
     }
   }

Response (truncated):

.. code-block:: json

   {
     "count": 44,
     "results": [
       {
         "alpha2": "DE",
         "name": "Germany",
         "region": "Europe",
         "sub_region": "Western Europe"
       },
       {
         "alpha2": "FR",
         "name": "France",
         "region": "Europe",
         "sub_region": "Western Europe"
       },
       {
         "alpha2": "PL",
         "name": "Poland",
         "region": "Europe",
         "sub_region": "Eastern Europe"
       }
     ]
   }

Search by name -- request:

.. code-block:: json

   {
     "name": "apicrate-search-countries",
     "arguments": {
       "query": "united"
     }
   }

Response:

.. code-block:: json

   {
     "count": 3,
     "results": [
       {
         "alpha2": "AE",
         "name": "United Arab Emirates",
         "region": "Asia",
         "sub_region": "Western Asia"
       },
       {
         "alpha2": "GB",
         "name": "United Kingdom",
         "region": "Europe",
         "sub_region": "Northern Europe"
       },
       {
         "alpha2": "US",
         "name": "United States",
         "region": "Americas",
         "sub_region": "Northern America"
       }
     ]
   }

Errors
^^^^^^

No tool-specific errors. An empty ``results`` list is returned when no
countries match the filters.


apicrate-validate-country-codes
-------------------------------

Validate one or more country codes in a single call. Each code is checked
against all ISO 3166-1 formats (alpha-2, alpha-3, numeric).

**Credit cost:** 1 credit per code. A request with 5 codes costs 5 credits.
Maximum 50 codes per call.

Parameters
^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 10 10 60

   * - Parameter
     - Type
     - Required
     - Description
   * - ``codes``
     - list[str]
     - Yes
     - List of codes to validate. Maximum 50 items. Each code is matched
       against alpha-2, alpha-3, and numeric formats.

Example
^^^^^^^

Request:

.. code-block:: json

   {
     "name": "apicrate-validate-country-codes",
     "arguments": {
       "codes": ["US", "DEU", "ZZZ"]
     }
   }

Response:

.. code-block:: json

   {
     "count": 3,
     "results": [
       {
         "code": "US",
         "valid": true,
         "alpha2": "US",
         "name": "United States"
       },
       {
         "code": "DEU",
         "valid": true,
         "alpha2": "DE",
         "name": "Germany"
       },
       {
         "code": "ZZZ",
         "valid": false,
         "alpha2": null,
         "name": null
       }
     ]
   }

Errors
^^^^^^

- **Empty list** -- ``codes`` must contain at least one item.
- **Over 50 limit** -- no more than 50 codes per request.