GET /v1/location/postalcodes

Postal areas within a country. These are the values a postalCode filter accepts in the boundingLocation of a Location or Geospatial field. An Address field also accepts a postal code filter, but matches only postal codes that have addresses.

Request

Query parameter	Required	Default	Description
country	Yes	none	The country to list postal areas for. See GET /v1/location/countries for the codes. A request without it returns 400.

There is no region parameter. Postal area boundaries do not follow region or sub-region boundaries, so a postal area has no region or sub-region. For the same reason, a postalCode filter cannot be combined with a region or subRegion filter.

curl "https://api.alchemy.example/v1/location/postalcodes?country=us" -H "X-Api-Key: YOUR_API_KEY"

Response

An array of { code, outlineCharacters }, ordered by code:

[
  { "code": "00601", "outlineCharacters": 53000 },
  { "code": "00602", "outlineCharacters": 78000 },
  { "code": "00603", "outlineCharacters": 61000 }
]

The entries above are an example. Call the endpoint for the current list and values.

outlineCharacters is the estimated size, in characters, of the postal area's boundary when the location sub-field is mapped. It determines how many rows fit within the data limit of a request. Most postal areas are small, but a rural postal area can be larger than a region in another country. Check it before mapping location, and see Boundaries.

A country whose postal property is false in GET /v1/location/countries has no postal areas, and a request for it returns 400, not an empty list.

Filtering with these values

A code from this list is used in the postalCode property, or in an entry of the weighted postalCodes list, in a field's boundingLocation. Codes must match exactly. See Matching place names.

Errors

400 with a ProblemDetails body:

Status	When
400	country is missing, or the country has no postal areas.

Requires an API key (see Authentication) but is not billed.