RESTful API

The what3words RESTful API gives you programmatic access to convert a 3 word address to coordinates (forward geocoding), to convert coordinates to a 3 word address (reverse geocoding) and to determine the languages that the API currently supports.

Version Information

Migrating to API v2

Introduction

Get Started

Before you get started, you'll need to register; this will give you a unique key which is needed for using the API. Check your email Inbox and once you receive your sign up email, just validate your account and you'll be ready to dive into the what3words API.

API Endpoints

All API resources are accessed from the api.what3words.com endpoint, which supports vanilla HTTP and SSL.

Authentication

All calls to the what3words API must be authenticated by a valid API key; this must be specified as the key query parameter, in the form key=api-key. If an invalid API key is passed or if the API key is missing an error code of X1 Missing or invalid key will be returned in the response body.

Error Codes

Any errors that occur during the handling of an API method are returned in the JSON response payload as follows.


X1

Missing or invalid key.

X2

Unknown method.

X3

Key inactive.

UE

Unknown error.

11

W3W string not recognised.

21

Invalid coordinates.

41

Invalid language.

Forward Geocoding

Forward geocodes a 3 word address to a position, expressed as coordinates of latitiude and longitude.

Resource URL

api.what3words.com/w3w

Resource Information

Response formats JSON
Requires authentication? Yes

Parameters

string required

A 3 word address as a string

Example value:string=index.home.raft

key required

A valid API key

Example value:key=[API-KEY]

lang optional

A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en

Example value:lang=fr

corners optional

Specifies whether the bounding box for the 3 word address should be included in the response

Example value:corners=true

Example Request

GET https://api.what3words.com/w3w?string=index.home.raft&dcorners=true&key=[API-KEY]

Example Result

                            
{
    "type": "3 words",
    "words": [
        "plan",
        "clips",
        "above"
    ],
    "position": [
        51.432393,
        -0.348023
    ],
    "corners": [
        [
            51.432379,
            -0.348044
        ],
        [
            51.432406,
            -0.348001
        ]
    ],
    "language": "en"
}
                            
                        
                        
curl --request GET \
  --url 'http://api.what3words.com/w3w?string=index.home.raft&key=MY-API-KEY&lang=en&corners=true'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://api.what3words.com/w3w?string=index.home.raft&key=MY-API-KEY&lang=en&corners=true",
  "method": "GET",
  "headers": {}
}

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

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/w3w?string=index.home.raft&key=MY-API-KEY&lang=en&corners=true",
  "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 => "http://api.what3words.com/w3w?string=index.home.raft&key=MY-API-KEY&lang=en&corners=true",
  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.HTTPConnection("api.what3words.com")

conn.request("GET", "/w3w?string=index.home.raft&key=MY-API-KEY&lang=en&corners=true")

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

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

url = URI("http://api.what3words.com/w3w?string=index.home.raft&key=MY-API-KEY&lang=en&corners=true")

http = Net::HTTP.new(url.host, url.port)

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

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

Reverse Geocoding

Reverse geocodes coordinates, expressed as latitiude and longitude to a 3 word address.

Resource URL

api.what3words.com/position

Resource Information

Response formats JSON
Requires authentication? Yes

Parameters

position required

Coordinates as a comma separated string of latitude and longitude

Example value:position=51.432393,-0.348023

key required

A valid API key

Example value:key=[API-KEY]

lang optional

A supported 3 word address language as an ISO 639-1 2 letter code. Defaults to en

Example value:lang=fr

corners optional

Specifies whether the bounding box for the 3 word address should be included in the response

Example value:corners=true

Example Request

GET http://api.what3words.com/position?position=51.521251,-0.203586&corners=true&key=[API-KEY]

Example Result

                            
{
    "words": [
        "plan",
        "clips",
        "above"
    ],
    "position": [
        51.432393,
        -0.348023
    ],
    "corners": [
        [
            51.432379,
            -0.348044
        ],
        [
            51.432406,
            -0.348001
        ]
    ],
    "language": "en"
}
                            
                        
                        
curl --request GET \
  --url 'http://api.what3words.com/position?position=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&corners=true'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://api.what3words.com/position?position=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&corners=true",
  "method": "GET",
  "headers": {}
}

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

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/position?position=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&corners=true",
  "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 => "http://api.what3words.com/position?position=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&corners=true",
  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.HTTPConnection("api.what3words.com")

conn.request("GET", "/position?position=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&corners=true")

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

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

url = URI("http://api.what3words.com/position?position=51.521251%2C-0.203586&key=MY-API-KEY&lang=en&corners=true")

http = Net::HTTP.new(url.host, url.port)

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

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

Get Languages

Retrieves a list of the currently loaded and available 3 word address languages.

Resource URL

api.what3words.com/get-languages

Resource Information

Response formats JSON
Requires authentication? Yes

Parameters

key required

A valid API key

Example value:key=[API-KEY]

Example Request

GET http://api.what3words.com/get-languages?&key=[API-KEY]

Example Result

                            
{
    "languages": [{
        "code": "de",
        "name_display": "Deutsch"
    }, {
        "code": "en",
        "name_display": "English"
    }, {
        "code": "es",
        "name_display": "Español"
    }, {
        "code": "fr",
        "name_display": "Français"
    }, {
        "code": "it",
        "name_display": "Italiano"
    }, {
        "code": "pt",
        "name_display": "Português"
    }, {
        "code": "ru",
        "name_display": "Русский"
    }, {
        "code": "sv",
        "name_display": "Svenska"
    }, {
        "code": "sw",
        "name_display": "Kiswahili"
    }, {
        "code": "tr",
        "name_display": "Türkçe"
    }]
}
                            
                        
                        
curl --request GET \
  --url 'http://api.what3words.com/get-languages?key=MY-API-KEY'
                        
                    
                        
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "http://api.what3words.com/get-languages?key=MY-API-KEY",
  "method": "GET",
  "headers": {}
}

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

var options = {
  "method": "GET",
  "hostname": "api.what3words.com",
  "port": null,
  "path": "/get-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 => "http://api.what3words.com/get-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.HTTPConnection("api.what3words.com")

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

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

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

url = URI("http://api.what3words.com/get-languages?key=MY-API-KEY")

http = Net::HTTP.new(url.host, url.port)

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

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