Guides

Normalize messy address input before geocoding it

Free text address fields collect a wide range of formatting habits, extra whitespace, inconsistent capitalization, abbreviations spelled out inconsistently, and the occasional stray character pasted in from somewhere else. None of that necessarily breaks a geocoding request, but cleaning it up first tends to improve match quality.

What to clean up before sending

Trim leading and trailing whitespace and collapse repeated spaces into one. Strip control characters and stray punctuation that clearly does not belong in an address. Leave actual address content alone, since the forward endpoint is designed to parse free text and does not need you to split it into separate street, city, and postal code fields yourself.

GET /v1/forward?q=221b   baker st,  london&limit=1

The endpoint will still generally resolve loosely formatted input like this, since it is built to handle real-world address text rather than a rigid template, but a cleaner input string reduces the odds of an ambiguous or low-confidence match on genuinely messy data.

A second example: abbreviations left as-is

A query using common abbreviations, such as "St" for "Street" or "Ave" for "Avenue", does not need to be expanded before sending.

GET /v1/forward?q=500 5th Ave, New York&limit=1

Expanding every abbreviation yourself before sending the request is extra work that rarely changes the outcome, since the endpoint already handles standard abbreviations as part of parsing ordinary address text. Focus your cleanup effort on genuinely broken input, such as pasted-in line breaks or encoding artifacts, rather than rewriting abbreviations that were never a problem.

Using the countries parameter to narrow results

If you already know which country an address should be in, from a billing address on file or a site's regional focus, pass it with the countries parameter to cut down on ambiguous matches to similarly named places elsewhere in the world.

GET /v1/forward?q=Springfield Main Street&countries=US&limit=3

A mistake worth avoiding

Over-cleaning an address by stripping anything that looks unusual can remove information the geocoder actually needed. A unit or apartment number, a floor indicator, or a building name attached to a street address is meaningful content, not noise, even though it looks unlike the rest of the address. Limit your cleanup to whitespace, encoding, and clearly stray characters, and leave anything that could plausibly be part of the address alone.

Checking confidence after the fact

Normalization reduces bad matches, it does not eliminate them entirely. Always check the confidence field on the result rather than assuming a returned result is automatically correct just because the request succeeded.

Request cost stays the same

Cleaning the input string before sending it does not change how many requests the lookup costs, it is still one request per address. What it changes is the odds that the one request you send returns something useful, rather than needing a second, corrected attempt that would cost a second request.

Getting normalization right up front means fewer wasted lookups and cleaner data downstream. See the forward geocoding docs for the full set of supported parameters, including countries and limit.