All tutorials
Partner API Docs | what3words
The what3words Partner API allows Partners to create and manage what3words API keys programmatically. The following tasks can be performed using the Partner API
- Create an API key
- Get a list of all of an accounts API keys
- Change status of an API key (disable/enable)
- Create a what3words account by signing up to a plan
- Contact your account manager to request access to the Partner API
- Once enabled, obtain your Partner API key from your account manager
- Use your Partner API key in requests to the API
Tips
- Use HTTPS GET, POST and PATCH methods only
- Remember to always URL encode your parameters
- Always include a valid Partner API key in the key=[YOUR_API_KEY] parameter
Authentication
The what3words Partner API uses API keys to authenticate requests. Partner API Keys differ from keys for our main API with keys being 12 characters and prefixed “PK”.
All API requests must be made over HTTPS. Calls made over HTTP will fail. API requests without authentication will also fail.
Error handling
If all went well, you will get a 200 HTTP status code. If something went wrong, such as trying application POST without a key you will get the appropriate HTTP error status (403 in this case). Also, the body will contain a message_code which can be used programmatically so you can respond appropriately. message is intended as a helpful message to help you understand how to fix what went wrong.
Response Codes
- 200 OK: The client application has been successfully linked with the partner application.
- 400 Bad Request: There was an issue with the request, typically due to:
- Missing partner api key
keyin the request query- The provided
keyis not a partner application or it has been suspended- Missing client api key
client_api_keyin the request body- The provided
client_api_keyhas already been linked.
- The provided
- Missing client api key
- The provided
- Missing partner api key
{ "message_code": 894, "message": "Client key not provided" }
Create a what3words API key for use in an application. The key can then be used to make requests to the what3words Main API. A key can be created for each end client and can be used as a way to segment usage. When creating a new key the request must specify a name and description to identify the key.
curl --location --request POST 'https://accountsapi.what3words.com/partner/v1/application?key=PK2D3j230291' \ --header 'Content-Type: application/json' \ --data-raw '{"name": "name of app", "description": "description of app"}'
| Parameters | Required/Optional | Description | Example |
| key | Required | Partner API key | key=PK2D3J230291 |
Request body
| Request Body | Required/Optional | Description | Example |
| name | Required | Name of API key. Could be the account name or an ID. | "name": "My app" |
| description | Required | Description of API key. Could be the account name or an ID or type of account | "description": "My test app" |
Example Request
POST
- https://accountsapi.what3words.com/partner/v1/application?key=PK2D3J230291
{"name": "name of app", "description": "description of app"}
Example Result
{ "api_key": "PG122LFC4W98", "name": "name of app", "description": "description of app", "suspended": false }
Obtain either one or all of the API keys connected to your partner account. Pass in a key to the request to return just a specific key details. The response will return the name and description of the key, along with it’s status (enabled/disabled).
curl --location --request GET 'https://accountsapi.what3words.com/partner/v1/application?key=PK2D3j230291&page=1&per_page=10'
| Parameters | Required/Optional | Description | Example |
| key | Required | Partner API key | key=PK2D3J230291 |
| api_key | Optional | API key | api_key=LFC4W98R |
Example Request
GET
Example Result
{ "message": "OK", "page": 1, "per_page": 10, "total": 3, "applications": [ { "api_key": "D0O8DQAR", "name": "app1", "description": "desc1", "suspended": false }, { "api_key": "U8KB3NZR", "name": "app2", "description": "desc2", "suspended": false }, { "api_key": "LFC4W98R", "name": "app3", "description": "desc3", "suspended": false } ] }
Enable or disable an API key. Disabling a key prevents the application from being able to make requests to the what3words Main API.
curl --location --request PATCH 'https://accountsapi.what3words.com/partner/v1/application?key=PK2D3j230291' \ --header 'Content-Type: application/json' \ --data-raw '{"suspended": false, "api_key": "PGLFC4W98R"}'
| Parameters | Required/Optional | Description | Example |
| key | Required | Partner API key | key=PK2D3J230291 |
Request body
| Request Body | Required/Optional | Description | Example |
| api_key | Required | Key to be changed | "api_key": "PGLFC4W98R" |
| suspended | Required | Suspended - true/false | "suspended": false |
Example Request
PATCH
- https://accountsapi.what3words.com/partner/v1/application?key=PK2D3J230291
Example Result
{ "api_key": "PGLFC4W98R", "name": "name of app", "description": "description of app", "suspended": false }
Link an API key that was created “manually” (outside of the Partner API through accounts.what3words.com) to a Partner account for revenue share agreements.
curl --location --request POST 'https://accountsapi.what3words.com/partner/v1/application/link?key=PK2D3J230291' \ --header 'Content-Type: application/json' \ --data-raw '{"client_api_key": "<client-application-key>"}'
| Parameters | Required/Optional | Description | Example |
| key | Required | Partner API key | key=PK2D3J230291 |
Request body
| Request Body | Required/Optional | Description | Example |
| client_api_key | Required | API key created through accounts.what3words.com | { "client_api_key": "<client-application-key>" }</client-application-key> |
Example Request
POST
- https://accountsapi.what3words.com/partner/v1/application/link?key=<partner-api-key> Content-Type: application/json { “client_api_key”: “<client-application-key>” }