API v3

The what3words API is a fast, simple interface which 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 the 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

  1. Get your free API key.
  2. Check out our wrappers for Javascript, Android, Java, Python, PHP, Swift and Objective-C.
  3. 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]
Coordinates => 3 word address
https://api.what3words.com/v3/convert-to-3wa?coordinates=51.521251%2C-0.203586&key=[API-KEY]

For more details on how to use these functions, please see below. We recommend Postman for learning about our API.

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.

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 message code can be used programatically 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"
    }
}
                

Convert to 3 word address

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 nearest place (such as a local town) and a link to our map site.

Resource URL

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

Parameters

key required

A valid API key; if not supplied as a parameter, a key must be supplied as a request header

Example value:key=[API-KEY]

coordinates required

Coordinates as a comma separated string of latitude and longitude

Example value:coordinates=51.432393,-0.348023

language optional

A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en (english). For a full list of 3 word address languages, see available-languages.

Example value:language=fr

format optional

Return data format type; can be either json (the default) or geojson

Example value:format=geojson

Example Request

GET https://api.what3words.com/v3/convert-to-3wa?coordinates=51.520847,-0.195521&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",
    "map": "https://w3w.co/filled.count.soap"
}                            
                        
                            
{
    "features": [
        {
            "bbox": [
                -0.195543,
                51.520833,
                -0.195499,
                51.52086
            ],
            "geometry": {
                "coordinates": [
                    -0.195521,
                    51.520847
                ],
                "type": "Point"
            },
            "type": "Feature",
            "properties": {
                "country": "GB",
                "nearestPlace": "Bayswater, London",
                "words": "filled.count.soap",
                "language": "en",
                "map": "https://w3w.co/filled.count.soap"
            }
        }
    ],
    "type": "FeatureCollection"
}                            
                        
                        
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'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.what3words.com/v3/convert-to-3wa?key=MY-API-KEY&coordinates=51.521251%2C-0.203586&language=en&format=json",
  "method": "GET",
  "headers": {}
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                        
                    
                        
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/v3/convert-to-3wa?key=MY-API-KEY&coordinates=51.521251%2C-0.203586&language=en&format=json",
  "headers": {}
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
                        
                    
                        
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.what3words.com/v3/convert-to-3wa?key=MY-API-KEY&coordinates=51.521251%2C-0.203586&language=en&format=json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                        
                    
                        
import http.client

conn = http.client.HTTPSConnection("api.what3words.com")

conn.request("GET", "/v3/convert-to-3wa?key=MY-API-KEY&coordinates=51.521251%2C-0.203586&language=en&format=json")

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
                        
                    
                        
require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v3/convert-to-3wa?key=MY-API-KEY&coordinates=51.521251%2C-0.203586&language=en&format=json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
                        
                    

Convert to coordinates

Convert 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.

Resource URL

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

Parameters

key required

A valid API key; if not supplied as a parameter, a key must be supplied as a request header

Example value: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)

Example value:words=index.home.raft or words=///filled.count.soap

format optional

Return data format type; can be one of json (the default) or geojson

Example value:format=geojson

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",
    "map": "https://w3w.co/filled.count.soap"
}                            
                        
                            
{
    "features": [
        {
            "bbox": [
                -0.195543,
                51.520833,
                -0.195499,
                51.52086
            ],
            "geometry": {
                "coordinates": [
                    -0.195521,
                    51.520847
                ],
                "type": "Point"
            },
            "type": "Feature",
            "properties": {
                "country": "GB",
                "nearestPlace": "Bayswater, London",
                "words": "filled.count.soap",
                "language": "en",
                "map": "https://w3w.co/filled.count.soap"
            }
        }
    ],
    "type": "FeatureCollection"
}                            
                        
                        
curl --request GET \
  --url 'https://api.what3words.com/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.what3words.com/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json",
  "method": "GET",
  "headers": {}
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                        
                    
                        
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json",
  "headers": {}
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
                        
                    
                        
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.what3words.com/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                        
                    
                        
import http.client

conn = http.client.HTTPSConnection("api.what3words.com")

conn.request("GET", "/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json")

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
                        
                    
                        
require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v3/convert-to-coordinates?key=MY-API-KEY&words=filled.count.soap&format=json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
                        
                    

AutoSuggest

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

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

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

We provide various clipping policies to allow you to specify a country (or list of countries) and/or geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend you use the clipping parameters 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 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 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. 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

By default, 3 results will be returned but you can choose the number of results with n-results, up to a maximum of 100 results.

Resource URL

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

Parameters

key required

A valid API key; if not supplied as a parameter, a key must be supplied as a request header

Example value: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.

Example value:input=plan.clips.a

n-results 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

Example value:n-results=5

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.

Example value:focus=51.521251,-0.203586

n-focus-results optional

Specifies the number of results (must be <= n-results) within the results set which will have a focus. Defaults to n-results. This allows you to run autosuggest with a mix of focussed and unfocussed results, to give you a "blend" of the two. This is exactly what the old V2 standardblend did, and standardblend behaviour can easily be replicated by passing n-focus-results=1, which will return just one focussed result and the rest unfocussed.

Example value:n-focus-results=1

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.

Example value:clip-to-country=NZ,AU

clip-to-bounding-box optional

Restrict autosuggest results to a bounding box, specified by coordinates.
Such as south_lat,west_lng,north_lat,east_lng, where:
south_lat <= north_lat
west_lng <= 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

Example value: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.

Example value: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.

Example value: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 or nmdp-asr. See voice recognition section for more details.

Example value:input-type=text

language optional (text) required (voice)

For normal text input, 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. For voice input (see voice section), language must always be specified.

Example value:language=fr

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 blend of focussed and unfocussed results

