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

The API's endpoints depend on your region:

  • North America: https://api.amazonalexa.com/events

  • Europe: https://api.eu.amazonalexa.com/events

  • Far East: https://api.fe.amazonalexa.com/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

See also: Handling Requests Sent by Alexa

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. Note the plural form.

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. Note the singular form.

Request

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

Response

One of: "CELSIUS" or "FAHRENHEIT".

Response codes

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