Obtain Customer Settings Information with the Alexa Settings API

Note: Sign in to the developer console to build or publish your skill.

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.

An access 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.

Note: If you test your skill with the Alexa Simulator, you will not be able to access all of the Alexa Settings API capabilities. If you attempt to query the Alexa Settings API using the deviceId and apiAccessToken values generated by the Alexa Simulator, you will only be able to retrieve the time zone value. If you attempt to retrieve the distance measurement unit or the temperature measurement unit, you will get an 'Error 204 No Content' error message. See Alexa Simulator Limitations.

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

Each API request must include an 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. 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

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.
406	Not acceptable. The header is not in an acceptable format.
429	Request is throttled. This response occurs if the rate limit is exceeded.
503	Service unavailable.

Last updated: Mar 30, 2022