Hi everyone,

Today we rolled out two changes to our geocoding API:

First up, as mentioned a few weeks ago, we have modified the stay_informed section of the API response to now additionally include a reference to our Mastodon account, as Mastodon has now become our primary social media channel. Here’s what the JSON now looks like:

"Screenshot of "stay_informed" section of OpenCage geocoding API JSON response"

Second, based on customer feedback we have created a new boolean optional API parameter: address_only. When set (ie address_only=1 we modify the formatted portion of the result to include only address details. This removes POI names (for example restaurants, business names, etc). This is particularly useful when many POIs are at the same location, for example a multi-story building, and the name causes confusion.

Let’s consider an address_only example.

If you reverse geocode the coordinates 51.52335, -0.10036 by default (ie with no ooptional parameters) we will return:

The Sutton Arms, 16 Great Sutton Street, London, EC1V 0DN, United Kingdom

Note that the name of the pub The Sutton Arms is in the formatted value. But, if you add address_only=1 to your request we return

16 Great Sutton Street, London, EC1V 0DN, United Kingdom

as the formatted value. The pub name can however still be found in the components portion of the result. As an aside, The Sutton Arms is a great pub and we often have drinks there after our London Geomob events.

As always, you can read the details of this new, optional parameter in our API documentation.

"Screenshot of OpenCage geocoding API docs for address_only optional parameter"

The creation of the formatted portion of the result is complex given all the different possible permutations (the world is a complicated place). It is worth reading the section of the documentation that explains how we create this part of the geocoding results.

One of the easiest way to see these changes in the actual geocoding API response is via our geocoding demo page where you can test different queries and examine the JSON response.

Both of these changes have been announced on our public Change Log, which is hosted on GitHub. If you are depending on our API we advise you to “watch” that repository so you are notified of changes (though of course we will also announce changes here on the blog and on Mastodon).

Happy geocoding,