Postal Codes¶

Look up, validate, and search postal codes across 124+ countries. Includes spatial queries for finding nearby codes by GPS coordinates.

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¶

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:

{
  "name": "apicrate-lookup-postal-code",
  "arguments": {
    "country_code": "DE",
    "postal_code": "10115"
  }
}

Response:

{
  "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¶

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:

{
  "name": "apicrate-validate-postal-code",
  "arguments": {
    "country_code": "US",
    "postal_code": "10001"
  }
}

Response:

{
  "country_code": "US",
  "postal_code": "10001",
  "format_valid": true,
  "exists": true
}

Invalid code – request:

{
  "name": "apicrate-validate-postal-code",
  "arguments": {
    "country_code": "US",
    "postal_code": "ABCDE"
  }
}

Response:

{
  "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¶

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:

{
  "name": "apicrate-search-postal-codes",
  "arguments": {
    "country_code": "DE",
    "query": "Berlin"
  }
}

Response:

{
  "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¶

Parameter	Type	Required	Description
`query`	str	No	Filter countries by name (e.g. `Germany`). Omit to list all.

Example¶

Unfiltered request:

{
  "name": "apicrate-list-postal-systems",
  "arguments": {}
}

Filtered request:

{
  "name": "apicrate-list-postal-systems",
  "arguments": {
    "query": "Germany"
  }
}

Response (filtered):

{
  "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¶

Parameter	Type	Required	Description
`country_code`	str	Yes	ISO 3166-1 alpha-2 country code.

Example¶

Request:

{
  "name": "apicrate-get-postal-system",
  "arguments": {
    "country_code": "DE"
  }
}

Response:

{
  "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¶

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:

{
  "name": "apicrate-validate-postal-codes-bulk",
  "arguments": {
    "codes": [
      {"country_code": "US", "postal_code": "10001"},
      {"country_code": "DE", "postal_code": "10115"}
    ]
  }
}

Response:

{
  "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¶

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:

{
  "name": "apicrate-find-nearby-postal-codes",
  "arguments": {
    "country_code": "DE",
    "lat": 52.52,
    "lng": 13.405,
    "radius_km": 5
  }
}

Response:

{
  "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.

Postal Codes¶

apicrate-lookup-postal-code¶

Parameters¶

Example¶

Errors¶

apicrate-validate-postal-code¶

Parameters¶

Example¶

Errors¶

apicrate-search-postal-codes¶

Parameters¶

Example¶

Errors¶

apicrate-list-postal-systems¶

Parameters¶

Example¶

Errors¶

apicrate-get-postal-system¶

Parameters¶

Example¶

Errors¶

apicrate-validate-postal-codes-bulk¶

Parameters¶

Example¶

Errors¶

apicrate-find-nearby-postal-codes¶

Parameters¶

Example¶

Errors¶

apicrate-lookup-postal-code ¶

apicrate-validate-postal-code ¶

apicrate-search-postal-codes ¶

apicrate-list-postal-systems ¶

apicrate-get-postal-system ¶

apicrate-validate-postal-codes-bulk ¶

apicrate-find-nearby-postal-codes ¶