My Geocode

Guides

Combine postcode and country for faster lookups

· 3 min read · My Geocode · #postal-code#performance#forward-geocoding

Forward geocoding is built to handle messy free text, which means it does work behind the scenes to figure out what kind of input it is looking at. If you already know you have a clean postal code and a country, there is a more direct path.

Going straight to the postcode endpoint

Rather than assembling a free-text string and sending it to /v1/forward, send the code and country directly to /v1/postcode.

GET /v1/postcode?code=90210&country=US
{
  "status": "ok",
  "postcode": "90210",
  "country_code": "US",
  "results": [
    {"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
  ]
}

Why this is the better fit

A postal code and country pair is already fully structured input, so there is no ambiguity for the endpoint to resolve the way there can be with a free-text string that might match multiple similarly worded places. Using the endpoint built for exactly this input shape gets you a cleaner match with less risk of an unexpected result.

A second example: an alphanumeric postal code

The same call works the same way for a country using letters and numbers together rather than digits alone.

GET /v1/postcode?code=K1A 0B1&country=CA

Passing the country parameter is what makes this reliable, since a code string alone is not always unique across countries, and the country parameter is what tells the endpoint which postal system to interpret it against.

When you still need forward geocoding

If you need a specific street-level match rather than the general area a postal code covers, forward geocoding with the full address is still the right tool, since a postal code lookup resolves to the area the code covers, not a specific building within it. Use /v1/postcode for area-level lookups such as validating a shipping zone, and /v1/forward when you need house-level precision.

A common mistake to avoid

Do not assume a postal code always maps to exactly one point that represents every address inside it precisely. The coordinates returned by /v1/postcode represent the code's covered area, which can be a single city block or, in some countries, a much larger zone. Treating that returned point as if it were the exact location of a specific customer's building, rather than a representative point for the whole code, will introduce error into anything distance-sensitive built on top of it.

Combining both in a workflow

A common pattern is validating the postal code and country pair first with /v1/postcode, then, once that passes, sending the full street address to /v1/forward to get exact coordinates. That is two requests per submission, one for each stage, rather than trying to force one endpoint to do both jobs.

An edge case: a code that returns no results

An empty results array means the code was not recognized for the country given, which is a different situation from an error response. Treat it the way you would any other unrecognized input, by asking the customer to re-check what they entered, rather than surfacing it as a system error.

What it costs

Each postcode lookup is one request, the same cost as a forward geocoding lookup. Choosing the right endpoint for structured input does not change what it costs, it changes how directly you get to a correct result.

Reaching for the postcode endpoint when you already have clean, structured input avoids the extra ambiguity that comes with reconstructing a free-text string just to parse it back apart again. Full details are on the postal code lookup docs.

More in Guides