Postal Codes¶

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

GET /api/v1/postal¶

List postal code systems by country.

Parameters

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

curl -H "X-API-Key: $KEY" \
  "https://api.apicrate.io/api/v1/postal?has_system=true&limit=2"

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

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

Example

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"}
    ]
  }'

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

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

Example

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

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

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

curl -H "X-API-Key: $KEY" \
  "https://api.apicrate.io/api/v1/postal/NL/codes?limit=3"

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

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

curl -H "X-API-Key: $KEY" \
  "https://api.apicrate.io/api/v1/postal/US/search?q=Beverly+Hills"

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

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

Example

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]]]
    }
  }'

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

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

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}'

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

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

Example

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

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

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

Look up a specific postal code.

Parameters

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

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

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