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 a specific country (or set of countries) or the bounds parameter to restrict the results to a specific bounding box.

Examples

Let's imagine you send us a forward geocoding request for q=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.
Example: countrycode=fr,be,lu

The bounds parameter limits results to a specific bounding box.
Example: bounds=-0.563160,51.280430,0.278970,51.683979

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, bounds parameter, and other optional parameters.

Happy geocoding!

Start your free trial

2,500 geocoding API requests per day.

No credit card required.