Get started

📘

Note

what3words is a restricted product. Contact your HERE account manager to activate or get a what3words license.

This section outlines how to get started quickly using what3words on the HERE platform.

📘

Note

This section provides information on the minimum setup required to quickly begin using what3words. For more detailed information on HERE account setup, project creation, service linking, app registration, and authentication, see the Identity & Access Management Guide.

Get a HERE account

Obtain access to the HERE platform through your organization administrator's invitation or contact us to get started.

• If your company has already established a HERE platform organization, contact your organization admin who can invite you to join the organization.
• If your company hasn’t established a HERE platform organization yet, contact us.

Create a project

To create a project, follow these steps:

1. Sign in to the HERE platform using your HERE account.
2. Open the Projects manager from the launcher.
3. Click Create new project.
4. Enter a name for the project. Project names don't have to be unique.
5. Enter a project ID. Project IDs must be unique within an organization and cannot be changed for the lifetime of the organization. Project IDs must be between 4 and 16 characters in length.
6. Enter an optional description.
7. Click Save.

Get an API key

To get an API key, follow these steps:

1. On the Resources tab, select Services and then click Link a Service.
2. Search for services and click Link to link them to your project as needed.
3. Click Done.
4. Select the Access and permissions tab and click Grant access.
5. Under New app, select Create.
6. Provide an app name and click Register. The platform creates a new app with a unique app ID.
7. On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Send a request

The following are examples of requests:

What3words address to coordinates

https://what3words.search.hereapi.com/v3/convert-to-coordinates?words=limo.reserve.skews&apiKey=[YOUR-API-KEY]

Coordinates to What3Words

https://what3words.search.hereapi.com/v3/convert-to-3wa?coordinates=51.44401%2C5.48052&apiKey=[YOUR-API-KEY]

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.

Locales

For some of our supported languages, a what3words locale can be specified within the API request using either the parameter locale or using the language parameter. The locale allows the what3words address to be displayed in a variant of a language. For example, Mongolian what3words addresses can be displayed in either Cyrillic or Latin characters and therefore by specifying the locale in the API request you can return either variant. The locale will also be included in the API response to show which variant has been returned.

Supported locales

If a locale is not specified for these languages the default locale for the language will be returned. If a language does not have multiple locales then null will be returned. For more information on how to pass in the locale please see the parameters for each API feature.

Error handling

If sucessful, 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 programmatically 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://what3words.search.hereapi.com/v3/convert-to-coordinates?words=no.address.here&key=[YOUR-API-KEY]

The response will be an HTTP 400, with the following body:

JSON

{
  "error": {
    "code": "BadWords",
    "message": "Invalid or non-existent 3 word address"
  }
}

📘

Note

Oauth tokens are recommended for production. This example uses an apiKey to allow you to quickly try the API.