Enhance Your Skill With Address Information

When a customer enables your Alexa skill, your skill can get 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 can provide a list of nearby store locations or provide restaurant recommendations using this address information.

For details about 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 zip code 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 following requirements. 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 Alexa developer console.
  • Your skill must not be a child-directed skill. For details, see Policy Requirements for more information on child-directed skills.
  • You must request permission to receive address information only when required to support the features and services that your skill provides. You must use any personal information that 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

To get device address information, perform the following steps:

  1. Configure your skill to indicate that your skill requires address information.
  2. Get the deviceId and apiAccessToken from the Alexa launch request when a customer invokes the skill.
  3. Send a message to the correct address endpoint that includes the apiAccessToken and deviceId.

Step 1: Configure the skill to request customer permissions for the device address

To configure the skill to request customer permissions for the device address, perform the following steps in the developer console:

  1. Edit your skill in the developer console.
  2. Navigate to the Build > TOOLS > Permissions page.
  3. Select Device Address and either Full Address or Country/Region & Postal Code Only, depending which information your skill uses.

If you configure these permissions, the customer is prompted with a permissions card in the Alexa app to ask for consent to provide their address information when they configure your skill. The following image shows what the customer sees when they're prompted for permissions in the Alexa app. In this example, the skill is configured for permissions to ask for the full address.

Permissions card in the Alexa app
Permissions card in the Alexa app

Step 2: 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 must 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. For the full body of the request, see Request Format.

{
  "context": {
    "System": {
      "apiAccessToken": "12345example",
      "apiEndpoint": "https://api.amazonalexa.com",
      "device": {
        "deviceId": "string-identifying-the-device",
        "supportedInterfaces": {}
      },
      "application": {
        "applicationId": "string"
      },
      "user": {}
    }
  }
}

In the launch request, the deviceId is this.event.context.System.device.deviceId.

When your code requests either "Full Address" or "Country/Region & Postal Code" from the customer, include the following information in the request:

  • 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. The following example shows an authorization header with an access token.

    Authorization: Bearer 12345example

In the launch request, the accessToken is this.event.context.System.apiAccessToken.

Step 3: Send a message to the correct address endpoint that includes the apiAccessToken and deviceId

Use the Get country/region and postal code and Get address operations.

Permission card examples

Alexa includes the apiAccessToken on all requests to your skill, regardless of whether the user granted your skill the permissions needed to fulfill the request. Therefore, you can't use the presence of apiAccessToken to determine whether or not you have the necessary permissions. Instead, call the API and check the response code. A 403 Forbidden response indicates that your skill doesn't have the necessary permissions.

In that case, your skill can display a permissions card to ask customers for consent dynamically. This section shows examples of permission cards.

New permissions card for requesting customer consent

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 an AskForPermissionsConsent card.

You can use the permissions in the following table.

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

The following example shows a 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, the permissions value in this response is "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 Alexa developer console.

Test the device address API as you develop your skill

You can do limited testing by using the Alexa simulator 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 enabled the address permissions for your skill in the Alexa app. When you open the skill ("Alexa, open skill_name"), a LaunchRequest is sent to your skill. If the permissions have been enabled, you can get the deviceId and the apiAccessToken from the request.

To test the case where the customer hasn't provided permissions to your skill, ensure that the address permissions for your skill in the Alexa 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 details about testing with a device, see Test Your Skill.

For details 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 doesn't consent to provide permissions

After the customer enables your skill, the Alexa app prompts the customer to consent to provide their address information. Depending on the skill configuration, this information might be the full address or the country/region and postal code.

Include a graceful fallback message in your code for the case where the customer doesn't consent.

You can develop your skill so that some functionality is available without address information. You can also develop your skill so that no functionality is provided without address information.

Sample fallback message if no functionality is provided without address information

The following utterances show a fallback message when your skill doesn't provide any functionality without address information.

In order to use {Skill_name}, please permit access to your address information. Go to the home screen in your Alexa app and grant the permissions to continue.

Afin d'utiliser {Skill_name}, veuillez autoriser l'accès à votre adresse. Allez à l'écran d'accueil de votre application Alexa et accordez les autorisations pour continuer.

Um {Skill_name} nutzen zu können, erlaube bitte den Zugriff auf deine Adressinformationen. Gehe auf die Startseite in deiner Alexa-App und erteile die Berechtigung um Fortzufahren.

{Skill_name}का उपयोग करने के लिए, कृपया अपनी पता जानकारी तक पहुंच की अनुमति दें। अपने एलेक्सा ऐप में होम स्क्रीन पर जाएं और जारी रखने की अनुमति दें

Per poter utilizzare {Skill_name}, consenti l'accesso alle informazioni sul tuo indirizzo. Vai alla schermata iniziale della tua app Alexa e concedi le autorizzazioni per continuare.

