Many places have the same name, so it can be hard to know if our geocoding
API returned the place you meant.
Humans are not very good at naming things. We often reuse placenames.
For example there are many places in the United Kingdom named
(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
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
keys in the
section of the result.
Please see our detailed explanation
in the API reference,
including common values of
and a link to a list of mappings to
Basically, if you know you are searching for a city, then scan
through the results and make sure
Unfortunately though this strategy is not foolproof, places are often
classified differently than you might expect. As an example,
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
parameters. See the
optional parameter section in the API reference
for a description of each parameter.