Postal Codes
============

Postal code lookup, search, validation, and spatial queries across 124+
countries.

GET /api/v1/postal
------------------

List postal code systems by country.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``has_system``
     - query
     - no
     - Filter to countries that have (``true``) or lack (``false``) a postal system
   * - ``format_like``
     - query
     - no
     - Filter by format pattern (e.g. ``#####``, ``ANA NAN``)
   * - ``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/postal?has_system=true&limit=2"

.. code-block:: json

   {
     "count": 124,
     "results": [
       {
         "country_code": "US",
         "country_name": "United States",
         "format": "#####",
         "regex": "^\\d{5}$"
       },
       {
         "country_code": "GB",
         "country_name": "United Kingdom",
         "format": "A9 9AA / A99 9AA / A9A 9AA",
         "regex": "^[A-Z]{1,2}\\d[A-Z\\d]? \\d[A-Z]{2}$"
       }
     ]
   }

POST /api/v1/postal/validate
-----------------------------

Validate a batch of postal codes across different countries.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``codes``
     - body
     - yes
     - Array of objects, each with ``country_code`` and ``postal_code``

**Example**

.. code-block:: bash

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

.. code-block:: json

   {
     "results": [
       {"country_code": "US", "postal_code": "90210", "valid": true},
       {"country_code": "US", "postal_code": "ABCDE", "valid": false}
     ]
   }

GET /api/v1/postal/{country_code}
---------------------------------

Get the postal code system for a specific country.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code

**Example**

.. code-block:: bash

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

.. code-block:: json

   {
     "country_code": "US",
     "country_name": "United States",
     "format": "#####",
     "regex": "^\\d{5}$",
     "total_codes": 41483
   }

GET /api/v1/postal/{country_code}/codes
----------------------------------------

List all postal codes for a country.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code
   * - ``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/postal/NL/codes?limit=3"

.. code-block:: json

   {
     "count": 4642,
     "results": [
       {"postal_code": "1000", "place_name": "Amsterdam", "admin_name": "Noord-Holland"},
       {"postal_code": "1001", "place_name": "Amsterdam", "admin_name": "Noord-Holland"},
       {"postal_code": "1002", "place_name": "Amsterdam", "admin_name": "Noord-Holland"}
     ]
   }

GET /api/v1/postal/{country_code}/search
-----------------------------------------

Search postal codes by name, prefix, or admin area.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code
   * - ``q``
     - query
     - no
     - Free-text search across place names
   * - ``prefix``
     - query
     - no
     - Postal code prefix to match
   * - ``admin_code``
     - query
     - no
     - Filter by admin division code
   * - ``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/postal/US/search?q=Beverly+Hills"

.. code-block:: json

   {
     "count": 1,
     "results": [
       {
         "postal_code": "90210",
         "place_name": "Beverly Hills",
         "admin_name": "California",
         "latitude": 34.0901,
         "longitude": -118.4065
       }
     ]
   }

POST /api/v1/postal/{country_code}/within
------------------------------------------

Find postal codes within a GeoJSON polygon.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code
   * - ``geometry``
     - body
     - yes
     - GeoJSON Polygon geometry

**Example**

.. code-block:: bash

   curl -X POST https://api.apicrate.io/api/v1/postal/US/within \
     -H "X-API-Key: $KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "geometry": {
         "type": "Polygon",
         "coordinates": [[[-118.5, 34.0], [-118.4, 34.0], [-118.4, 34.1], [-118.5, 34.1], [-118.5, 34.0]]]
       }
     }'

.. code-block:: json

   {
     "count": 12,
     "results": [
       {"postal_code": "90210", "place_name": "Beverly Hills", "latitude": 34.0901, "longitude": -118.4065},
       {"postal_code": "90211", "place_name": "Beverly Hills", "latitude": 34.0652, "longitude": -118.3832}
     ]
   }

POST /api/v1/postal/{country_code}/nearby
------------------------------------------

Find postal codes near a geographic point.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code
   * - ``lat``
     - body
     - yes
     - Latitude of the center point
   * - ``lng``
     - body
     - yes
     - Longitude of the center point
   * - ``radius_km``
     - body
     - yes
     - Search radius in kilometers

**Example**

.. code-block:: bash

   curl -X POST https://api.apicrate.io/api/v1/postal/US/nearby \
     -H "X-API-Key: $KEY" \
     -H "Content-Type: application/json" \
     -d '{"lat": 34.0522, "lng": -118.2437, "radius_km": 5}'

.. code-block:: json

   {
     "count": 24,
     "results": [
       {"postal_code": "90012", "place_name": "Los Angeles", "distance_km": 0.8},
       {"postal_code": "90013", "place_name": "Los Angeles", "distance_km": 1.2}
     ]
   }

GET /api/v1/postal/{country_code}/validate/{postal_code}
---------------------------------------------------------

Quick-validate a single postal code for a country.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code
   * - ``postal_code``
     - path
     - yes
     - Postal code to validate

**Example**

.. code-block:: bash

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

.. code-block:: json

   {
     "country_code": "US",
     "postal_code": "90210",
     "valid": true
   }

GET /api/v1/postal/{country_code}/{postal_code}
------------------------------------------------

Look up a specific postal code.

**Parameters**

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

   * - Name
     - In
     - Required
     - Description
   * - ``country_code``
     - path
     - yes
     - ISO 3166-1 alpha-2 country code
   * - ``postal_code``
     - path
     - yes
     - Postal code to look up
   * - ``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/postal/US/90210

.. code-block:: json

   {
     "postal_code": "90210",
     "country_code": "US",
     "place_name": "Beverly Hills",
     "admin_name": "California",
     "admin_code": "CA",
     "latitude": 34.0901,
     "longitude": -118.4065
   }