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.