The problemMany places have the same name, so it can be hard to know if our geocoding API returned the place you meant.
BackgroundHumans 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 confidenceOur 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
confidencescore, 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
_categorykeys in the
componentssection of the result. Please see our detailed explanation in the API reference, including common values of
_typeand 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
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
proximityparameters. See the optional parameter section in the API reference for a description of each parameter.