{スキル名}を使用するには、位置情報へのアクセスを許可する必要があります。続行するにはAlexaアプリのホーム画面でスキルに権限を付与してください。

Para usar {Skill_name}, por favor, permita o acesso às informações de seu endereço. Vá para a tela inicial em seu aplicativo Alexa e conceda as permissões para continuar.

Para usar {Skill_name}, por favor permita acceder a la información de su dirección. Vaya a la pantalla de inicio en su aplicación Alexa y otorgue los permisos para continuar.

Sample fallback message if limited functionality is provided without address information

The following utterances show a fallback message when your skill only provides limited functionality without address information.

In order to complete this functionality, {Skill_name} needs access to your address information. Go to the home screen in your Alexa app and grant the permissions to continue.

Afin de compléter cette fonctionnalité, {Skill_name} a besoin d'accéder à votre adresse. Allez à l'écran d'accueil de votre application Alexa et accordez les autorisations pour continuer.

Um diese Funktion ausführen zu können, benötigt {Skill_name} Zugriff auf deine Adressdaten. Gehe zum Startbildschirm in deiner Alexa-App und erteile die Berechtigung um fortzufahren.

इस कार्यक्षमता को पूरा करने के लिए, {Skill_name} को आपकी पता जानकारी तक पहुंच की आवश्यकता है। अपने एलेक्सा ऐप में होम स्क्रीन पर जाएं और जारी रखने की अनुमति दें।

Per completare questa funzionalità, {Skill_name} deve accedere alle informazioni sul tuo indirizzo. Vai alla schermata iniziale della tua app Alexa e concedi le autorizzazioni per continuare.

この機能を完了するには、{スキル名}がデバイスの位置情報にアクセスする必要があります。続行するにはAlexaアプリのホーム画面でスキルに権限を付与してください。

Para completar esta funcionalidade, {Skill_name} precisa ter acesso às informações de seu endereço. Vá para a tela inicial em seu aplicativo Alexa e conceda as permissões para continuar.

Para completar esta funcionalidad, {Skill_name} necesita acceso a la información de tu dirección. Ve a la pantalla de inicio en tu aplicación Alexa y otorga los permisos para continuar.

API reference

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. That is, the API endpoint is 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 on this page use the US endpoint (https://api.amazonalexa.com/).

For details about configuring your skill for multiple languages, see Develop 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 12345example
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address/countryAndPostalCode
Request headers
HeaderDescriptionTypeRequired
Authorization A current access token in the format: Bearer your access token string yes
Request parameters
Parameter Description Type Required
deviceId The deviceId for which to retrieve the country/region and postal code. string Yes

Response

Successful response message example

The following 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
ParameterDescription>TypeRequired
countryCodeThe two-letter country/region code where the specified device is located.stringyes
postalCodeThe postal code for the device.stringYes
Possible responses
Response Description
200 OK Successfully retrieved the country/region and postal code associated with the deviceId.
204 No Content The query didn't return any results.
403 Forbidden The authentication token is invalid or doesn't have access to the resource.
404 Not Found The given URI isn't able to locate a resource, for example because the deviceId isn't valid.
405 Method Not Allowed The method isn't 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 the deviceId.

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

Request message example

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer 12345example
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address
Request parameters
Parameter Description Type Required
deviceId The deviceId for which to retrieve the address. 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. For non-US countries, this value might be an empty string. 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. This value might be an empty string. string Yes
addressLine3 The third line of the address. This value might be an empty string. string Yes
districtOrCounty The district or county associated with the device. This value might 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 didn't return any results.
403 Forbidden The authentication token is invalid or doesn't have access to the resource.
405 Method Not Allowed The method isn't supported.
429 Too Many Requests The skill has been throttled due to an excessive number of requests.
500 Internal Error An unexpected error occurred.

What happens when the skill asks for unpermitted address information

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

If a skill asks for address information for which the customer hasn't granted permissions, the skill receives 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 might still be unavailable. For example, a customer might not have provided address information to Alexa. In that case, you might receive specific default values, as described in the following sections.

Response in the NA region when the customer hasn't supplied the device address information or when the customer is in an unsupported country/region

If the customer hasn't supplied the device address information or if the postal code is military-related, a default postalCode value of "98109" might be returned.

Response in the EU region when the customer hasn't supplied the device address information

The device address information is obtained from the customer's Amazon account settings, if possible. If no information is obtained, a null value is returned.

Response in an unsupported country/region that isn't in the NA region

A null value is returned.

Best practices when device address information is unavailable

As a skill developer, you can determine the appropriate response when your customer doesn't provide address information.

You can provide a graceful fallback message that indicates that the skill can't 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.

Was this page helpful?

Last updated: Apr 20, 2023