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.
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.
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 time zone
- Get the distance measurement unit
- Get the temperature measurement unit
- 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: BearerACCESS_TOKEN
, whereACCESS_TOKEN
is the value of theapiAccessToken
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
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