Device Settings REST API Reference

Use the Device Settings REST API to get settings associated with the customer's Alexa device. Alexa customers can set their address, distance measuring unit, temperature measurement unit, and time zone in the Alexa app.

Before you can get address information, the customer must grant permission to your skill. For more details, see Enhance Your Skill With Address Information.

API endpoint

Use one of the following API hosts, based on the region where the customer is located:

  • North America: https://api.amazonalexa.com
  • Europe: https://api.eu.amazonalexa.com
  • Far East: https://api.fe.amazon.com

You can find the API endpoint in the context.System.apiEndpoint retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.

Authentication

Each API request must have an authorization header whose value is the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest. The apiAccessToken encapsulates the permissions granted to your skill.

To access address information, the following permission scopes must be enabled for your skill and granted by the customer.

Permission scope Description

read::alexa:device:all:address

Allows your skill to get the full device address.

read::alexa:device:all:address:country_and_postal_code

Allows your skill to get the country code and postal code.

Operations

The Device Settings API includes the following operations.

Operation HTTP method and URI

Get address

GET /v1/devices/{deviceId}/settings/address

Get country and postal codes

GET /v1/devices/{deviceId}/settings/address/countryAndPostalCode

Get distance units

GET /v2/devices/{deviceId}/settings/System.distanceUnits

Get temperature units

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

Get time zone

GET /v2/devices/{deviceId}/settings/System.timeZone

Get address

Get the address of the specified device.

Request

To get the address, you make a GET request to the /v1/devices/{deviceId}/settings/address resource.

Request path and header example

Copied to clipboard.

GET /v1/devices/{deviceId}/settings/address
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

deviceId

Path

Identifies the device at the customer address. Set to the context.System.device.deviceId property value retrieved from a request from Alexa.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the address. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "addressLine1": "410 Maple Street",
    "addressLine2": "Apt B",
    "addressLine3": "",
    "city": "Seattle",
    "countryCode": "US",
    "districtOrCounty": "",
    "postalCode": "98109",
    "stateOrRegion": "WA"
}

Response body properties

Property Description Type

addressLine1

The first line of the address for the specified device.

String

addressLine2

The second line of the address. This value might be an empty string.

String

addressLine3

The third line of the address. This value might be an empty string.

String

city

The city for the specified device.

String

countryCode

The two-letter country or region code for the specified device.

String

districtOrCounty

The district or county associated with the device. For non-US countries, this value might be an empty string.

String

postalCode

The postal code for the device.

String

stateOrRegion

Abbreviation for the state, province, or region associated with the specified device. For non-US countries, this value might be an empty string

String

HTTP status codes

Status Description

200 OK

Response body contains the address of the specified device.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get country and postal codes

Gets the country or region and postal codes of the specified device.

Request

To get the country and postal codes, you make a GET request to the /v1/devices/{deviceId}/settings/address resource.

Request path and header example

Copied to clipboard.

GET /v1/devices/{deviceId}/settings/address/countryAndPostalCode
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

deviceId

Path

Identifies the device at the customer address. Set to the context.System.device.deviceId property value retrieved from a request from Alexa.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the country and postal codes. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
  "countryCode" : "US",
  "postalCode" : "98109"
}

Response body properties

Property Description Type

countryCode

The two-letter country or region code for the specified device.

String

postalCode

The postal code for the specified device.

String

HTTP status codes

Status Description

200 OK

Response body contains the country and postal codes of the specified device.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get distance units

Get the distance-units setting on the specified device.

Request

To get the distance units, you make a GET request to the /v2/devices/{deviceId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/devices/{deviceId}/settings/System.distanceUnits
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

deviceId

Path

Identifies the customer device.
Set to the context.System.device.deviceId property value retrieved from a request from Alexa.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the setting. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
  "METRIC"
}

Response body properties

Property Description Type

setting

Distance units.
Valid values: IMPERIAL, METRIC.

String

HTTP status codes

Status Description

200 OK

Response body contains the distance units setting.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get temperature units

Get the temperature-units setting on the specified device.

Request

To get the setting, you make a GET request to the /v2/devices/{deviceId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/devices/{deviceId}/settings/System.temperatureUnit
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

deviceId

Path

Identifies the customer device.
Set to the context.System.device.deviceId property value retrieved from a request from Alexa.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the setting. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
   "FAHRENHEIT"
}

Response body properties

Property Description Type

setting

A time zone, following the Olson format.
Valid values: CELSIUS, FAHRENHEIT.

String

HTTP status codes

Status Description

200 OK

Response body contains the temperature units setting.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get time zone

Get the time zone setting on the specified device.

Request

To get the time zone, you make a GET request to the /v2/devices/{deviceId}/settings resource.

Request path and header example

Copied to clipboard.

GET /v2/devices/{deviceId}/settings/System.distanceUnits
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

deviceId

Path

Identifies the customer device.
Set to the context.System.device.deviceId property value retrieved from a request from Alexa.

String

Yes

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the setting. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
  "America/Los_Angeles"
}

Response body properties

Property Description Type

setting

A time zone, following the Olson format.
For valid values, see Time Zone Database.

String

HTTP status codes

Status Description

200 OK

Response body contains the time zone setting.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Last updated: Aug 01, 2024