Enhance Your Skill With Address Information

Note: Sign in to the developer console to build or publish your skill.

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.

Note: The address entered in the Alexa device might not represent the current physical address of the device. This API uses the address that the customer entered manually in the Alexa app, and doesn't have any capability of testing for GPS or other location-based data.

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.

Prerequisites

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, Amazon will reject or suspend your submission and notify you at 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 about child-directed skills, see Policy Requirements.
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. You must not associate an Alexa customer to a customer in your account pool with the same address information. A customer's Amazon account information is not verified and may be outdated.
The skill must call the Device Settings REST API to get the latest customer information every time the customer invokes the skill with a request that needs this information.

The requested device information might not be available to your skill when requested. Your skill code should handle missing information gracefully.

Steps to request device address information

To get device address information, perform the following steps:

Configure permission for device address.
Request the device address.
Request customer permission for device address (Optional).
Test as you develop your skill.

Step 1: Configure permission for device address

Follow these steps to configure permissions in the Alexa developer console.

If you use SMAPI or the Alexa Skills Kit Command Line Interface (ASK CLI) instead of the developer console to manage your skill, edit the skill manifest to request the device address permissions. For details about setting permissions in the skill manifest, see permissions.

To configure permission for device address in the Alexa developer console

Navigate back to your skill in the Alexa developer console.
Or, if you closed the skill page, follow these steps to find your skill.
1. Sign in to the Alexa developer console.
2. On the Skills tab, under SKILL NAME, find your skill.
3. Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
Navigate to Build > TOOLS > Permissions.
Select Device Address, and then select either Full Address or Country/Region & Postal Code Only, depending which information your skill uses.

Step 2: Request the device address

Use the Get address and Get country and postal codes operations of the Device Settings REST API to get the address of the customer's device. You include the device ID and access token in these operations.

You can find the apiAccessToken and deviceId values in the context.System object in requests from Alexa as shown in the following example. For the full body of the request, see Request Format.

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

Alexa includes the context.System.apiAccessToken on all requests to your skill, regardless of whether the user granted your skill the permissions needed to fulfill the request for device settings. Therefore, you can't use the presence of apiAccessToken to determine whether you have the necessary permissions. Instead, include the apiAccessToken value in the API request and check the response code. An HTTP 403 Forbidden response indicates that your skill doesn't have the necessary permissions. Make sure that your skill handles the situation gracefully if the customer refuses to grant permission to access contact information.

Note: Don't store the token because it expires. Instead, obtain the apiAccessToken value from each subsequent request.

Step 3: Request customer permission for device address (Optional)

When a customer enables a skill that requires customer permissions, Alexa prompts the customer with a permissions card in the Alexa app. The card asks for consent to provide their address information to your skill. The following image shows an example permissions card for a skill configured for permission to ask for the full address.

Permissions card that says, Allow this skill to access the full postal address configured for your Alexa device. — Permissions card in the Alexa app

If the customer chooses not to grant these permissions during skill enablement, your skill can prompt the customer during the skill session for the permissions required for the skill. You request customer consent by sending a permissions card in the response to Alexa. When you include the AskForPermissionsConsent card in the response, Alexa speaks to the customer to tell them to view the card in the Alexa app or on an Alexa-enabled device with a screen. The voice prompt that your skill provides should describe why the skill needs these permissions. The customer can decide whether to grant the requested permissions.

If possible, you should develop your skill so that some functionality is available without the requested permission and prompt the customer for permissions when needed to fulfill a customer request.

Permission scope

Include the requested permission scope for device address in the permissions card. The permissions value always matches the scope that you declared for the skill on the Build > Permissions page in the developer console.

For details about the permissions card, see Send a card to ask for customer permission.

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.

Permissions card example

The following is a sample response for a card with a request for the full address.

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

Permission events

Use Skill Permission Accepted events in your skill so that your skill is notified when the customer has granted permissions to the skill.

If you want Alexa to notify your skill when the customer grants or revokes permissions, you can subscribe to the following skill events:

Skill permission accepted event – Your skill receives this event when a customer accepts permissions the first time, or grants permissions after revoking all the permissions.
Skill permission changed event – Your skill receives this event when a customer grants additional permissions to a skill, or revokes the existing permissions from a skill.

Skill permissions events for changing or granting permissions always include the most recently accepted permissions in the payload. For details about using skill events, see Skill Events in Alexa Skills.

Step 4: Test as you develop your skill

Before you test your skill, read Test and Troubleshoot Personalization.

You can do limited testing on the Test page in the Alexa developer console, using yourself as the skill user. When you test your skill with the Alexa Simulator, your skill can call the Device Settings API and receive a non-error response that contains your own information. You can also test the flow in which the customer doesn't grant permissions. An actual device is recommended for comprehensive testing.

To test what happens when a customer has provided permissions to your skill, make sure that you have granted the address permissions for your skill in the Alexa app. When you open the skill, Alexa sends a LaunchRequest with the deviceId and apiAccessToken that includes the permission.

To test the case where a customer hasn't provided permissions to your skill, make sure you haven't granted, or that you have revoked, address permissions for your skill in the Alexa app. When you open the skill, Alexa sends a LaunchRequest with the apiAccessToken value that doesn't specify the correct permissions. If your skill passes this token to the Device Settings API, the API returns a HTTP 403 Forbidden status 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.

Best practices when device address is unavailable

As a developer, you can determine the appropriate response when your customer doesn't grant permission or doesn't provide address information. You can provide a graceful fallback message that indicates that the skill can't function without this information, and then end the session. Or, you can provide a message that indicates that the skill continues to work, but with reduced functionality.

Keep in mind the following best practices when address information isn't available:

If possible, develop your skill so that some functionality is available without the requested permissions.
Prompt the customer for permissions only when needed to fulfill a user request. The prompt that your skill provides should describe why the skill needs these permissions.
If the customer doesn't consent to share the information and your skill can't continue without it, provide a graceful fallback message that indicates 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.
Prepare for the situation in which the customer grants consent, but the required information is still unavailable. For example, the customer hasn't provided their address to Amazon. If the requested information is unavailable, the API returns a HTTP 204 No Content status. In this situation, if your skill can't fulfill the request without the address, you might prompt the user to enter this information.
For a good user experience, make sure that you consider the skill workflow for all the scenarios in which you fail to get the desired information.

Sample fallback message for no functionality

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 for limited functionality

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.

FAQ

Having trouble with customer consent? The following frequently asked questions (FAQ) section answers your most common questions.

Q: What happens when the skill asks for address information without customer consent?: 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.
Q: Can a customer grant permissions for device address information, but device address information be unavailable?: When your skill requests the 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.
Q: What's the 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, the response might return a default postalCode value of "98109".
Q: What's the 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 available, the API returns a null value.
Q: What's the response in an unsupported country/region that isn't in the NA region?: The API returns a null value.

Was this page helpful?

Provide feedback

Last updated: Jan 26, 2024