API v2
This page describes version 2 of the API which was officially deprecated in March 2019 and will no longer be available after the 1st February 2021. Please use the latest version .
The what3words API allows you to convert a 3 word address to coordinates (forward geocoding), to convert coordinates to a 3 word address (reverse geocoding), to obtain suggestions based on a full or partial 3 word address (AutoSuggest, Voice AutoSuggest and StandardBlend), to obtain a geographically bounded section of the 3m x 3m what3words grid and to determine the languages that the API currently supports.
Overview
Get Started
- Get your free API key.
- Start using the what3words API by requesting a URL:
3 words address => coordinates
https://api.what3words.com/v2/forward?addr=index.home.raft&key=MY-API-KEY
Coordinates => 3 word address
https://api.what3words.com/v2/reverse?coords=51.521251%2C-0.203586&key=MY-API-KEY
Key Points
- 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 asX-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.
Error Handling
Wherever possible, the what3words API tries to use the appropriate HTTP status code to indicate problems or errors when invoking an API resource; the status code and reason message are additionally returned in the status
section of the response body as status
and reason
respectively.
Both the HTTP status and the API status should be checked; it is entirely possible to have an HTTP status of 200
returned because the API request was well formed but to have an API error code returned because the request generated an error or contained an invalid parameter.
For example, attempting to forward geocode an invalid 3 word address such as no.address.here
would return an HTTP status of 200
and an API error code of 300
.
Example error
{ "status": { "status": 200, "reason": "OK", "code": 300, "message": "Invalid or non-existent 3 word address" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
Code | Description |
---|---|
200 | The API resource call was well formed and successfully handled; additional information may also be available in the status section of the response body. |
400 | An attempt was made to access an SSL only API endpoint via vanilla HTTP. |
400 | A required parameter was missing or contained an invalid value. |
401 | An invalid what3words API key was supplied or the what3words API key was missing. |
404 | An invalid or unknown API resource was invoked. |
405 | An invalid HTTP request method was used to access an API resource. |
50x | A problem has occurred with the what3words API. |
Additional what3words specific error details are also provided in the status
section of the response body as follows.
Authentication Failures:
Code | Description |
---|---|
1 | Authentication failed; missing required key parameter or header. |
2 | Authentication failed; invalid key parameter value or header value. |
3 | Authentication failed, the specified key is inactive. |
Optional Parameter Validation Failures:
Code | Description |
---|---|
100 | The display parameter is invalid or missing a display type. |
101 | The format parameter is invalid or missing a format type. |
102 | The addr parameter is invalid or missing a 3 word address. |
103 | The lang parameter is invalid or missing a language code. |
104 | The coords parameter is invalid or missing coordinates. |
105 | The focus parameter is invalid or missing coordinates or a 3 word address. |
106 | The clip parameter is invalid or missing the clip type and parameters. |
107 | The count parameter is invalid. |
108 | The bbox parameter is invalid. |
Mandatory Parameter Validation Failures
Code | Description |
---|---|
200 | Missing required addr parameter. |
201 | Missing required coords parameter. |
202 | Missing required lang parameter. |
203 | Missing required bbox parameter. |
Geocoding Failures
Code | Description |
---|---|
300 | Invalid or non-existent 3 word address. |
301 | Invalid or non-existent coordinates. |
Grid Failures
Code | Description |
---|---|
400 | The area described by the bounding box is too large; the distance between the NE and SW corners should be less than or equal to 2 km. |
Forward Geocoding
Forward geocodes a 3 word address to a position, expressed as coordinates of latitude and longitude.
curl --request GET --url 'https://api.what3words.com/v2/forward?addr=index.home.raft&key=MY-API-KEY&lang=en&format=json&display=full'
Resource URL
https://api.what3words.com/v2/forward
Parameters
Parameter | Required/Optional | Description | Example |
---|---|---|---|
addr | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
lang | optional | A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en (English). | lang=fr |
display | optional | Return display type; can be one of full (the default), terse (less output) or minimal (the bare minimum) | display=full |
format | optional | Return data format type; can be one of json (the default), geojson or xml | format=geojson |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. | callback=jsonp |
Example Request
GET https://api.what3words.com/v2/forward?addr=index.home.raft&display=full&format=json&key=[API-KEY]
Example Result
{ "crs": { "properties": { "type": "ogcwkt", "href": "http://spatialreference.org/ref/epsg/4326/ogcwkt/" }, "type": "link" }, "bounds": { "southwest": { "lng": -0.203607, "lat": 51.521238 }, "northeast": { "lng": -0.203564, "lat": 51.521265 } }, "words": "index.home.raft", "map": "http://w3w.co/index.home.raft", "language": "en", "geometry": { "lng": -0.203586, "lat": 51.521251 }, "status": { "code": 200, "message": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
Reverse Geocoding
Reverse geocodes coordinates, expressed as latitude and longitude to a 3 word address.
curl --request GET --url 'https://api.what3words.com/v2/reverse?coords=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&format=json&display=full'
Resource URL
https://api.what3words.com/v2/reverse
Parameters
Parameter | Required/Optional | Description | Example |
---|---|---|---|
coords | required | Coordinates as a comma separated string of latitude and longitude | coords=51.432393,-0.348023 |
key | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
lang | optional | A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en | lang=fr |
display | optional | Return display type; can be one of full (the default), terse (less output) or minimal (the bare minimum) | display=full |
format | optional | Return data format type; can be one of json (the default), geojson or xml | format=geojson |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Example Request
GET https://api.what3words.com/v2/reverse?coords=51.521251,-0.203586&display=full&format=json&key=[API-KEY]
Example Result
{ "crs": { "type": "link", "properties": { "href": "http://spatialreference.org/ref/epsg/4326/ogcwkt/", "type": "ogcwkt" } }, "words": "index.home.raft", "bounds": { "southwest": { "lng": -0.203607, "lat": 51.521238 }, "northeast": { "lng": -0.203564, "lat": 51.521265 } }, "geometry": { "lng": -0.203586, "lat": 51.521251 }, "language": "en", "map": "http://w3w.co/index.home.raft", "status": { "code": 200, "message": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
AutoSuggest
Returns a list of 3 word addresses based on user input and other parameters.
This resource 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
AutoSuggest determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. AutoSuggest can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.
Input 3 word address
All AutoSuggest variants accept either a full or partial 3 word address. If a partial 3 word address is specified, you will only receive results back if the partial 3 word address you submit contains the first two words and at least the first character of the third word; otherwise an error will be returned.
Clipping and Focus
We provide various clip
policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the clip
parameter to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the focus
to return results which are likely to be more relevant (results near the user are considered to be more relevant).
In summary, the clip
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 relevancy 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. The lang
parameter is optional, and AutoSuggest will work well even without a lang
parameter.
Results
A maximum of 100 AutoSuggest results may be returned, but you may choose to display fewer results to your user e.g. the first 3 or 5 (depending on your user interface). By default, 3 results will be returned. It is possible we may increase the number of results returned in the future, so if you choose to limit the list of results returned, we recommend that you choose to include e.g. the top 3/5/7 results rather than choose to exclude the bottom e.g. 18/19/20 results.
Resource URL
https://api.what3words.com/v2/autosuggest
Parameters
Parameter | Required/Optional | Description | Example |
---|---|---|---|
addr | 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 | addr=plan.clips.a |
key | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
lang | optional | Specifies 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 | lang=fr |
focus | optional | A location, specified as a latitude,longitude used to refine the results. If specified, the results will be weighted to give preference to those near the specified location in addition to considering similarity to the addr string. If omitted the default behaviour is to weight results for similarity to the addr string only. | focus=51.521251,-0.203586 |
clip | optional | Restricts results to those within a geographical area. If omitted defaults to clip=none . See the section on clipping policies below for full details on the differing clip policies available. | clip=radius(51.521251,-0.203586,10) |
count | optional | The number of AutoSuggest results to return. A maximum of 100 results can be specified, if a number greater than this is requested, this will be truncated to the maximum. The default is 3 | count=5 |
display | optional | Return display type; can be one of full (the default) or terse | display=full |
format | optional | Return data format type; can be one of json (the default), geojson or xml | format=json |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Clipping Policies
Policy | Default | Description | Example |
---|---|---|---|
None | default | No clipping takes place; this is the default. | clip=none |
Radius | clip=radius(lat,lng,km) . Clips to a radius of km kilometers from the point specified as lat,lng . | clip=radius(51.521251,-0.203586,10) | |
Focus | clip=focus(km) . Clips to a radius of km kilometers from the point specified by the focus parameter. | clip=focus(10) | |
Bounding Box | clip=bbox(nelat,nelng,swlat,swlng) . Clips to 3 word addresses that are fully contained inside a bounding box, specified by the northeast and southwest corner coordinates. | clip=bbox(51.521215,-0.2036011,51.520982,-0.2041395) |
Example Requests
AutoSuggest
This example returns AutoSuggest results for the partial 3 word address plan.clips.a
; the results are not clipped and not ranked for proximity to a given location.
GET https://api.what3words.com/v2/autosuggest?addr=plan.clips.a&lang=en&key=[API-KEY]
AutoSuggest With Focus And Without Clip Policy
This example returns AutoSuggest results for the partial 3 word address plan.clips.a
; the results are ranked for proximity relevance to the focus
point of 51.4243877,-0.3474524.
GET https://api.what3words.com/v2/autosuggest?addr=plan.clips.a&lang=en&focus=51.4243877,-0.3474524&key=[API-KEY]
AutoSuggest With Radius Clip Policy
This example returns AutoSuggest results for the partial 3 word address 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/v2/autosuggest?addr=plan.clips.a&clip=radius(51.4243877,-0.3474524,10)&lang=en&key=[API-KEY]
AutoSuggest With Focus Clip Policy
This example returns AutoSuggest results for the partial 3 word address plan.clips.a
; the results are constrained to those that are within 10 km of the focus
point of 51.4243877,-0.3474524.
GET GET https://api.what3words.com/v2/autosuggest?addr=plan.clips.a&focus=51.4243877,-0.3474524&clip=focus(10)&lang=en&key=[API-KEY]
AutoSuggest With Bounding Box Clip Policy
This example returns AutoSuggest results for the partial 3 word address plan.clips.a
; the results are constrained to those that are within the bounding box described by a NE corner of 54,2 and a SW corner of 50,-4; the results are then ranked for proximity relevance to the focus
point of 51.4243877,-0.3474524.
GET https://api.what3words.com/v2/autosuggest?addr=plan.clips.a&focus=51.4243877,-0.3474524&clip=bbox(54,2,50,-4)&lang=en&key=[API-KEY]
{ "suggestions": [ { "country": "gb", "distance": 14, "words": "plan.clips.area", "rank": 1, "geometry": { "lng": -0.140382, "lat": 51.429293 }, "place": "Brixton Hill, London" }, { "country": "gb", "distance": 7, "words": "plan.flips.dawn", "rank": 2, "geometry": { "lng": -0.443947, "lat": 51.425332 }, "place": "Sunbury-on-Thames, Surrey" }, { "country": "gb", "distance": 27, "words": "plan.clips.arts", "rank": 3, "geometry": { "lng": -0.249153, "lat": 51.659134 }, "place": "Borehamwood, Herts." } ], "status": { "status": 200, "reason": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
Voice AutoSuggest
Returns a list of 3 word addresses based on an input string from one of two Cerence speech recognition systems: VoCon Hybrid and NDEV. The default of these is the Cerence Vocon Hybrid, which accepts URL-encoded JSON. The Cerence NDEV plain text output can also be passed to this endpoint, although the results generally have lower accuracy when dealing with a 3 word address input. Please note that this resource does not provide speech recognition capabilities and that a separate licensing agreement is required with Cerence to use the VoCon Hybrid and/or NDEV technologies.
This resource provides corrections for the following types of input error:
- words which sound similar
- misremembered words (e.g. singular vs. plural)
- words in the wrong order
The voice-autosuggest
resource determines possible corrections to the supplied 3 word addresses based on the probability of the input errors listed above and returns a ranked list of suggestions. This resource can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.
Clipping and Focus
We provide various clip
policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the clip
parameter to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the focus
to return results which are likely to be more relevant (results near the user are considered to be more relevant).
In summary, the clip
policy is used to optionally restrict the list of candidate Voice AutoSuggest results, after which, if focus
has been supplied, this will be used to weight the results in order of relevancy to the focus
.
Language
The lang
parameter is mandatory for voice-autosuggest
; we recommend that you set this according to the language of your user interface, or the browser/device language of your user. If your software or app displays 3 word addresses to users (in addition to accepting 3 words as a search/input) then we recommend you set the language parameter for this resource to the same language that 3 word addresses are displayed to your users. Currently, English is the only supported language for voice but more languages will be available soon.
JSON or Text input
The json
parameter is mandatory when using the Cerence VoCon Hybrid speech recognition system, which is the default. To use the Cerence NDEV text input, you should specify voice-type=ndev
, at which point the text
parameter is mandatory. Both strings will typically contain non-URL complaint characters, and should be URL-encoded.
Results
A maximum of 20 Voice AutoSuggest results may be returned, but you may choose to display fewer results to your user e.g. the first 3 or 5 (depending on your user interface). By default, 3 results will be returned. It is possible we may increase the number of results returned in the future, so if you choose to limit the list of results returned, we recommend that you choose to include e.g. the top 3/5/7 results rather than choose to exclude the bottom e.g. 18/19/20 results.
Resource URL
https://api.what3words.com/v2/voice-autosuggest
Parameters
Parameter | Required/Optional | Description | Example |
---|---|---|---|
json | required (see voice-type ) | Cerence VoCon Hybrid JSON, which must be URL encoded. | json=[URL encoded JSON string] |
text | required (see voice-type ) | Cerence NDEV output, which must be URL encoded. | text=[URL encoded text with spaces and newlines] |
key | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
lang | required | A supported 3 word address language as an ISO 639-1 2 letter code | lang=fr |
focus | optional | A location, specified as a latitude,longitude used to refine the results. If specified, the results will be weighted to give preference to those near the specified location in addition to considering similarity to the voice input. If omitted the default behaviour is to weight results for similarity to the voice input only. | focus=51.521251,-0.203586 |
clip | optional | Restricts results to those within a geographical area. If omitted defaults to clip=none . See the section on clipping policies below for full details on the differing clip policies available. | clip=radius(51.521251,-0.203586,10) |
count | optional | The number of Voice AutoSuggest results to return. A maximum of 20 results can be specified, if a number greater than 20 is requested, this will be truncated to the maximum. The default is 3 | count=5 |
voice-type | optional | Which Cerence speech recognition system is being used, and therefore which parameter of json= and text= is required. Can be one of vocon (the default) or ndev | voice-type=vocon |
display | optional | Return display type; can be one of full (the default) or terse | display=full |
format | optional | Return data format type; can be one of json (the default), geojson or xml | format=json |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Clipping Policies
Policy | Default | Description | Example |
---|---|---|---|
None | default | No clipping takes place; this is the default. | clip=none |
Radius | clip=radius(lat,lng,km) . Clips to a radius of km kilometers from the point specified as lat,lng . | clip=radius(51.521251,-0.203586,10) | |
Focus | clip=focus(km) . Clips to a radius of km kilometers from the point specified by the focus parameter. | clip=focus(10) | |
Bounding Box | clip=bbox(nelat,nelng,swlat,swlng) . Clips to 3 word addresses that are fully contained inside a bounding box, specified by the northeast and southwest corner coordinates. | clip=bbox(51.521215,-0.2036011,51.520982,-0.2041395) |
Example Requests
Voice AutoSuggest With Focus And Without Clip Policy
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.dev/v2/voice-autosuggest?json=%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&lang=en&focus=51.4243877,-0.3474524&format=json&key=[api-key]
{ "suggestions": [ { "country": "ie", "distance": 598, "words": "tinges.artichokes.perch", "rank": 1, "geometry": { "lng": -8.621144, "lat": 53.283595 }, "place": "Athenry, Connaught" }, { "country": "ch", "distance": 924, "words": "tent.artichoke.perch", "rank": 2, "geometry": { "lng": 9.739427, "lat": 46.400132 }, "place": "Silvaplana, Grisons" }, { "country": "se", "distance": 1183, "words": "tending.artichokes.perch", "rank": 3, "geometry": { "lng": 15.379507, "lat": 56.805695 }, "place": "Lessebo, Kronoberg" } ], "status": { "status": 200, "reason": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
StandardBlend
Returns a blend of the three most relevant 3 word address candidates for a given location, based on a full or partial 3 word address.
The specified 3 word address may either be a full 3 word address or a partial 3 word address containing the first 2 words in full and at least 1 character of the 3rd word. StandardBlend provides the search logic that powers the search box on map.what3words.com and in the what3words mobile apps.
Language
StandardBlend 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. The lang
parameter is optional, and StandardBlend will work well even without a lang
parameter.
Results
A maximum of 100 AutoSuggest results may be returned, but you may choose to display fewer results to your user e.g. the first 3 or 5 (depending on your user interface). By default, 3 results will be returned. It is possible we may increase the number of results returned in the future, so if you choose to limit the list of results returned, we recommend that you choose to include e.g. the top 3/5/7 results rather than choose to exclude the bottom e.g. 18/19/20 results.
Resource URL
https://api.what3words.com/v2/standardblend
Parameters
Parameter | Required/Optional | Description | Example |
---|---|---|---|
addr | required | The full or partial 3 word address to obtain blended candidates for. At minimum this must be the first two complete words plus at least one character from the third word | addr=plan.clips.a |
key | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
lang | optional | Specifies a fallback language, which will help guide StandardBlend 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 | lang=fr |
focus | optional | A location, specified as a latitude,longitude used to refine the results. If specified, the results will be weighted to give preference to those near the specified location. | focus=51.521251,-0.203586 |
format | optional | Return data format type; can be one of json (the default), geojson or xml | format=json |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Visualising StandardBlend
The what3words map site uses the standardblend
method to display candidate 3 word addresses. If the contents of the search box matches a partial 3 word address, detected by a regular expression, then standardblend
will be invoked and any resulting candidate 3 word addresses displayed. The map site also displays a relevant flag, keyed on the ISO 3166-1 alpha-2 country code that is returned by the API. For the map site, we are using a flag set licensed from IconDrawer with the addition of two additional flags for tn and xk .
Example Requests
StandardBlend
This example returns StandardBlend results for the partial 3 word address plan.clips.a
; the results are ranked for proximity relevance to the focus
point 51.4243877,-0.3474524.
GET https://api.what3words.com/v2/standardblend?addr=plan.clips.above&lang=en&focus=51.4243877,-0.3474524&format=json&key=[API-KEY]
{ "blends": [ { "distance": 1, "rank": 1, "words": "plan.clips.above", "language": "en", "place": "Teddington, London", "geometry": { "lng": -0.348023, "lat": 51.432393 }, "country": "gb" }, { "distance": 6405, "rank": 2, "words": "plans.clips.above", "language": "en", "place": "Warren Park, Indiana", "geometry": { "lng": -86.101238, "lat": 39.785077 }, "country": "us" }, { "distance": 8822, "rank": 3, "words": "plan.clip.above", "language": "en", "place": "Coronado, California", "geometry": { "lng": -117.272099, "lat": 32.716944 }, "country": "us" } ], "status": { "status": 200, "reason": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
Voice StandardBlend
Returns a blend of the three most relevant 3 word address candidates for a given location, based on an input string of URL encoded Cerence Vocon Hybrid JSON. Please note that this resource does not provide speech recognition capabilities and that a separate licensing agreement is required with Cerence to use the VoCon Hybrid SDK.
Resource URL
https://api.what3words.com/v2/voice-standardblend
Parameters
Parameter | Required/Optional | Description | Example |
---|---|---|---|
json | required | Cerence VoCon Hybrid JSON, which must be URL encoded. | json=[URL encoded JSON string] |
key | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
lang | required | A supported 3 word address language as an ISO 639-1 2 letter code | lang=fr |
focus | optional | A location, specified as a latitude,longitude used to refine the results. If specified, the results will be weighted to give preference to those near the specified location in addition to considering similarity to the voice input. If omitted the default behaviour is to weight results for similarity to the voice input only. | focus=51.521251,-0.203586 |
format | optional | Return data format type; can be one of json (the default), geojson or xml | format=json |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Example Requests
Single Language StandardBlend
This example returns StandardBlend results for the supplied Cerence VoCon Hybrid JSON; the results are ranked for proximity relevance to the focus
point 51.4243877,-0.3474524 not clipped.
GET https://api.what3words.com/v2/voice-standardblend?json=%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&lang=en&focus=51.4243877,-0.3474524&format=json&key=[API-KEY]
{ "blends": [{ "country": "ie", "distance": 598, "words": "tinges.artichokes.perch", "rank": 1, "language": "en", "geometry": { "lng": -8.621144, "lat": 53.283595 }, "place": "Athenry, Connaught" }, { "country": "ca", "distance": 5378, "words": "tend.artichokes.perch", "rank": 2, "language": "en", "geometry": { "lng": -78.736977, "lat": 47.928107 }, "place": "Rouyn-Noranda, Quebec" }, { "country": "ca", "distance": 6142, "words": "tent.artichokes.perch", "rank": 3, "language": "en", "geometry": { "lng": -124.344359, "lat": 65.803269 }, "place": "Norman Wells, Northwest Territories" } ], "status": { "status": 200, "reason": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
Grid Section
Returns a section of the 3m x 3m what3words grid for a given area.
curl --request GET --url 'https://api.what3words.com/v2/grid?bbox=52.208867%2C0.117540%2C52.207988%2C0.116126&key=MY-API-KEY&format=json'
Resource URL
https://api.what3words.com/v2/grid
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] |
bbox | required | Bounding box, specified by the northeast and southwest corner coordinates, for which the grid should be returned. | bbox=52.207988,0.116126,52.208867,0.117540 |
format | optional | Return data format type; can be either json (the default) or geojson | format=geojson |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Example Request
GET https://api.what3words.com/v2/grid?bbox=52.208867,0.117540,52.207988,0.116126&format=json&key=[API-KEY]
Example Result
{ "lines": [ { "start": { "lng": 0.11612600000001, "lat": 52.208009918068 }, "end": { "lng": 0.11753999999999, "lat": 52.208009918068 } }, { "start": { "lng": 0.11612600000001, "lat": 52.20803686934 }, "end": { "lng": 0.11753999999999, "lat": 52.20803686934 } } ], "status": { "status": 200, "reason": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }
Get Languages
Retrieves a list of the currently loaded and available 3 word address languages.
curl --request GET --url 'https://api.what3words.com/v2/languages?key=MY-API-KEY' '
Resource URL
https://api.what3words.com/v2/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] |
callback | optional | Specifies that the response should be JSONP wrapped as a function; supplying a callback parameter is only supported for JSON and GeoJSON format responses. See JSONP Responses for more information. | callback=jsonp |
Example Request
GET https://api.what3words.com/v2/languages?format=json&key=[API-KEY]
Example Result
curl --request GET --url 'https://api.what3words.com/v2/languages?key=MY-API-KEY'
{ "languages": [ { "code": "de", "name": "German", "native_name": "Deutsch" }, { "code": "mn", "name": "Mongolian", "native_name": "Mонгол" }, { "code": "fi", "name": "Finnish", "native_name": "Suomi" }, { "code": "ru", "name": "Russian", "native_name": "Русский" }, { "code": "sv", "name": "Swedish", "native_name": "Svenska" }, { "code": "pt", "name": "Portuguese", "native_name": "Português" }, { "code": "sw", "name": "Swahili", "native_name": "Kiswahili" }, { "code": "en", "name": "English", "native_name": "English" }, { "code": "it", "name": "Italian", "native_name": "Italiano" }, { "code": "fr", "name": "French", "native_name": "Français" }, { "code": "es", "name": "Spanish", "native_name": "Español" }, { "code": "ar", "name": "Arabic", "native_name": "العربية" }, { "code": "pl", "name": "Polish", "native_name": "Polski" }, { "code": "tr", "name": "Turkish", "native_name": "Türkçe" } ], "status": { "status": 200, "reason": "OK" }, "thanks": "Thanks from all of us at index.home.raft for using a what3words API" }