Enhance Your Skill With Address Information
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.
For information on how to request customer contact information including name, email address, and phone number, see Request Customer Contact Information for Use in Your Skill.
If you want to enable the user to verbally consent to share their Alexa device's address with your skill, see Use Voice-Forward Consent in Your Alexa Skill.
Before you begin
To protect customer data, any skill that uses device address information must meet the requirements below. If Amazon determines that your skill violates any of these requirements, we will reject or suspend your submission and notify you using the email address associated with your developer account.
- You must include a link to the Privacy Policy that applies to your skill, on the Distribution page of the developer console.
- Your skill must not be a child-directed skill. See here for more information on child-directed skills.
- You must request permission to receive address information only when required to support the features and services provided by your skill. You must use any personal information you request only as permitted by the user and in accordance with your privacy notice and applicable law.
- You must not use device address information to link the customer's account in the background. That is, you must not associate an Alexa customer to a customer in your account pool with the same address information.
- The skill must call the Device Address API to get the latest customer information every time the customer invokes the skill with a request that needs this information.
Steps to Get Customer Permission and Device Address Information
The steps to get device address information are as follows:
-
Configure your skill in the developer console 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 - Obtain the
deviceId
andapiAccessToken
from the Alexa launch request message when a customer invokes the skill. - Send a message to the correct address endpoint that includes the
apiAccessToken
anddeviceId
, as described in Get Country/Region and Postal Code and Get Address.
Configure the Skill to Request Customer Permissions for the Device Address
- Edit your skill in the developer console.
- Navigate to the Build > TOOLS > Permissions page.
- Select Device Address, and either Full Address or Country/Region & Postal Code Only, depending which your skill uses.
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 "Full Address" or "Country/Region & Postal Code".
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 either "Full Address" or "Country/Region & Postal Code" from the customer, 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
consentToken
within session.user.permissions
and context.System.user.permissions
. This property is deprecated. Existing skills that use consentToken
continue to work, but the context.System.apiAccessToken
property should be used instead. New Permissions Card for Requesting Customer Consent
The apiAccessToken
is included on all requests to your skill, regardless of whether the user granted your skill the permissions needed to fulfill the request. Therefore, the token may not contain the right set of permissions for your skill to fulfill the request. Your skill can display a special permissions card to ask customers for consent dynamically.
New Card | AskForPermissionsConsentCard |
---|---|
Interface | CardRenderer |
Definition |
|
Attributes | permissions : 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. |
Because apiAccessToken
is included in all skill requests, you cannot use the presence of apiAccessToken
to determine whether or not you have the needed permissions. Instead, call the API and check the response code. A 403 Forbidden
response indicates that your skill does not have the permissions, so at that point you can include the AskForPermissionsConsent
card in your response to Alexa.
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 address | Country/Region and postal code |
---|---|
read::alexa:device:all:address | read::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/region 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 Build > Permissions page in the Amazon Developer Portal.
Test the Device Address API as You Develop Your Skill
You can do limited testing on the Test page in the developer console. When testing with the Alexa Simulator, your skill can call the Device Address API and get back a non-error response. You can also test the flow when the user has not provided the device address permission.
However, note that the address fields in the response are set to null
and the postal code field is set to a default US postal code.
The Test page cannot be configured as a full device in the Alexa app. An actual device is recommended for comprehensive testing.
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 apiAccessToken
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 and the apiAccessToken
value, but the apiAccessToken
will not specify the correct permissions. Passing this token to the Device Address API will return a 403 Forbidden
response code.
For more information about testing with a device, see: Test Your 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
Fallback Message When Customer Does Not Consent to Provide Permissions
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/region 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, 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 endpoint for the Device Address API varies depending on the geographic location of your skill. You can get the correct base URL to use from the apiEndpoint
value in the System
object: context.System.apiEndpoint
:
{
"version": "1.0",
"session": {},
"context": {
"System": {
"application": {
"applicationId": "amzn1.ask.skill.<skill-id>"
},
"user": {},
"apiAccessToken": "AxThk...",
"apiEndpoint": "https://api.amazonalexa.com"
}
},
"request": {}
}
The examples in this document use the US endpoint (https://api.amazonalexa.com/
).
For more about configuring your skill for multiple languages, see [Develop Skills in Multiple Languages][developing-skills-in-multiple-languages].
Get Country/Region and Postal Code
Gets the country/region 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 MQEWY...6fnLok
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address/countryAndPostalCode
Request Headers
Header | Description | Type | Required |
---|---|---|---|
Authorization |
A current access token in the format: Bearer your access token |
string |
yes |
Request Parameters
Parameter | Description | Type | Required |
---|---|---|---|
deviceId |
The deviceId to retrieve the country/region and postal code for |
string |
yes |
Response
Successful Response Message Example
This example shows a successful response for a request for "Country/Region & 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 a problem occurs, Amazon can use this value to troubleshoot the problem. |
Response Parameters
Parameter | Description> | Type | Required |
---|---|---|---|
countryCode | The two-letter country/region code where the specified device is located. | string | yes |
postalCode | The postal code for the device | string | yes |
Possible Responses
Response | Description |
---|---|
200 OK | Successfully retrieved the country/region 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. |
404 Not Found | The given URI is not able to locate a resource, for example because the deviceId is not valid. |
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 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 a problem occurs, 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/region 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/Region
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/Region 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.
Last updated: Mar 31, 2022