We use cookies, including third party cookies, to improve your experience and for marketing purposes. By continuing to browse we assume you have consented to their use.Learn more
got it

API v2

This page describes the version 2 of the API which was officially deprecated in March 2019. If you are writing new code that uses the API, please use the latest version .

This version of the API will remain online and functional for the foreseeable future. However, it will no longer be actively developed, so we do recommend updating to V3 where possible.

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

  1. Get your free API key.
  2. 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 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.

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"
}
CodeDescription
200The API resource call was well formed and successfully handled; additional information may also be available in the status section of the response body.
400An attempt was made to access an SSL only API endpoint via vanilla HTTP.
400A required parameter was missing or contained an invalid value.
401An invalid what3words API key was supplied or the what3words API key was missing.
404An invalid or unknown API resource was invoked.
405An invalid HTTP request method was used to access an API resource.
50xA 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:

CodeDescription
1Authentication failed; missing required key parameter or header.
2Authentication failed; invalid key parameter value or header value.
3Authentication failed, the specified key is inactive.

Optional Parameter Validation Failures:

CodeDescription
100The display parameter is invalid or missing a display type.
101The format parameter is invalid or missing a format type.
102The addr parameter is invalid or missing a 3 word address.
103The lang parameter is invalid or missing a language code.
104The coords parameter is invalid or missing coordinates.
105The focus parameter is invalid or missing coordinates or a 3 word address.
106The clip parameter is invalid or missing the clip type and parameters.
107The count parameter is invalid.
108The bbox parameter is invalid.

Mandatory Parameter Validation Failures

CodeDescription
200Missing required addr parameter.
201Missing required coords parameter.
202Missing required lang parameter.
203Missing required bbox parameter.

Geocoding Failures

CodeDescription
300Invalid or non-existent 3 word address.
301Invalid or non-existent coordinates.

Grid Failures

CodeDescription
400The 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

ParameterRequired/OptionalDescriptionExample
addrrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
langoptionalA supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en (english).lang=fr
displayoptionalReturn display type; can be one of full (the default), terse (less output) or minimal (the bare minimum)display=full
formatoptionalReturn data format type; can be one of json (the default), geojson or xmlformat=geojson
callbackoptionalSpecifies 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

ParameterRequired/OptionalDescriptionExample
coordsrequiredCoordinates as a comma separated string of latitude and longitudecoords=51.432393,-0.348023
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
langoptionalA supported 3 word address language as an ISO 639-1 2 letter code. Defaults to enlang=fr
displayoptionalReturn display type; can be one of full (the default), terse (less output) or minimal (the bare minimum)display=full
formatoptionalReturn data format type; can be one of json (the default), geojsonor xmlformat=geojson
callbackoptionalSpecifies 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

ParameterRequired/OptionalDescriptionExample
addrrequiredThe 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 wordaddr=plan.clips.a
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
langoptionalSpecifies 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 codelang=fr
focusoptionalA 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
clipoptionalRestricts 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)
countoptionalThe 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 3count=5
displayoptionalReturn display type; can be one of full (the default) or tersedisplay=full
formatoptionalReturn data format type; can be one of json (the default), geojson or xmlformat=json
callbackoptionalSpecifies 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

PolicyDefaultDescriptionExample
NonedefaultNo clipping takes place; this is the default.clip=none
Radiusclip=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)
Focusclip=focus(km). Clips to a radius of km kilometers from the point specified by the focus parameter.clip=focus(10)
Bounding Boxclip=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 Nuance voice recognition systems: VoCon Hybrid and NDEV. The default of these is the Nuance Vocon Hybrid, which accepts URL-encoded JSON. The Nuance 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 Nuance 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 Nuance VoCon Hybrid voice recognition system, which is the default. To use the Nuance NDEV text input, you should specify voice-type=ndev, at which point the textparameter 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

ParameterRequired/OptionalDescriptionExample
jsonrequired (see voice-type)Nuance VoCon Hybrid JSON, which must be URL encoded.json=[URL encoded JSON string]
textrequired (see voice-type)Nuance NDEV output, which must be URL encoded.text=[URL encoded text with spaces and newlines]
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
langrequiredA supported 3 word address language as an ISO 639-1 2 letter codelang=fr
focusoptionalA 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
clipoptionalRestricts 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)
countoptionalThe 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 3count=5
voice-typeoptionalWhich Nuance voice recognition system is being used, and therefore which parameter of json= and text= is required. Can be one of vocon (the default) or ndevvoice-type=vocon
displayoptionalReturn display type; can be one of full (the default) or tersedisplay=full
formatoptionalReturn data format type; can be one of json (the default), geojson or xmlformat=json
callbackoptionalSpecifies 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

PolicyDefaultDescriptionExample
NonedefaultNo clipping takes place; this is the default.clip=none
Radiusclip=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)
Focusclip=focus(km). Clips to a radius of km kilometers from the point specified by the focus parameter.clip=focus(10)
Bounding Boxclip=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 Nuance 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

ParameterRequired/OptionalDescriptionExample
addrrequiredThe 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 wordaddr=plan.clips.a
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
langoptionalSpecifies 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 codelang=fr
focusoptionalA 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
formatoptionalReturn data format type; can be one of json (the default), geojson or xmlformat=json
callbackoptionalSpecifies 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 Nuance Vocon Hybrid JSON. Please note that this resource does not provide speech recognition capabilities and that a separate licensing agreement is required with Nuance to use the VoCon Hybrid SDK.

Resource URL

https://api.what3words/com/v2/voice-standardblend

Parameters

ParameterRequired/OptionalDescriptionExample
jsonrequiredNuance VoCon Hybrid JSON, which must be URL encoded.json=[URL encoded JSON string]
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
langrequiredA supported 3 word address language as an ISO 639-1 2 letter codelang=fr
focusoptionalA 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
formatoptionalReturn data format type; can be one of json (the default), geojson or xmlformat=json
callbackoptionalSpecifies 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 Nuance 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

ParameterRequired/OptionalDescriptionExample
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
bboxrequiredBounding 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
formatoptionalReturn data format type; can be either json (the default) or geojsonformat=geojson
callbackoptionalSpecifies 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

ParameterRequired/OptionalDescriptionExample
keyrequiredA valid API key; if not supplied as a parameter, a key must be supplied as a request headerkey=[API-KEY]
callbackoptionalSpecifies 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"
}
Back to top