×

Device Address API

When a customer enables your Alexa skill, your skill can obtain the customer’s permission to use address data associated with the customer’s Alexa device. You can then use this address data to provide key functionality for the skill, or to enhance the customer experience. For example, your skill could provide a list of nearby store locations or provide restaurant recommendations using this address information. This document describes how to enable this capability and query the Device Address API for address data.

Note that the address entered in the Alexa device may not represent the current physical address of the device. This API uses the address that the customer has entered manually in the Alexa app, and does not have any capability of testing for GPS or other location-based data.

Steps to Get Customer Permission and Device Address Information

The steps to get device address information are as follows:

  1. Configure your skill in the Amazon Developer Portal to indicate that it requires address information. As a result, the customer is prompted, with a permissions card in the Alexa app to consent to provide the customer’s address information when they configure your skill.

    For reference, here is what the customer sees when prompted for permissions in the Alexa app. In this example, the skill has been configured for permissions to ask for the full address, so that is what is shown on the card.

    Permissions card in the Alexa companion app
    Permissions card in the Alexa companion app
  2. Obtain the deviceId and consentToken from the Alexa launch request message when a customer enables the skill.
  3. Send a message to the correct address endpoint that includes the consentToken and deviceId, as described in Get Country and Postal Code and Get Address.

Configure the Skill to Request Customer Permissions for the Device Address

  • In the Amazon Developer Portal, open your skill and click the Configuration tab.

    In the Permissions section, select Device Address, and either Full Address or Country & Postal Code Only, depending which your skill uses. Click Save.

Dev Portal Permissions

See also: Registering and Managing Your Skill on the Developer Portal

After customer consent is obtained, a request to your skill from Alexa includes a user object that contains a consent token and device ID. You will need to retrieve these values and include them in requests for the customer’s “Full Address” or “Country & Postal Code”. Here is an example of the user and device objects. The user object and the device object 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.

{
  "user": {
    "userId": "amzn1.ask.account.<userId_value>",
    "permissions": {
      "consentToken": "Atza|MQEWY...6fnLok"
    }
  },
  "device": {
    "deviceId": <device_id>,
    "supportedInterfaces": {}
  }
}

Thus:

deviceId = this.event.context.System.device.deviceId

When your code requests either “Full Address” or “Country & Postal Code” from the customer, include:

  • The deviceID in the request path

  • The consent token in an Authorization header in the format: Bearer CONSENT_TOKEN, where CONSENT_TOKEN is the value of the consentToken field from the Alexa request message. Here is an example:

Authorization: Bearer Atc|MQEWY...6fnLok

Thus: consentToken = this.event.context.System.user.permissions.consentToken

See also: Handling Requests Sent by Alexa

New Permissions Card for Requesting Customer Consent

During an interaction, the consentToken provided to your skill might not contain sufficient permissions for your skill to fulfill the request. For example, perhaps the customer did not consent to any permissions during enablement (voice enablement), or a skill may have been updated with new required permissions that were not present in previous versions. In those cases, your skill can display a special permissions card to ask customers for consent dynamically.

New CardAskForPermissionsConsentCard
InterfaceCardRenderer
Definition 
{
    "type": "AskForPermissionsConsent",
    "permissions": << list of scope strings >>
}
Attributespermissions: this contains a list of scope strings that maps to Alexa permissions. Include only those Alexa permissions that are both needed by your skill and that are declared in your skill metadata on the Amazon Developer Portal.

Sample Response with Permission Card

An in-session interaction can return a response that includes the new AskForPermissionsConsent card.

The permissions values can be as shown in the following table:

Full addressCountry and postal code
read::alexa:device:all:addressread::alexa:device:all:address:country_and_postal_code

Here is a sample response for a card with a request for a full address.

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "read::alexa:device:all:address"
      ]
    }
  }
}

If the request was for the country and postal code, then the permissions value in this response will be “read::alexa:device:all:address:country_and_postal_code”.

The permissions value will always match the scope that you declared for the skill on the Configuration page in the Amazon Developer Portal.

Test the Device Address API as You Develop Your Skill

The Service Simulator cannot be used to test the Device Address API because it is not a device and cannot provide a deviceId. You can still debug your skill by looking at requests and responses.

To test the case where the customer has provided permissions to your skill, ensure that you have enabled the address permissions for your skill in the Alexa companion app. When you open the skill (“Alexa, open skill_name”), that will cause a LaunchRequest to be sent. If the permissions have been enabled, you can obtain the deviceId and the consentToken from the request.

To test the case where the customer has not provided permissions to your skill, ensure that the address permissions for your skill in the Alexa companion app are not enabled. When you open the skill (“Alexa, open skill_name”), that will cause a LaunchRequest to be sent. This request will contain the deviceId value, but will not contain a consentToken value.

For more information about testing with a device, see: Testing a Custom Skill

For more information about debugging a Node.js skill that uses an AWS Lambda function without a simulator, see: Debugging AWS Lambda Code Locally

After the customer enables your skill, the customer is prompted to consent to providing address information from within the Alexa app, whether that is the full address or the country and postal code.

If the customer does not consent, you are encouraged to include a graceful fallback message in your code.

Your skill can be developed so that some functionality is available without address information being provided, or it can be developed so that no functionality is provided without address information.

Sample Fallback Message If No Functionality Is Provided Without Address Information

