Countries
=========

ISO 3166-1 country and subdivision lookup.

GET /api/v1/countries
---------------------

List or search countries.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``region``
     - query
     - no
     - Filter by region (e.g. ``Europe``, ``Asia``)
   * - ``sub_region``
     - query
     - no
     - Filter by sub-region (e.g. ``Northern Europe``)
   * - ``q``
     - query
     - no
     - Free-text search across country names
   * - ``limit``
     - query
     - no
     - Maximum results to return (default 50)
   * - ``offset``
     - query
     - no
     - Number of results to skip
   * - ``fields``
     - query
     - no
     - Comma-separated list of response fields to include

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/countries?region=Europe&limit=2"

.. code-block:: json

   {
     "count": 44,
     "results": [
       {
         "alpha2": "DE",
         "alpha3": "DEU",
         "numeric": "276",
         "name": "Germany",
         "official_name": "Federal Republic of Germany",
         "region": "Europe",
         "sub_region": "Western Europe",
         "capital": "Berlin"
       },
       {
         "alpha2": "FR",
         "alpha3": "FRA",
         "numeric": "250",
         "name": "France",
         "official_name": "French Republic",
         "region": "Europe",
         "sub_region": "Western Europe",
         "capital": "Paris"
       }
     ]
   }

GET /api/v1/countries/{code}
----------------------------

Get a single country by alpha-2, alpha-3, or numeric code.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``code``
     - path
     - yes
     - Country code (alpha-2, alpha-3, or numeric)
   * - ``fields``
     - query
     - no
     - Comma-separated list of response fields to include

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     https://api.apicrate.io/api/v1/countries/US

.. code-block:: json

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

GET /api/v1/countries/{code}/subdivisions
-----------------------------------------

List subdivisions (states, provinces, regions) for a country.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``code``
     - path
     - yes
     - Country code (alpha-2)
   * - ``type``
     - query
     - no
     - Filter by subdivision type (e.g. ``state``, ``province``)
   * - ``q``
     - query
     - no
     - Free-text search across subdivision names
   * - ``limit``
     - query
     - no
     - Maximum results to return (default 50)
   * - ``offset``
     - query
     - no
     - Number of results to skip

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     "https://api.apicrate.io/api/v1/countries/US/subdivisions?type=state&limit=2"

.. code-block:: json

   {
     "count": 50,
     "results": [
       {"code": "US-CA", "name": "California", "type": "state"},
       {"code": "US-TX", "name": "Texas", "type": "state"}
     ]
   }

GET /api/v1/subdivisions/{code}
-------------------------------

Get a single subdivision by its ISO 3166-2 code.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``code``
     - path
     - yes
     - ISO 3166-2 subdivision code (e.g. ``US-CA``)

**Example**

.. code-block:: bash

   curl -H "X-API-Key: $KEY" \
     https://api.apicrate.io/api/v1/subdivisions/US-CA

.. code-block:: json

   {
     "code": "US-CA",
     "name": "California",
     "type": "state",
     "country": "US",
     "parent": null
   }

POST /api/v1/countries/validate
-------------------------------

Validate a batch of country codes.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``codes``
     - body
     - yes
     - Array of country codes to validate

**Example**

.. code-block:: bash

   curl -X POST https://api.apicrate.io/api/v1/countries/validate \
     -H "X-API-Key: $KEY" \
     -H "Content-Type: application/json" \
     -d '{"codes": ["US", "XX", "DE"]}'

.. code-block:: json

   {
     "results": [
       {"code": "US", "valid": true, "name": "United States of America"},
       {"code": "XX", "valid": false, "name": null},
       {"code": "DE", "valid": true, "name": "Germany"}
     ]
   }

POST /api/v1/subdivisions/validate
-----------------------------------

Validate a batch of subdivision codes.

**Parameters**

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - Name
     - In
     - Required
     - Description
   * - ``codes``
     - body
     - yes
     - Array of ISO 3166-2 subdivision codes to validate

**Example**

.. code-block:: bash

   curl -X POST https://api.apicrate.io/api/v1/subdivisions/validate \
     -H "X-API-Key: $KEY" \
     -H "Content-Type: application/json" \
     -d '{"codes": ["US-CA", "US-ZZ", "DE-BY"]}'

.. code-block:: json

   {
     "results": [
       {"code": "US-CA", "valid": true, "name": "California"},
       {"code": "US-ZZ", "valid": false, "name": null},
       {"code": "DE-BY", "valid": true, "name": "Bavaria"}
     ]
   }