My Geocode

Guides

Look up the postal code for a partial address

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

A customer who leaves the postal code field blank has not necessarily given you bad data. Forward geocoding can usually fill that gap in from the rest of the address.

Sending the partial address

Send whatever text you have, street and city at minimum, to /v1/forward. The components object in the result includes the postal code for the best match, even though the input never mentioned one.

GET /v1/forward?q=1600 Pennsylvania Avenue, Washington&limit=1
{
  "status": "ok",
  "query": "1600 Pennsylvania Avenue, Washington",
  "results": [
    {
      "formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
      "lat": 38.8977,
      "lon": -77.0365,
      "type": "address",
      "precision": "house",
      "confidence": 0.97,
      "place_id": "def456",
      "components": {"postcode": "20500", "city": "Washington", "region": "DC", "country": "US"}
    }
  ]
}

A thinner example, and why it matters

Not every address is this complete. A query with only a city and region, such as "Springfield, Illinois", can still return a result, but the postcode in components will cover the whole city rather than one building, and the precision field will read something coarser than "house". That difference matters if you plan to print the returned postcode on a shipping label rather than just use it for a regional estimate, since a city-level postcode is not the same guarantee as a house-level one.

Trusting the result

Check the precision and confidence fields before treating the returned postal code as reliable. A "house" precision with a high confidence score means the match was specific enough to trust the postcode value directly. A coarser precision, such as a street or city level match, means the postal code covers a wider area and might not match the exact address the customer meant.

Cost of this lookup

This is a single lookup, one request against your daily allowance for one address. Doing this for every checkout or signup form submission that arrives without a postal code is normal usage and will rarely come close to the 2,500 free requests included every day with a key or from a single IP address without one.

When there is no good match

An empty results array, or a result with a low confidence score, means the address was too vague to resolve. In that case, ask the customer directly for the postal code rather than guessing, since a wrong postcode on a shipping label causes more trouble than an empty one.

An edge case worth planning for

Some countries do not use postal codes at all, or use them so inconsistently that a components object simply omits the field for a given result. Do not treat a missing postcode field as an error on its own, check the country in the components object first, and only flag the row for review if the country in question is one where a postal code is normally expected.

Once you have a candidate postal code, a direct call to /v1/postcode with that code and the country from the components object is a fast way to double check it independently, especially useful when the original forward geocoding confidence was borderline rather than clearly high or clearly low.

Filling in a missing postal code this way saves a form field and a round trip with the customer. Full field definitions are in the postal code lookup docs and the forward geocoding docs.

More in Guides