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": {}
}
}
}
When your code requests customer settings, include:
-
The
deviceIDin the request path. -
The access token in an
Authorizationheader in the format: BearerACCESS_TOKEN, whereACCESS_TOKENis the value of theapiAccessTokenfield from the Alexa request message. See also: Handling Requests Sent by Alexa.
You can get the deviceID and access token in the following ways:
- By using an ASK SDK. Example:
const deviceId = Alexa.getDeviceId(handlerInput.requestEnvelope); - By using plain JSON, starting from the handler input. Example:
const deviceId = handlerInput.requestEnvelope.context.System.device.deviceId;
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
GET /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
GET /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: Nov 29, 2023