“You have refused to allow skill_name access to the address information in the Alexa app. skill_name cannot function without address information. To permit access to address information, enable skill_name again, and consent to provide address information in the Alexa app.”

Sample Fallback Message If Limited Functionality Is Provided Without Address Information

“You have refused to allow skill_name access to the address information in the Alexa app. skill_name will have limited functionality without this information. To permit skill_name to have address information, enable skill_name again, and consent to provide address information in the Alexa app.”

Base URIs and Geographic Location of the Skill

The base URI varies depending on the geographic location of your skill, which is a separate value than the device address of the customer’s Alexa device. You can set the apiEndpoint value in the System object to obtain the appropriate base URI.

  • The base URI for US calls for device address data is: https://api.amazonalexa.com/.
  • The base URI for UK and DE calls for device address data is: https://api.eu.amazonalexa.com

The examples on this page use the US URI.

Get Country and Postal Code

Gets the country and postal code associated with a device specified by deviceId. The endpoint is case-sensitive.

  • Endpoint: /v1/devices/*deviceId*/settings/address/countryAndPostalCode

Request Message Example

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer Atc|MQEWY...6fnLok 
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address/countryAndPostalCode

Request Headers

HeaderDescriptionTypeRequired
AuthorizationA current consent token in the format: Bearer Atc|your consent token| stringyes

Request Parameters

Parameter Description Type Required
deviceId The deviceId to retrieve the country and postal code for string yes

Response

Successful Response Message Example

This example shows a successful response for a request for “Country & Postal Code”.

Host: api.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json
{
  "countryCode" : "US",
  "postalCode" : "98109"
}

Response Headers

Header Description
Content-Type application/json
X-Amzn-RequestId Unique identifier for the request. If problems occur, Amazon can use this value to troubleshoot the problem.

Response Parameters

ParameterDescription>TypeRequired
countryCodeThe two-letter country code where the specified device is located.stringyes
postalCodeThe postal code for the devicestringyes

Possible Responses

Response Description
200 OK Successfully retrieved the country and postal code associated with the deviceId.
204 No Content The query did not return any results.
403 Forbidden The authentication token is invalid or doesn’t have access to the resource.
405 Method Not Allowed The method is not supported.
429 Too Many Requests The skill has been throttled due to an excessive number of requests.
500 Internal Error An unexpected error occurred.

Get Address

Gets the full address associated with the device specified by deviceId.

Endpoint: /v1/devices/*deviceId*/settings/address

Request Message Example

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer Atc|MQEWY...6fnLok 
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address

Request Parameters

Parameter Description Type Required
deviceId The deviceId to retrieve the address for string yes

Successful Response Message Example

Host: api.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json

{
  "stateOrRegion" : "WA",
  "city" : "Seattle",
  "countryCode" : "US",
  "postalCode" : "98109",
  "addressLine1" : "410 Terry Ave North",
  "addressLine2" : "",
  "addressLine3" : "aeiou",
  "districtOrCounty" : ""
}

Response Headers

Header Description
Content-Type application/json
X-Amzn-RequestId Unique identifier for the request. If problems occur, Amazon can use this value to troubleshoot the problem.

Response Parameters

Parameter Description Type Required
stateOrRegion Abbreviation for the state, province or region associated with the device specified in the request. This value may be an empty string for non-US countries. string yes
city The city for the device specified in the request. string yes
countryCode The two-letter country code for the device specified in the request. string yes
addressLine1 The first line of the address. string yes
addressLine2 The second line of the address. string yes, may be empty string
addressLine3 The third line of the address. string yes, may be empty string
districtOrCounty The district or county associated with the device. This value may be an empty string for non-US countries. string yes

Possible Responses

Response Description
200 OK Successfully got the address associated with this deviceId.
204 No Content The query did not return any results.
403 Forbidden The authentication token is invalid or doesn’t have access to the resource.
405 Method Not Allowed The method is not supported.
429 Too Many Requests The skill has been throttled due to an excessive number of requests.
500 Internal Error An unexpected error occurred.

If a Skill asks for Unpermitted Address Information

The customer may grant or reject the request for device address information.

If a skill asks for address information for which the customer has not granted permissions, then the skill will receive an error.

When a Customer Has Granted Permissions for Device Address Information, But Device Address Information is Unavailable

When your skill requests the customer’s device address information, and the customer grants it, this information may still be unavailable, such as if a customer has not provided address information to Alexa. In that case, you may receive specific default values, as described below.

Response in the NA Region When the Customer Has Not Supplied the Device Address Information Or When the Customer is in an Unsupported Country

If the customer has not supplied the device address information or if the postal code is military related, then a default postalCode value of “98109” may be returned.

Response in the EU Region When the Customer Has Not Supplied the Device Address Information

The device address information will be obtained from the customer’s Amazon account settings, if possible. If no information can be obtained, then a null value is returned.

Response In an Unsupported Country that is not in the NA Region

A null value is returned.

Suggested Best Practices When Device Address Information Is Unavailable

As a skill developer, you can determine the appropriate response when your customer does not provide address information.

You can provide a graceful fallback message that indicates the skill cannot function without this information, and end the session.

Alternatively, you can provide a message that indicates that the skill will continue to work, but with reduced functionality compared to having the requested address information.

For a good customer experience, ensure that you consider the skill workflow in all of the scenarios in which you fail to get the desired device address information.

Next Steps

See all coding topics:

Other topics:

Reference materials: