The problem
Too many places in the world share the same name. As a result
you get back too many results, and it's hard too know which result
is the one you want.
The solution
You can to
restrict results to only certain countries or a specific region.
You can do this by using the
countrycode
parameter too limit results to acountry (or set of countries)
or the
bounds
parameter
to restrict the results to a specific bounding box.
Example
Let's imagine you send us a forward geocoding request for "London".
We can't know if you mean "London, England" or "London, Ontario, Canada", or
one of the many other places in the world named London, so we return all
of them. But if you know you only want the place in Canada
Instead of
https://api.opencagedata.com/geocode/v1/json?q=London&pretty=1&key=YOUR-API-KEY
do
https://api.opencagedata.com/geocode/v1/json?countrycode=ca&q=London&pretty=1&key=YOUR-API-KEY
or
https://api.opencagedata.com/geocode/v1/json?bounds=-84.26514,41.58998,-77.54150,46.14246&q=London&pretty=1&key=YOUR-API-KEY
Explanation and relevant documentation
The
countrycode
parameter restricts results to a specific country
or set of countries, you can set a comma separated list of countrycodes
The
bounds
parameter limits results to a specific bounding box.
We have built
a small, map-based tool
to easily visualize bounds values.
In the
OpenCage API Reference
you can find all the details of the optional
countrycode parameter
and
bounds parameter.