Geocoding accuracy

The problem

Many places have the same name, so it can be hard to know if our geocoding API returned the place you meant.

Background

Humans are not very good at naming things. We often reuse placenames.

For example there are many places in the United Kingdom named "Waterloo" (all named after a place in Belgium). Similarly, administrative divisions often share names, for example "New York, New York" (New York City in the state of New York).

The end result is that when you send us a placename as a forward geocoding query we will often return more than one relevant result. You will need to determine which result is the one you wanted.

Understanding relevancy and confidence

Our results are returned in order of relevancy - the first result is the one we believe to be most relevant to your query.

Each result has a confidence score, an integer value ranging from 0 to 10. The confidence score has nothing to do with "correctness" or relevancy of the result. Confidence is simply a measure of how large the bounding box of the result is. Please spend one minute reading our definition of confidence in the API reference to understand what the number means.

What did we match?

The way to know what we matched is to look at the _type and/or _category keys in the components section of the result. Please see our detailed explanation in the API reference, including common values of _type and a link to a list of mappings to _category.

Basically, if you know you are searching for a city, then scan through the results and make sure _type is city. Unfortunately though this strategy is not foolproof, places are often classified differently than you might expect. As an example, "Berlin, Germany" is a state not a city.

In some cases a bit of trial and error may be needed, though this will depend on your query set. The way humans have named and subdivided the earth does not always lend itself to simple solutions.

A good strategy to reduce ambiguity is to use the optional bounds, countrycode, and/or proximity parameters. See the optional parameter section in the API reference for a description of each parameter.

Happy geocoding!

Start your free trial

2,500 API requests per day.

No credit card required.