Migration Guide

Introduction

If you're already using v1 of the what3words API you'll find that a lot has changed in v2. To help you migrate your existing applications to v2, we've put together this high level summary of what's new and what's changed.

Why migrate?

Resource names

All of the v1 API resource names have changed in v2, as follows:

  • For converting a 3 word address to coordinates, or forward geocoding, the resource name has changed from /w3w to /v2/forward; more information can be found here.
  • For converting coordinates to a 3 word address, or reverse geocoding, the resource name has changed from /position to /v2/reverse; more information can be found here.
  • To obtain the list of 3 word address languages supported by the API, the resource name has changed from /get-languages to /v2/languages; more information can be found here.

New features

In addition to the 3 main resources provided by the v1 API, v2 now provides a further 3 additional API resources:

  • /v2/autosuggest returns a list of 3 word address suggestions based on a full or partial 3 word address. You can find out more about AutoSuggest here.
  • /v2/standardblend returns a list of 3 word address candidates for a given location, based on a full or partial 3 word address. This is the same search logic that powers our search box on map.what3words.com and in the what3words mobile apps; under the hood the /v2/standardblend resource uses both /v2/forward and /v2/autosuggest methods. You can find out more about StandardBlend here.
  • /v2/grid returns a section of the what3words 3m x 3m grid for a geographical area. You can find out about the grid resource here.

Authentication

As with v1, v2 of the API requires authentication with a what3words API key. This can be provided as part of the query string via the key parameter or as the X-Api-Key header.

SSL only resources

Accessing v2 of the API is supported via SSL only; support for vanilla HTTP has been obsoleted.

Removal of support for HTTP POST

All resources provided by v2 of the API support HTTP GET only; support for HTTP POST or any other method have been obsoleted.

API response formats

By default, v2 of the API returns a payload in JSON; optional format types of GeoJSON and for XML are also supported.

API response payload

The response payloads for the /w3w and /position resources in the v1 API used a different JSON representation. For v2 of the API, both the /v2/forward and /v2/reverse resources return the same consistent response payload.

HTTP status codes and API error codes

In v1 of the API an HTTP status code of 200 was always returned with a further descriptive code in case of errors. For v2 of the API, we try to return the appropriate HTTP status code and additionally return an API error code to further describe API specific errors. The use of HTTP status codes and API error codes are documented here.