02/04/2019

The what3words API is an easy way to enable a website or mobile app to display or accept 3 word addresses. To make it easier to integrate, we’ve been working hard on a new, upgraded version. We’ve built a simpler interface and added powerful new features to ensure a better user experience and accurate 3 word address entry.

With the release of what3words API v3 it’s now easier than ever to create an API key and start making calls to our API to see what it can do.

Get started now

What’s new?

1. GPS coordinates ←→ 3 word address

We previously referred to the process of converting GPS coordinates to a 3 word address as reverse geocoding and converting a 3 word address to GPS coordinates as forward geocoding. While this may be intuitive to those with an understanding of geocoding, we’ve changed this terminology so that our API functions are clear to all developers.

Old TerminologyNew Terminology
Forward geocodingConvert-to-coordinates
Reverse geocodingConvert-to-3wa

Previously, what3words API simply returned GPS coordinates during a ‘convert-to-coordinates’ API call. Now, apps, websites and platforms can offer more location context users. what3words API v3 incorporates the country code and region of a 3 word address into its response.

2. Simplified and enhanced AutoSuggest

what3words AutoSuggest prompts users with intelligent 3 word address suggestions for a full or partial 3 word address search input.

In what3words API v2, we had different endpoints – one for AutoSuggest, voice AutoSuggest and StandardBlend.

For the what3words API v3, we merged these three endpoints into one AutoSuggest function, which now has the cumulative functionality of all three.

Old EndpointNew Endpoints
AutosuggestAutosuggest
Voice autosuggest
StandardBlend

3. New: Clipping by country or polygon

One key benefit of what3words is that similar 3 word addresses are located as far apart as possible. This means that you can make AutoSuggest results more accurate and relevant to each user. For example, when a customer specifies a delivery country on a checkout page, AutoSuggest results can be configured to only prompt the user with 3 word addresses within their country.

With the what3words API v3  you can now clip to a country (or multiple countries) by specifying county code(s) or to a polygon by including the polygon coordinates with the request.  The existing radius and bounding box clipping can also be used to restrict results.

Methods of geographical clipping with what3words API v3:

  • Country clipping
  • Polygon clipping
  • Radius clipping
  • Bounding box clipping

4. Error handling

We’ve improved the way we manage and return errors. Our responses are now more robust and it’s easier for applications to handle errors gracefully. what3words API v3 will always supply an appropriate HTTP status code in its response, alerting an application to an error and providing a description of how it can be investigated. On success, it will return a 200 status code.

5. Wrappers and migration docs

To make our API easy to migrate to the new version or add to a new application, we’ve updated and added new code libraries. Here is a short migration guide summarising the key changes. Full reference docs and API wrappers are here.

Get started

All API keys created for API V2 can automatically make requests to API v3.

Create my new key

Join us!

Interested in joining us to build innovative products with exciting new technologies? Check out our open positions