Postal Codes ============ Look up, validate, and search postal codes across 124+ countries. Includes spatial queries for finding nearby codes by GPS coordinates. .. contents:: Tools on this page :local: :depth: 1 apicrate-lookup-postal-code --------------------------- Look up a single postal code in a given country, returning place name, administrative region, and coordinates. **Credit cost:** 2 credits per call. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``country_code`` - str - Yes - ISO 3166-1 alpha-2 country code (e.g. ``DE``, ``US``). * - ``postal_code`` - str - Yes - The postal code to look up (e.g. ``10115``). Example ^^^^^^^ Request: .. code-block:: json { "name": "apicrate-lookup-postal-code", "arguments": { "country_code": "DE", "postal_code": "10115" } } Response: .. code-block:: json { "country_code": "DE", "postal_code": "10115", "place_name": "Berlin Mitte", "admin_name1": "Berlin", "admin_code1": "BE", "latitude": 52.532, "longitude": 13.3886 } Errors ^^^^^^ - **Country not found** -- the ``country_code`` does not match any supported country. - **Postal code not found** -- no entry exists for the given code in that country. apicrate-validate-postal-code ----------------------------- Check whether a postal code is valid for a given country. Returns format validity (regex match) and whether the code exists in the database. **Credit cost:** 1 credit per call. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``country_code`` - str - Yes - ISO 3166-1 alpha-2 country code. * - ``postal_code`` - str - Yes - The postal code to validate. Example ^^^^^^^ Valid code -- request: .. code-block:: json { "name": "apicrate-validate-postal-code", "arguments": { "country_code": "US", "postal_code": "10001" } } Response: .. code-block:: json { "country_code": "US", "postal_code": "10001", "format_valid": true, "exists": true } Invalid code -- request: .. code-block:: json { "name": "apicrate-validate-postal-code", "arguments": { "country_code": "US", "postal_code": "ABCDE" } } Response: .. code-block:: json { "country_code": "US", "postal_code": "ABCDE", "format_valid": false, "exists": false } Errors ^^^^^^ - **Country not found** -- the ``country_code`` does not match any supported country. apicrate-search-postal-codes ----------------------------- Search postal codes within a country by place name or code prefix. **Credit cost:** 3 credits per call. Returns up to 50 results. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``country_code`` - str - Yes - ISO 3166-1 alpha-2 country code. * - ``query`` - str - No - Free-text search against place names (e.g. ``Berlin``). * - ``prefix`` - str - No - Postal code prefix to match (e.g. ``101``). Example ^^^^^^^ Request: .. code-block:: json { "name": "apicrate-search-postal-codes", "arguments": { "country_code": "DE", "query": "Berlin" } } Response: .. code-block:: json { "country_code": "DE", "count": 3, "results": [ { "postal_code": "10115", "place_name": "Berlin Mitte", "latitude": 52.532, "longitude": 13.3886 }, { "postal_code": "10117", "place_name": "Berlin Mitte", "latitude": 52.5225, "longitude": 13.3881 }, { "postal_code": "10119", "place_name": "Berlin Prenzlauer Berg", "latitude": 52.5327, "longitude": 13.4108 } ] } Errors ^^^^^^ - **Country not found** -- the ``country_code`` does not match any supported country. apicrate-list-postal-systems ----------------------------- List all supported postal systems (countries) with their code formats. Use the optional ``query`` parameter to filter by country name. **Credit cost:** 2 credits per call. Returns up to 250 results. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``query`` - str - No - Filter countries by name (e.g. ``Germany``). Omit to list all. Example ^^^^^^^ Unfiltered request: .. code-block:: json { "name": "apicrate-list-postal-systems", "arguments": {} } Filtered request: .. code-block:: json { "name": "apicrate-list-postal-systems", "arguments": { "query": "Germany" } } Response (filtered): .. code-block:: json { "count": 1, "results": [ { "country_code": "DE", "country_name": "Germany", "format": "#####", "regex": "^\\d{5}$" } ] } Errors ^^^^^^ No tool-specific errors. An empty ``results`` list is returned when the query matches nothing. apicrate-get-postal-system -------------------------- Get detailed information about a single country's postal system, including the code format, validation regex, and example codes. **Credit cost:** 2 credits per call. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``country_code`` - str - Yes - ISO 3166-1 alpha-2 country code. Example ^^^^^^^ Request: .. code-block:: json { "name": "apicrate-get-postal-system", "arguments": { "country_code": "DE" } } Response: .. code-block:: json { "country_code": "DE", "country_name": "Germany", "format": "#####", "regex": "^\\d{5}$", "examples": ["10115", "20095", "80331"] } Errors ^^^^^^ - **Country not found** -- the ``country_code`` does not match any supported country. apicrate-validate-postal-codes-bulk ------------------------------------ Validate multiple postal codes in a single call. Each item specifies its own country code, so you can mix countries freely. **Credit cost:** 2 credits per code. A request with 10 codes costs 20 credits. Maximum 50 codes per call. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``codes`` - list[dict] - Yes - List of objects, each with ``country_code`` (str) and ``postal_code`` (str). Maximum 50 items. Example ^^^^^^^ Request: .. code-block:: json { "name": "apicrate-validate-postal-codes-bulk", "arguments": { "codes": [ {"country_code": "US", "postal_code": "10001"}, {"country_code": "DE", "postal_code": "10115"} ] } } Response: .. code-block:: json { "count": 2, "results": [ { "country_code": "US", "postal_code": "10001", "format_valid": true, "exists": true }, { "country_code": "DE", "postal_code": "10115", "format_valid": true, "exists": true } ] } Errors ^^^^^^ - **Empty list** -- ``codes`` must contain at least one item. - **Over 50 limit** -- no more than 50 codes per request. - **Missing keys** -- each item must include both ``country_code`` and ``postal_code``. apicrate-find-nearby-postal-codes --------------------------------- Find postal codes near a GPS coordinate within a given radius. Results are sorted by distance (nearest first). **Credit cost:** 5 credits per call. Returns up to 100 results. Parameters ^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - Parameter - Type - Required - Description * - ``country_code`` - str - Yes - ISO 3166-1 alpha-2 country code. * - ``lat`` - float - Yes - Latitude of the search center. Range: ``-90`` to ``90``. * - ``lng`` - float - Yes - Longitude of the search center. Range: ``-180`` to ``180``. * - ``radius_km`` - float - Yes - Search radius in kilometres. Must be greater than ``0`` and at most ``500``. Example ^^^^^^^ Request: .. code-block:: json { "name": "apicrate-find-nearby-postal-codes", "arguments": { "country_code": "DE", "lat": 52.52, "lng": 13.405, "radius_km": 5 } } Response: .. code-block:: json { "country_code": "DE", "center": {"lat": 52.52, "lng": 13.405}, "radius_km": 5, "count": 3, "results": [ { "postal_code": "10117", "place_name": "Berlin Mitte", "latitude": 52.5225, "longitude": 13.3881, "distance_km": 1.14 }, { "postal_code": "10115", "place_name": "Berlin Mitte", "latitude": 52.532, "longitude": 13.3886, "distance_km": 1.52 }, { "postal_code": "10119", "place_name": "Berlin Prenzlauer Berg", "latitude": 52.5327, "longitude": 13.4108, "distance_km": 1.47 } ] } Errors ^^^^^^ - **Country not found** -- the ``country_code`` does not match any supported country. - **Invalid latitude** -- ``lat`` must be between ``-90`` and ``90``. - **Invalid longitude** -- ``lng`` must be between ``-180`` and ``180``. - **Invalid radius** -- ``radius_km`` must be greater than ``0`` and at most ``500``.