We can return 5 results, with 1 focussed result with setting n-results=5 and n-focus-results=1. 4 results in the list will be unfocussed. This is equivalent to the V2 standardblend.

GET https://api.what3words.com/v3/autosuggest?input=film.crunchy.spiri&focus=50.842404,4.361177&n-results=5&n-focus-results=1&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]

Example Result

                            
{
    "suggestions": [
        {
            "country": "BE",
            "nearestPlace": "Brussels, Brussels Capital",
            "words": "film.crunchy.spirits",
            "distanceToFocusKm": 1,
            "rank": 1,
            "language": "en"
        },
        {
            "country": "ES",
            "nearestPlace": "Caldes de Montbui, Catalonia",
            "words": "film.crunchy.spirit",
            "distanceToFocusKm": 1039,
            "rank": 2,
            "language": "en"
        },
        {
            "country": "NL",
            "nearestPlace": "Weert, Limburg",
            "words": "firm.crunchy.spires",
            "distanceToFocusKm": 105,
            "rank": 3,
            "language": "en"
        }
    ]
}                            
                        
                        
curl --request GET \
  --url 'https://api.what3words.com/v3/autosuggest?key=MY-API-KEY&input=index.home.r&n-results=5&focus=51.521251%2C-0.203586&clip-to-country=BE%2CGB'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.what3words.com/v3/autosuggest?key=MY-API-KEY&input=index.home.r&n-results=5&focus=51.521251%2C-0.203586&clip-to-country=BE%2CGB",
  "method": "GET",
  "headers": {}
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                        
                    
                        
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/v3/autosuggest?key=MY-API-KEY&input=index.home.r&n-results=5&focus=51.521251%2C-0.203586&clip-to-country=BE%2CGB",
  "headers": {}
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
                        
                    
                        
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.what3words.com/v3/autosuggest?key=MY-API-KEY&input=index.home.r&n-results=5&focus=51.521251%2C-0.203586&clip-to-country=BE%2CGB",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                        
                    
                        
import http.client

conn = http.client.HTTPSConnection("api.what3words.com")

conn.request("GET", "/v3/autosuggest?key=MY-API-KEY&input=index.home.r&n-results=5&focus=51.521251%2C-0.203586&clip-to-country=BE%2CGB")

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
                        
                    
                        
require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v3/autosuggest?key=MY-API-KEY&input=index.home.r&n-results=5&focus=51.521251%2C-0.203586&clip-to-country=BE%2CGB")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
                        
                    

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.

Resource URL

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

Parameters

key required

A valid API key; if not supplied as a parameter, a key must be supplied as a request header

Example value: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.

Example value:bounding-box=52.207988,0.116126,52.208867,0.117540

format optional

Return data format type; can be one of json (the default) or geojson

Example value:format=json

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]

Example Result

                            
{
    "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
            }
        }
    ]
}                            
                        
                            
{
    "features":[
        {
            "geometry":{
                "coordinates":[
                    [
                        [
                            0.116126,
                            52.208009918068136
                        ],
                        [
                            0.11754,
                            52.208009918068136
                        ]
                    ],
                    [
                        [
                            0.116126,
                            52.20803686934023
                        ],
                        [
                            0.11754,
                            52.20803686934023
                        ]
                    ]
                ],
                "type":"MultiLineString"
            },
            "type":"Feature",
            "properties":{

            }
        }
    ],
    "type":"FeatureCollection"
}                            
                        
                        
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'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.what3words.com/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json",
  "method": "GET",
  "headers": {}
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                        
                    
                        
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json",
  "headers": {}
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
                        
                    
                        
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.what3words.com/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                        
                    
                        
import http.client

conn = http.client.HTTPSConnection("api.what3words.com")

conn.request("GET", "/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json")

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
                        
                    
                        
require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v3/grid-section?key=MY-API-KEY&bounding-box=52.207988%2C0.116126%2C52.208867%2C0.117540&format=json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
                        
                    

Available Languages

Retrieves a list all available 3 word address languages, including the ISO 639-1 2 letter code, english name and native name.

Resource URL

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

Parameters

key required

A valid API key; if not supplied as a parameter, a key must be supplied as a request header

Example value:key=[API-KEY]

Example Request

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

Example Result

                            
{
    "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"
        }
    ]
}                            
                        
                        
curl --request GET \
  --url 'https://api.what3words.com/v3/available-languages?key=MY-API-KEY'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.what3words.com/v3/available-languages?key=MY-API-KEY",
  "method": "GET",
  "headers": {}
}

$.ajax(settings).done(function (response) {
  console.log(response);
});
                        
                    
                        
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/v3/available-languages?key=MY-API-KEY",
  "headers": {}
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();
                        
                    
                        
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.what3words.com/v3/available-languages?key=MY-API-KEY",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
                        
                    
                        
import http.client

conn = http.client.HTTPSConnection("api.what3words.com")

conn.request("GET", "/v3/available-languages?key=MY-API-KEY")

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
                        
                    
                        
require 'uri'
require 'net/http'

url = URI("https://api.what3words.com/v3/available-languages?key=MY-API-KEY")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
                        
                    

Using AutoSuggest with Voice

By default, AutoSuggest accepts text input. However, autosuggest also has powerful routines specifically optimised to post-process output from voice recognition systems. Currently, we support two Nuance-based voice recognition sytems: nmdp-asr and Vocon Hybrid. To use voice recognition, you will first need to process your audio using one of Nuance'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.

Nuance Vocon Hybrid

AutoSuggest can post-process output for Nuance'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.

Example Request

AutoSuggest With Focus (Vocon Hybrid)

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.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]

Nuance NMDP ASR

AutoSuggest can post-process output for Nuance's NMDP ASR. Please contact Nuance 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 programatically 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"
    }
}
            

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

HTTP status code

Information

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 you 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.

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.