API v3

The what3words API is a fast and simple interface that allows you to convert 3 word addresses to coordinates and vice versa. It features a powerful AutoSuggest function, which can validate and autocorrect user input and limit it to certain geographic areas (this powers the search box on our map site). It allows you to request a section of the what3words grid (which can be requested as GeoJSON for easy display on online maps), and to request an up-to-date list of all languages supported by what3words. For advanced users, AutoSuggest can be used to post-process voice output. See links on the left to navigate.

All coordinates are latitude,longitude pairs in standard WGS-84 as commonly used worldwide in GPS systems. All latitudes must be in the range of -90 to 90 (inclusive).

Overview

Get started

Get your free API key.
Check out our wrappers for JavaScript, Android, Java, Python, PHP, Swift and Objective-C.
Or start using the what3words API directly by requesting a URL:

3 words address => coordinates

https://api.what3words.com/v3/convert-to-coordinates?words=filled.count.soap&key=[API-KEY]

Copied

Coordinates => 3 word address

https://api.what3words.com/v3/convert-to-3wa?coordinates=51.521251%2C-0.203586&key=[API-KEY]

Copied

Tips

Use HTTPS GET method only
Remember to always URL encode your parameters
Always include a valid API key in the key=api-key parameter, or in the request header as X-Api-Key: [API-KEY]
We support CORS, which allows Javascript requests to be made across domains. Each response contains the Access-Control-Allow-Origin: * header, that enables CORS.

Locales

For some of our supported languages, a what3words locale can be specified within the API request using either the parameter locale or using the language parameter. The locale allows the what3words address to be displayed in a variant of a language. For example, Mongolian what3words addresses can be displayed in either Cyrillic or Latin characters and therefore by specifying the locale in the API request you can return either variant. The locale will also be included in the API response to show which variant has been returned.

Bosnian-Croatian-Montenegrin-Serbian is available using the language code oo with Cyrillic and Latin locales (oo_cy and oo_la).

Supported locales:

Language/Locale code	Language variant
`oo_cy`	Bosnian-Croatian-Montenegrin-Serbian (Cyrillic)
`oo_la`	Bosnian-Croatian-Montenegrin-Serbian (Latin)
`kk_cy`	Kazakh (Cyrillic)
`kk_la`	Kazakh (Latin)
`mn_cy`	Mongolian (Cyrillic)
`mn_la`	Mongolian (Latin)
`zh_tr`	Chinese (Traditional)
`zh_si`	Chinese (Simplified)

If a locale is not specified for these languages the default locale for the language will be returned. If a language does not have multiple locales then null will be returned. For more information on how to pass in the locale please see the parameters for each API feature.

Error handling

If all went well, you will get a 200 HTTP status code. If something went wrong, such as trying convert-to-coordinates with an invalid 3 word address such as no.address.here, you will get the appropriate HTTP error status (400 in this case). Also, the body will contain an error block with a code and a messagecode can be used programmatically so you can respond appropriately. message is intended as a helpful message to help you understand how to fix what went wrong.

Example error

URL: https://api.what3words.com/v3/convert-to-coordinates?words=no.address.here&key=[API-KEY]

{
  "error": {
      "code": "BadWords",
      "message": "Invalid or non-existent 3 word address"
  }
}

Copied

Convert to 3 word address

This function will convert a latitude and longitude to a 3 word address, in the language of your choice. It also returns country, the bounds of the grid square, a nearby place (such as a local town) and a link to our map site.

curl --request GET --url 'https://api.what3words.com/v3/convert-to-3wa?key=MY-API-KEY&coordinates=51.521251%2C-0.203586&language=en&format=json'

Copied

Resource URL

https://api.what3words.com/v3/convert-to-3wa

Parameters

Parameter	Required/Optional	Description	Example
`coordinates`	required	Coordinates as a comma separated string of latitude and longitude	`coordinates=51.432393,-0.348023`
`language`	optional	A supported 3 word address language as an ISO 639-1 2 letter code. For Bosnian-Croatian-Montenegrin-Serbian use `oo`. Defaults to `en` (English). For a full list of 3 word address languages, see available-languages.	`language=fr`
`format`	optional	Return data format type; can be either `json` (the default) or `geojson`	`format=geojson`
`locale`	optional	Locale to specify a variant of a language (see here more details)	`locale=mn_la`

