Limit API results to a certain country or region

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.

You can restrict results to only certain countries or a specific region. You can do this by using the countrycode parameter to limit results to a specific country (or set of countries) or the bounds parameter to restrict the results to a specific bounding box.

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, then you can restrict results as follows:

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

• 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
  It's a hard filter: results outside the listed countries are excluded entirely, not just ranked lower.
  Read the full countrycode parameter documentation.
• The bounds parameter limits results to a specific bounding box.
  Example: bounds=-0.563160,51.280430,0.278970,51.683979
  The four numbers are, in order: southwest longitude, southwest latitude, northeast longitude, northeast latitude — i.e. the bottom-left corner of the box, followed by the top-right corner.
  We have built a small, map-based tool to easily visualize bounds values. This is the easiest way to get the coordinate order right without doing it by hand.
  Like countrycode, this is a hard filter, not a soft bias: a result outside the box will not be returned at all, even if it would otherwise have been the best match. If you set the box too tightly and the real match falls just outside it, you'll get zero results rather than a slightly-off one, so err on the side of a slightly larger box.
  Read the full bounds parameter documentation.

If you don't want to hard-exclude results, but just want results near a particular point to rank higher, use the optional proximity parameter instead. Unlike countrycode and bounds, proximity doesn't remove any results, it just re-ranks based on distance to the point you give it.

Read the full proximity parameter documentation.