Limit API results to a certain country or region

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.

Happy geocoding!

Start your free trial

2,500 API requests per day.

No credit card required.