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.

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

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.

Was this page helpful?

Last updated: Nov 29, 2023