Obtain Customer Settings Information with the Alexa Settings API

Alexa customers can set their time zone, distance measuring unit, and temperature measurement unit in the Alexa app. The Alexa Settings APIs allow developers to retrieve customer preferences for these settings in a unified view.

A JWT token is used for authorization. All of these APIs refer to deviceId, which is the unique identifier for the customer device for which these settings are being obtained.

Alexa Settings API endpoint and authorization
- Get the API Access Token and Device ID
Get the time zone
- Request
- Response
Get the distance measurement unit
- Request
- Response
Get the temperature measurement unit
- Request
- Response
Response codes

Alexa Settings API endpoint and authorization

The API's endpoints depend on your region:

North America: https://api.amazonalexa.com/v3/events
Europe: https://api.eu.amazonalexa.com/v3/events
Far East: https://api.fe.amazonalexa.com/v3/events

Each API request must have an Authorization header whose value should be the JWT access token retrieved from Login with Amazon.

Get the API Access Token and Device ID

Each request sent to your skill includes an API access token (apiAccessToken) that encapsulates the permissions granted to your skill. You need to retrieve both this token and the device ID (deviceId) and include them in requests for the customer's settings.

Both the apiAccessToken and device ID deviceId values are nested in the System object, which is nested in the context object. To see the full body of the request, refer to Request Format.

{
  "context": {
    "System": {
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.amazonalexa.com",
      "device": {
        "deviceId": "string-identifying-the-device",
        "supportedInterfaces": {}
      },
      "application": {
        "applicationId": "string"
      },
      "user": {}
    }
  }
}

Thus:

deviceId = this.event.context.System.device.deviceId

When your code requests customer settings, include:

The deviceID in the request path
The access token in an Authorization header in the format: Bearer ACCESS_TOKEN, where ACCESS_TOKEN is the value of the apiAccessToken field from the Alexa request message. Here is an example:

Authorization: Bearer AxThk...6fnLok

Thus: accessToken = this.event.context.System.apiAccessToken

Get the time zone

Get the time zone of the device.

Request

GET	/v2/devices/{deviceId}/settings/System.timeZone

Response

An example of a specific time zone is given here: "Africa/Abidjan"

See a complete list of time zones.

Get the distance measurement unit

Get the distance measurement unit of the device.

Request

/v2/devices/{deviceId}/settings/System.distanceUnits

Response

One of: "METRIC" or "IMPERIAL".

Get the temperature measurement unit

Get the temperature measurement unit of the device.

Request

/v2/devices/{deviceId}/settings/System.temperatureUnits

Response

One of: "CELSIUS" or "FAHRENHEIT".

Response codes

Code	Message
200	Successfully retrieved the setting.
204	No setting value exists.
400	Bad request.
401	Token is malformed.
403	The authentication token is invalid or has expired.
404	Not found. Applies when the given URI is not able to locate a resource, such as if the `deviceId` is invalid.
429	Request is throttled. This response occurs if the rate limit is exceeded.
503	Service unavailable.