Example Request

GET https://api.what3words.com/v3/convert-to-3wa?key=[API-KEY]&coordinates=51.521251%2C-0.203586&language=en&format=json

Example Result

{
  "country": "GB",
  "square": {
      "southwest": {
          "lng": -0.195543,
          "lat": 51.520833
      },
      "northeast": {
          "lng": -0.195499,
          "lat": 51.52086
      }
  },
  "nearestPlace": "Bayswater, London",
  "coordinates": {
      "lng": -0.195521,
      "lat": 51.520847
  },
  "words": "filled.count.soap",
  "language": "en",
  "locale": null,
  "map": "https://w3w.co/filled.count.soap"
}

Copied

Convert to coordinates

This function converts a 3 word address to a latitude and longitude. It also returns country, the bounds of the grid square, a nearest place (such as a local town) and a link to our map site.

curl --request GET --url 'https://api.what3words.com/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json'

Copied

Resource URL

https://api.what3words.com/v3/convert-to-coordinates

Parameters

Parameter	Required/Optional	Description	Example
`key`	required	A valid API key; if not supplied as a parameter, a key must be supplied as a request header	`key=[API-KEY]`
`words`	required	A 3 word address as a string. It must be three words separated with dots or a japanese middle dot character (・). Words separated by spaces will be rejected. Optionally, the 3 word address can be prefixed with /// (which would be encoded as %2F%2F%2F)	`words=index.home.raft` or `words=///filled.count.soap`
`format`	optional	Return data format type; can be either `json` (the default) or `geojson`	`format=geojson`
`locale`	optional	Locale to specify a variant of a language (see here more details)	`locale=mn_la`

Example request

GET https://api.what3words.com/v3/convert-to-coordinates?words=filled.count.soap&key=[API-KEY]

Example Result

{
{
  "country": "GB",
  "square": {
      "southwest": {
          "lng": -0.195543,
          "lat": 51.520833
      },
      "northeast": {
          "lng": -0.195499,
          "lat": 51.52086
      }
  },
  "nearestPlace": "Bayswater, London",
  "coordinates": {
      "lng": -0.195521,
      "lat": 51.520847
  },
  "words": "filled.count.soap",
  "language": "en",
  "locale": null,
  "map": "https://w3w.co/filled.count.soap"
}

Copied

AutoSuggest

AutoSuggest can take a slightly incorrect 3 word address and suggest a list of valid 3 word addresses. It has powerful features that can, for example, optionally limit results to a country or area, and prioritise results that are near the user (see Clipping and Focus below).

It provides corrections for the following types of input error:

Typing errors
Spelling errors
Misremembered words (e.g. singular vs. plural)
Words in the wrong order

Input 3 word address

AutoSuggest accepts either a full or partial 3 word address (it will be partial if the user is still typing in a search box, for example). A partial 3 word address must contain at least the first two words and first character of the third word. For example filled.count.s will return results, but anything shorter will not.

Clipping and Focus

Our clipping allows you to specify a country (or list of countries) and/or geographic area to exclude results that are not likely to be relevant to your users. To give a more targeted, shorter set of results to your users, we recommend you use the clipping parameters. If you know your user’s current location, we also strongly recommend that you use the focus to return results that are likely to be more relevant (i.e. results near the user).

In summary, the clipping policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to weight the results in order of relevance to the focus.

Multiple clipping policies can be specified, though only one of each type. For example you can clip to country and clip to circle in the same AutoSuggest call, and it will clip to the intersection of the two (results must be in the circle AND in the country). However, you can't specify two clip-to-circle policies in the same call.

Language

AutoSuggest will search in all languages. However, you can additionally specify a fallback language, to help the API in situations where the input is particularly messy. For normal text input, the language parameter is optional, and AutoSuggest will work well even without a language parameter. However, for voice input the language should always be specified.

Results

As well as Cerence-based speech recognition systems, AutoSuggestalso supports a Generic Voice option. This supports output from any speech recognition software. This input type handles spaces between words, for example, 'filled count soap'. Users should not pronounce 'dot' when speaking a 3 word address, and this input type not handle text in languages in which words are not separated by spaces, e.g. Chinese. Language detection should be disabled, so languagemust always be set.

Resource URL

https://api.what3words.com/v3/autosuggest

Parameters

Parameter	Required/Optional	Description	Example
`key`	required	A valid API key; if not supplied as a parameter, a key must be supplied as a request header	`key=[API-KEY]`
`input`	required	The full or partial 3 word address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word.	`input=plan.clips.a`
`focus`	optional	This is a location, specified as latitude,longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the `focus`. For convenience, longitude is allowed to wrap around the 180 line, so 361 is equivalent to 1.	`focus=51.521251,-0.203586`
`clip-to-country`	optional	Restricts AutoSuggest to only return results inside the countries specified by comma-separated list of uppercase ISO 3166-1 alpha-2 country codes (for example, to restrict to Belgium and the UK, use `clip-to-country=GB,BE`). Clip-to-country will also accept lowercase country codes. Entries must be two a-z letters. WARNING: If the two-letter code does not correspond to a country, there is no error: API simply returns no results.	`clip-to-country=NZ,AU`
`clip-to-bounding-box`	optional	Restrict AutoSuggest results to a bounding box, specified by coordinates.`south_lat,west_lng,north_lat,east_lng`, where:`south_lat` less than or equal to north_lat`west_lng` less than or equal to `east_lng`In other words, latitudes and longitudes should be specified order of increasing size. Lng is allowed to wrap, so that you can specify bounding boxes which cross the ante-meridian: `-4,178.2,22,195.4`	`clip-to-bounding-box=51.521,-0.343,52.6,2.3324`
`clip-to-circle`	optional	Restrict AutoSuggest results to a circle, specified by `lat,lng,kilometres`, where `kilometres` in the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179.	`clip-to-circle=51.521,-0.343,142`
`clip-to-polygon`	optional	Restrict AutoSuggest results to a polygon, specified by a comma-separated list of `lat,lng` pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs.	`clip-to-polygon=51.521,-0.343,52.6,2.3324,54.234,8.343,51.521,-0.343`
`input-type`	optional	For power users, used to specify voice input mode. Can be `text` (default),`vocon-hybrid`, `nmdp-asr` or `generic-voice`. see speech recognition.for more details.	`input-type=text`
`language`	optional	For normal text input, used to specify a fallback language which will help guide AutoSuggest if the input is particularly messy. If specified, this parameter must be a supported 3 word address language as an ISO 639-1 2 letter code. For Bosnian-Croatian-Montenegrin-Serbian use `oo`. For voice input (see speech recognition), language must always be specified.	`language=fr`
`prefer-land`	optional	Makes `AutoSuggest` prefer results on land to those in the sea. This setting is on by default. Use `false` to disable this setting and receive more suggestions in the sea.	`prefer-land=false`
`locale`	optional	Locale to specify a variant of a language (see here more details)	`locale=mn_la`

Example requests

AutoSuggest

This example returns AutoSuggest results for the partial 3 word address film.crunchy.spiri; the results are not clipped and not ranked for proximity to a given location.

GET https://api.what3words.com/v3/autosuggest?input=film.crunchy.spiri&key=[API-KEY]

AutoSuggest with focus only

This example returns AutoSuggest results for the partial 3 word address film.crunchy.spiri; the results are ranked for proximity relevance to the focus point of 50.842404,4.361177.

GET https://api.what3words.com/v3/autosuggest?input=film.crunchy.spiri&focus=50.842404,4.361177&key=[API-KEY]

AutoSuggest with clip-to-circle

This example searches for plan.clips.a; the results are constrained to those that are within 10 km of the point 51.4243877,-0.3474524.

GET https://api.what3words.com/v3/autosuggest?input=plan.clips.a&clip-to-circle=51.4243877,-0.3474524,10&key=[API-KEY]

AutoSuggest with focus and clip-to-country

GET https://api.what3words.com/v3/autosuggest?input=plan.clips.a&focus=51.4243877,-0.3474524&clip-to-country=GB&key=[API-KEY]

AutoSuggest with clip-to-bounding-box

This searches for plans.clip.a in the bounding box described by a NE corner of 54,2 and a SW corner of 50,-4.

GET https://api.what3words.com/v3/autosuggest?input=plan.clips.a&clip-to-bounding-box=50,-4,54,2&key=[API-KEY]

{
  "suggestions": [
      {
          "country": "BE",
          "nearestPlace": "Brussels, Brussels Capital",
          "words": "film.crunchy.spirits",
          "distanceToFocusKm": 1,
          "rank": 1,
          "language": "en",
          "locale": null
      },
      {
          "country": "ES",
          "nearestPlace": "Caldes de Montbui, Catalonia",
          "words": "film.crunchy.spirit",
          "distanceToFocusKm": 1039,
          "rank": 2,
          "language": "en",
          "locale": null
      },
      {
          "country": "NL",
          "nearestPlace": "Weert, Limburg",
          "words": "firm.crunchy.spires",
          "distanceToFocusKm": 105,
          "rank": 3,
          "language": "en",
          "locale": null
      }
  ]
}

Copied

Grid section

Returns a section of the 3m x 3m what3words grid for a bounding box. The bounding box is specified by lat,lng,lat,lng as south,west,north,east. You can request the grid in GeoJSON format, making it very simple to display on a map.

curl --request GET
--url 'https://api.what3words.com/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json'

Copied

Resource URL

https://api.what3words.com/v3/grid-section

Parameters

Parameter	Required/Optional	Description	Example
`key`	required	A valid API key; if not supplied as a parameter, a key must be supplied as a request header	`key=[API-KEY]`
`bounding-box`	required	Bounding box, as a lat,lng,lat,lng, for which the grid should be returned. The requested box must not exceed 4km from corner to corner, or a `BadBoundingBoxTooBig` error will be returned. Latitudes must be >= -90 and <= 90, but longitudes are allowed to wrap around 180. To specify a bounding-box that crosses the anti-meridian, use longitude greater than 180. EG: `bounding-box=50.0,179.995,50.01,180.0005`	`bounding-box=52.207988,0.116126,52.208867,0.117540`
`format`	optional	Return data format type; can be either `json` (the default) or `geojson`	`format=geojson`

Example Request

GET https://api.what3words.com/v3/grid-section?bounding-box=52.207988,0.116126,52.208867,0.117540&format=json&key=[API-KEY]

{
  "lines": [
      {
          "start": {
              "lng": 0.116126,
              "lat": 52.208009918068136
          },
          "end": {
              "lng": 0.11754,
              "lat": 52.208009918068136
          }
      },
      {
          "start": {
              "lng": 0.116126,
              "lat": 52.20803686934023
          },
          "end": {
              "lng": 0.11754,
              "lat": 52.20803686934023
          }
      }
  ]
}

Copied

Available languages

Retrieves a list of all available 3 word address languages, including the ISO 3166-1 alpha-2 2 letter code, English name and native name. Bosnian-Croatian-Montenegrin-Serbian is available using the language code oo with Cyrillic and Latin locales (oo_cy and oo_la).

curl --request GET
--url 'https://api.what3words.com/v3/available-languages?key=MY-API-KEY'

Copied

Resource URL

https://api.what3words.com/v3/available-languages

Parameters

Parameter	Required/Optional	Description	Example
`key`	required	A valid API key; if not supplied as a parameter, a key must be supplied as a request header	`key=[API-KEY]`

Example Request

GET https://api.what3words.com/v3/available-languages?key=[API-KEY]

{
  "languages": [
      {
          "nativeName": "Deutsch",
          "code": "de",
          "name": "German"
      },
      {
          "nativeName": "Norsk",
          "code": "no",
          "name": "Norwegian"
      },
      {
          "nativeName": "Suomi",
          "code": "fi",
          "name": "Finnish"
      },
      {
          "nativeName": "Русский",
          "code": "ru",
          "name": "Russian"
      },
      {
          "nativeName": "Português",
          "code": "pt",
          "name": "Portuguese"
      },
      {
          "nativeName": "Français",
          "code": "fr",
          "name": "French"
      },
      {
          "nativeName": "Bahasa Indonesia",
          "code": "id",
          "name": "Bahasa Indonesia"
      },
      {
          "nativeName": "Mонгол",
          "code": "mn",
          "name": "Mongolian"
      },
      {
          "nativeName": "Svenska",
          "code": "sv",
          "name": "Swedish"
      },
      {
          "nativeName": "한국어",
          "code": "ko",
          "name": "Korean"
      },
      {
          "nativeName": "Kiswahili",
          "code": "sw",
          "name": "Swahili"
      },
      {
          "nativeName": "Afrikaans",
          "code": "af",
          "name": "Afrikaans"
      },
      {
          "nativeName": "Ελληνικά",
          "code": "el",
          "name": "Greek"
      },
      {
          "nativeName": "English",
          "code": "en",
          "name": "English"
      },
      {
          "nativeName": "Italiano",
          "code": "it",
          "name": "Italian"
      },
      {
          "nativeName": "Español",
          "code": "es",
          "name": "Spanish"
      },
      {
          "nativeName": "简体中文",
          "code": "zh",
          "name": "Chinese"
      },
      {
          "nativeName": "Čeština",
          "code": "cs",
          "name": "Czech"
      },
      {
          "nativeName": "isiXhosa",
          "code": "xh",
          "name": "Xhosa"
      },
      {
          "nativeName": "العربية",
          "code": "ar",
          "name": "Arabic"
      },
      {
          "nativeName": "ไทย",
          "code": "th",
          "name": "Thai"
      },
      {
          "nativeName": "日本語",
          "code": "ja",
          "name": "Japanese"
      },
      {
          "nativeName": "isiZulu",
          "code": "zu",
          "name": "Zulu"
      },
      {
          "nativeName": "Polski",
          "code": "pl",
          "name": "Polish"
      },
      {
          "nativeName": "Dansk",
          "code": "da",
          "name": "Danish"
      },
      {
          "nativeName": "Nederlands",
          "code": "nl",
          "name": "Dutch"
      },
      {
          "nativeName": "Türkçe",
          "code": "tr",
          "name": "Turkish"
      }
  ]
}

Copied

Using AutoSuggest with Voice

By default, AutoSuggest accepts text input. However, AutoSuggest also has powerful routines specifically optimised to post-process output from speech recognition systems.

As well as Cerence-based speech recognition systems, AutoSuggest also supports a Generic Voice option. This supports output from any speech recognition software. This input type handles spaces between words, for example, 'filled count soap'. Users should not pronounce 'dot' when speaking a 3 word address, and this input type cannot handle text in languages in which words are not separated by spaces, e.g. Chinese. Language detection is disabled, solanguage must always be set.

Currently, we support two Cerence-based speech recognition systems: NMDP-ASR and VoCon Hybrid. To use speech recognition, you will first need to process your audio using one of Cerence's Automated Speech Recognition systems, then pass the output into our AutoSuggest function. Use the input-type parameter to specify which system's output you are processing. For non-English languages, you must also always specify a language parameter.

Generic Voice

AutoSuggest can post-process output for any speech recognition software . All of AutoSuggest's parameters such as clipping and focus can be used as normal. To use AutoSuggest in Generic Voice mode, set input-type=generic-voice, set input to the space separated 3 word address output, and set language to the appropriate language value, for example language=en.

Cerence VoCon Hybrid

AutoSuggest can post-process output for Cerence's VoCon Hybrid . All of AutoSuggest's parameters such as clipping and focus can be used as normal. To use AutoSuggest in VoCon Hybrid mode, set input-type=vocon-hybrid and set input to the URL-encoded JSON output from VoCon Hybrid.

curl --request GET --url 'https://api.what3words.com/v3/autosuggest?input=%7B%22_isInGrammar%22%3A%22yes%22%2C%22_isSpeech%22%3A%22yes%22%2C%22_hypotheses%22%3A%5B%7B%22_score%22%3A342516%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6546%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34225%2C%22_orthography%22%3A%22tend%22%2C%22_conf%22%3A6964%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A43800%2C%22_orthography%22%3A%22poached%22%2C%22_conf%22%3A6181%2C%22_endTimeMs%22%3A4060%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342631%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6498%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34340%2C%22_orthography%22%3A%22tent%22%2C%22_conf%22%3A6772%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A43800%2C%22_orthography%22%3A%22poached%22%2C%22_conf%22%3A6181%2C%22_endTimeMs%22%3A4060%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342668%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6474%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34225%2C%22_orthography%22%3A%22tend%22%2C%22_conf%22%3A6964%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A41696%2C%22_orthography%22%3A%22perch%22%2C%22_conf%22%3A5950%2C%22_endTimeMs%22%3A4020%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342670%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6474%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34379%2C%22_orthography%22%3A%22tinge%22%2C%22_conf%22%3A6705%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A43800%2C%22_orthography%22%3A%22poached%22%2C%22_conf%22%3A6181%2C%22_endTimeMs%22%3A4060%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342783%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6426%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34340%2C%22_orthography%22%3A%22tent%22%2C%22_conf%22%3A6772%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A41696%2C%22_orthography%22%3A%22perch%22%2C%22_conf%22%3A5950%2C%22_endTimeMs%22%3A4020%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342822%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6402%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34379%2C%22_orthography%22%3A%22tinge%22%2C%22_conf%22%3A6705%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A41696%2C%22_orthography%22%3A%22perch%22%2C%22_conf%22%3A5950%2C%22_endTimeMs%22%3A4020%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%5D%2C%22_resultType%22%3A%22NBest%22%7D&language=en&focus=51.4243877,-0.3474524&input-type=vocon-hybrid&key=[api-key]'

Copied

Example request

AutoSuggest with focus (VoCon Hybrid)

This example returns Voice AutoSuggest results for the supplied Cerence VoCon Hybrid JSON; the results are ranked for proximity relevance to the focus point of 51.4243877,-0.3474524.

GET https://api.what3words.com/v3/autosuggest?input=%7B%22_isInGrammar%22%3A%22yes%22%2C%22_isSpeech%22%3A%22yes%22%2C%22_hypotheses%22%3A%5B%7B%22_score%22%3A342516%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6546%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34225%2C%22_orthography%22%3A%22tend%22%2C%22_conf%22%3A6964%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A43800%2C%22_orthography%22%3A%22poached%22%2C%22_conf%22%3A6181%2C%22_endTimeMs%22%3A4060%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342631%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6498%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34340%2C%22_orthography%22%3A%22tent%22%2C%22_conf%22%3A6772%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A43800%2C%22_orthography%22%3A%22poached%22%2C%22_conf%22%3A6181%2C%22_endTimeMs%22%3A4060%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342668%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6474%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34225%2C%22_orthography%22%3A%22tend%22%2C%22_conf%22%3A6964%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A41696%2C%22_orthography%22%3A%22perch%22%2C%22_conf%22%3A5950%2C%22_endTimeMs%22%3A4020%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342670%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6474%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34379%2C%22_orthography%22%3A%22tinge%22%2C%22_conf%22%3A6705%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A43800%2C%22_orthography%22%3A%22poached%22%2C%22_conf%22%3A6181%2C%22_endTimeMs%22%3A4060%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342783%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6426%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34340%2C%22_orthography%22%3A%22tent%22%2C%22_conf%22%3A6772%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A41696%2C%22_orthography%22%3A%22perch%22%2C%22_conf%22%3A5950%2C%22_endTimeMs%22%3A4020%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%2C%7B%22_score%22%3A342822%2C%22_startRule%22%3A%22whatthreewordsgrammar%23_main_%22%2C%22_conf%22%3A6402%2C%22_endTimeMs%22%3A6360%2C%22_beginTimeMs%22%3A1570%2C%22_lmScore%22%3A300%2C%22_items%22%3A%5B%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A34379%2C%22_orthography%22%3A%22tinge%22%2C%22_conf%22%3A6705%2C%22_endTimeMs%22%3A2250%2C%22_beginTimeMs%22%3A1580%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A47670%2C%22_orthography%22%3A%22artichokes%22%2C%22_conf%22%3A7176%2C%22_endTimeMs%22%3A3180%2C%22_beginTimeMs%22%3A2260%7D%2C%7B%22_type%22%3A%22terminal%22%2C%22_score%22%3A41696%2C%22_orthography%22%3A%22perch%22%2C%22_conf%22%3A5950%2C%22_endTimeMs%22%3A4020%2C%22_beginTimeMs%22%3A3220%7D%5D%7D%5D%2C%22_resultType%22%3A%22NBest%22%7D&language=en&focus=51.4243877,-0.3474524&input-type=vocon-hybrid&key=[api-key]

Cerence NMDP ASR

AutoSuggest can post-process output for Cerence's NMDP ASR . Please contact Cerence before attempting to use this server. Use with text from any other source is unsupported and results may not be as expected. Does not handle text in languages in which words are not separated by spaces, e.g. Chinese. All of AutoSuggest's parameters such as clipping and focus can be used as normal. To pass in NMDP-ASR output, simple set input-type=nmdp-asr and set input to the NMDP ASR output.

Error handling

A successful API call will return an HTTP status code of 200. However, your code should always also handle potential errors. The most common error is a BadWords, which occurs when you call convert-to-coordinates with an invalid 3 word address. In this case you will get the appropriate HTTP error status (400 in this case). Also, the body will contain an error block with a code and a message. code can be used programmatically so you can respond appropriately. message is intended as a helpful message to help you understand what went wrong.

Example error

URL: https://api.what3words.com/v3/convert-to-coordinates?words=no.address.here&key=[API-KEY]

The response will be an HTTP 400, with the following body:

{
  "error": {
      "code": "BadWords",
      "message": "Invalid or non-existent 3 word address"
  }
}

Copied

Below is a list of all HTTP error codes. This is not an exhaustive list; new error codes may be added in future.

Code	Description
`200`	Successful
`400`	Bad request. This could be caused by: Invalid character: make sure you URL encode all parameters. Bad parameter: the `code` will be set to, for example, `BadWords, BadCoordinates, BadLanguage, BadFormat, BadClipToPolygon` and so on. Missing parameter: a required parameter was missing. For example `MissingWords, MissingInput or MissingBoundingBox`. Duplicate parameter: a parameter must only be specified once. If not, you will see a `DuplicateParameter` error code.
`401`	`MissingKey` or `InvalidKey`. Check your API key is supplied as `key=[API-KEY]`. If not supplied as a parameter, a key must be supplied as a request header `X-API-KEY`.
`402`	For API accounts on the Free tier, the requested feature is not available. For accounts on a Business plan, the `convert-to-coordinates` quota has been exceeded. Go to https://accounts.what3words.com/select-plan to adjust your API plan.
`404`	URL not found. Check the URL of the endpoint you're trying to reach.
`405`	Method not allowed. You must use a GET request.
`50x`	Internal Server Error.

Quota and usage limits

API plans

When signing up for the what3words API you will need to select a what3words API plan.

The Free plan only has access to the autosuggest and available-languages API functions.

Each Business plan has a quota for the number of convert-to-coordinates requests that can be made during your account’s billing period. If you exceed your quota during your billing period, any subsequent convert-to-coordinates requests will receive an HTTP 402 response until either the API plan is upgraded or the billing period resets. Other API functions are covered by our Fair Usage Policy.

If you need a higher quota than specified by our plans then please discuss with the what3words team so we can advise on the best product for your use case. We also offer free and discounted plans for qualifying NGOs, charities and emergency services. Get in touch to find out more.

Rate limits

Each API function has a rate limit that restricts the frequency that requests can be sent to the API. If you exceed the rate limit, subsequent requests will be throttled and will receive a HTTP 429 (Too Many Requests) response from the API until your request rate drops below the limit.

The what3words Free plan has a restriction of 10 requests per second for the autosuggest function. We recommend selecting one of our business plans to increase the rate limit.

If you need a higher rate than specified for a plan then please discuss with the what3words team so we can advise on the best product for your use case.

Plan rate limits (requests per second) are as follows:

Plan	AutoSuggest	Convert to coordinates	Convert to 3 word address	Grid	Available Languages
Free	10	N/A	N/A	N/A	200
Basic	200	200	200	200	200
Standard	200	200	200	200	200
Plus	200	200	200	200	200
Premium	200	200	200	200	200

Developer

API v3

Overview

Get started

3 words address => coordinates

Coordinates => 3 word address

Tips

Locales

Supported locales:

Error handling

Example error

Convert to 3 word address

Resource URL

Parameters

Example Request

Example Result

Convert to coordinates

Resource URL

Parameters

Example request

Example Result

AutoSuggest

Input 3 word address

Clipping and Focus

Language

Results

Resource URL

Parameters

Example requests

AutoSuggest

AutoSuggest with focus only

AutoSuggest with clip-to-circle

AutoSuggest with focus and clip-to-country

AutoSuggest with clip-to-bounding-box

Grid section

Resource URL

Parameters

Example Request

Available languages

Resource URL

Parameters

Example Request

Using AutoSuggest with Voice

Generic Voice

Cerence VoCon Hybrid

Example request

AutoSuggest with focus (VoCon Hybrid)

Cerence NMDP ASR

Error handling

Example error

Quota and usage limits

API plans

Rate limits