Use Location Services for Alexa Skills

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

With location services, your skill can ask a user for permission to get the real-time location of the user's Alexa-enabled device at the time of the user's request to Alexa. The location is represented by geo-coordinates (including latitude, longitude, altitude, and so on), that you can use as proxies for the location of mobile devices like smartphones and in-car navigation systems.

When a user enables a skill that's configured to use location services, the Alexa app prompts the user to consent to share their location data with your skill. The user can visit the Alexa Privacy Settings page in the Alexa app at any time to manage their skill permissions.

If you want to enable the user to verbally consent to share their location information with your skill, see Use Voice-Forward Consent in Your Alexa Skill.

How location services work

The following figure shows how location services coordinate between Alexa, the user's device, and your skill.

Requirements to use location services

Any skill that uses location information must meet the following requirements.

Note: If Amazon determines that your skill violates any of these requirements, we might reject or suspend your submission and notify you at the email address associated with your developer account.

On the Distribution page of the developer console, you must include a link to the Privacy Policy that applies to your skill.
Your skill must not be a child-directed skill. For details about child-directed skills, see Child-Directed Alexa skills.
You must request permission to receive location information only when required to support the features and services provided by your skill.
You must only use any personal information that you request as permitted by the user and in accordance with your privacy notice and applicable law.
You must not use location information, or other user information, to link the user's account in the background. That is, you must not associate an Alexa user to a user in your account pool with the same location information. Users' Amazon account information isn't verified and might be outdated.
Your skill must get the latest location information every time the user invokes your skill with a request that requires location information, and your skill must overwrite the prior location data it had from the user's previous request. That is, your skill must store only the most recent data.

Device address compared to geo-coordinates

The device address, such as "585 Broadway", isn't the same as device geo-coordinates. Mobile devices can move around, so a mobile device's current location likely varies considerably from its registered device address. For stationary devices like the Amazon Echo, Alexa can provide you the device's physical address with the Device Settings API. Stationary devices don't provide geo-coordinate data through location services.

For mobile devices, your skill should use location services instead of the Device Settings API for the device's current location, with a few exceptions. For a pizza delivery skill, you might want to use the actual device address, not geo-coordinates, so that you can deliver the pizza to a precise location. For local search or navigation skills, geo-coordinates are more useful than the device address, because the user's current location might be different than their home address.

Configure your skill to use location services

To configure your skill to use location services, perform the following steps:

Enable location services permissions.
Modify your skill service logic to handle location services data.
Test your skill to ensure location services works as expected.

Step 1: Enable location services permissions

You must enable permissions for location services. This configuration informs Alexa that your skill wants to use dynamic user location. If your skill is configured for location services, and the user's permissions allow, Alexa passes on the user's location inside the Service Provider Interface (SPI).

To enable permissions for location services

Sign in to the Alexa developer console and navigate to your skill.
On the left, click Tools, and then click Permissions.
Enable Location Services.
Note: If you don't enable Location Services, your skill doesn't receive user location data.

Location services permissions enabled in the developer console

Step 2: Modify your skill service logic to handle location services data

Inside the source code for your skill, you can find user location data in the custom skills context, which is a JSON object that Alexa sends to your AWS Lambda function or to your web service. The data is in the geolocation section of the context object, at context.Geolocation.

The following code example prints the geo-coordinates of the user's device.

var isGeoSupported = context.System.device.supportedInterfaces.Geolocation;
var geoObject = context.Geolocation;
if (isGeoSupported) {
   var ACCURACY_THRESHOLD = 100; // Accuracy of 100 meters required
   if (geoObject && geoObject.coordinate && geoObject.coordinate.accuracyInMeters < ACCURACY_THRESHOLD ) {
      console.log(geoObject);  // Print the geo-coordinates object if accuracy is within 100 meters
   }
}

Only users who are using an Alexa-enabled device with its own location services can share their geo-coordinates with your skill, assuming the proper permissions have been granted. To determine whether the user's device can share its location, check whether the context.System.device.supportedInterfaces object has a Geolocation field.

If the Geolocation field isn't present, the user's device is unable to provide any location data, which is the case for stationary devices like the Amazon Echo. In that case, your skill should provide a user experience that doesn't require the user's location like prompting the user that you are unable to receive user's real-time location.

The following code shows an example Geolocation object.

Note: A coordinate object must contain latitudeInDegrees, longitudeInDegrees, and accuracyInMeters, whereas altitude, heading, and speed are optional objects for the device to share with Alexa. As a result, these optional fields might not be available to skills.

For details about each property, see Geolocation object properties.

Step 3: Test your skill

After you write your skill logic to handle geo-coordinates, you can start testing with a mobile device like the Alexa app.

Note: The Alexa Simulator doesn't support testing for location services.

Important: Before you test your skill, make sure that you granted the required permissions for your skill in the Alexa app.

The user location, if available, is passed to your skill with each user utterance. In the following exchange, the user location is sent twice to Alexa. If the user is in motion, each utterance might contain different user location data. Location services don't support real-time streams of location data.

The following example shows a test dialog.

User: Alexa, take me to the nearest coffee shop.

Skill: Providing directions to Example Coffee Shop at 2008 Pine Street.

User: Alexa, where's the nearest movie theater?

Skill: The nearest movie theater is at 1100 Pike Street.

The geo-coordinate information comes from the hardware device, which uses its own location services to get this data. Alexa doesn't control the source of this data, such as whether it comes from GPS or is IP-derived. Therefore, Alexa doesn't control the granularity nor the accuracy of user location data that's sent to a skill. However, a mobile device with Alexa must provide accuracy metrics (in the form of accuracy in meters, context.Geolocation.coordinates.accuracyInMeters) so that skills can decide whether the level of accuracy is sufficient for the desired use within your skill.

Geolocation object properties

Parameter	Description	Type	Required
`locationServices`	Property that indicates whether location sharing is turned on in the user's device. Note: The `Geolocation` object must contain either the `locationServices` object or the `coordinate` object.	Object	No
`locationServices.access`	Property that indicates whether location sharing access is enabled or disabled. One of: `"ENABLED"`, `"DISABLED"`.	Enum string	Yes, if `locationServices` is present
`locationServices.status`	Status of location sharing. One of: `"RUNNING"`, `"STOPPED"`. If `locationServices.access` is set to `"ENABLED"` and `locationServices.status` is set to `"RUNNING"`, location sharing access is enabled and running.	Enum string	Yes, if `locationServices` is present
`timestamp`	Device time when GPS data was updated in the device in ISO 8601 (preferably RFC 3339) format. Example: `2016-09-09T21:28:45+00:00`.	XYZ	Yes
`coordinate`	Coordinates of the device. Note: The `Geolocation` object must contain either the `locationServices` object or the `coordinate` object.	Object	Yes, if `locationServices` isn't present
`coordinate.latitudeInDegrees`	Degrees from equator. Range: [-90.0, 90.0].	Double	Yes, if `coordinate` is present.
`coordinate.longitudeInDegrees`	Degrees from prime meridian. Range: [-180.0, 180].	Double	Yes, if `coordinate` is present.
`coordinate.accuracyInMeters`	Uncertainty in the latitude and longitude in meters. Range: [0, MAX_INTEGER].	Double	Yes, if `coordinate` is present.
`altitude`	Meters above sea level within GPS limits. Range: [-6350, 18000].	Double	No
`altitude.altitudeInMeters`	Meters above sea level within GPS limits. Range: [-6350, 18000].	Double	No
`altitude.accuracyInMeters`	Uncertainty in the altitude in meters. Range: [0, MAX_INTEGER].	Double	No
`heading`	Heading of the device.	Object	No
`heading.directionInDegrees`	Degrees from true north. Range: (0.0, 360.0].	Double	No
`heading.accuracyInDegrees`	Accuracy parameter for direction. Range: [0, MAX_INTEGER].	Double	No
`speed`	Speed of the device.	Object	No
`speed.speedInMetersPerSecond`	Meters per second within GPS limits. Range: [0, 1900].	Double	No, except for automotive (through contract)
`speed.accuracyInMetersPerSecond`	Accuracy parameter for speed. Range: [0, MAX_INTEGER].	Double	No

Implementation

The following sections describe how to implement the following actions in your skill code:

Check freshness and accuracy of data.
Request user consent for getting permissions in runtime.
Detect which specific permissions are needed.
Detect if location sharing is off on the mobile device.

Check freshness and accuracy of data

You must check both the freshness and accuracy of the location data prior to using this data in your skill. User location can change quickly, such as when a user is driving, which makes 10-minute-old GPS data highly imprecise.

To check for freshness, look at the difference between Geolocation.timestamp and the timestamp of your IntentRequest (request.timestamp). If this difference is small, the data is fresh. The Geolocation.timestamp value is the time when the user location was measured inside the device. The request.timestamp value is roughly the current time when your skill is invoked.

By combining the freshness and accuracy check, you can create logic to determine whether the location data is usable. The following code tests for data with a desired accuracy of 100 meters and freshness of one minute.

var isGeoSupported = context.System.device.supportedInterfaces.Geolocation;
var geoObject = context.Geolocation;
if (isGeoSupported) {
	var freshness = ( new Date(request.timestamp) - new Date(geoObject.timestamp) ) / 1000; // freshness in seconds
	var ACCURACY_THRESHOLD = 100; // accuracy of 100 meters required
                if ( geoObject && geoObject.coordinate && geoObject.coordinate.accuracyInMeters < ACCURACY_THRESHOLD && freshness < 60 ) {
                          //  your code here
                }
}

The Geolocation object might be missing geo-coordinates data, which you can check by testing to see if context.Geolocation is null. If so, context.Geolocation can be null due to the following three reasons, assuming you enabled Location Services in the developer console.

Case 1 – The user's device is stationary, such as an Amazon Echo, or it is not set up to send its location to Alexa. In this case, the device's coordinates are unavailable by default, because it is not a valid mobile device. To see if Case 1 applies, check the context.System.device.supportedInterfaces.Geolocation field to see if it is set to true, as shown in the previous code example. If Case 1 doesn't apply, proceed to test Case 2.
Case 2 – The user has not opted in to share location with your skill. In this case, consider resolving this issue by asking the user for permissions using the AskForPermissionsConsent card. To test for Case 2, ask for the user to provide permissions to get location information for Alexa or your skill. To ask the user, return the AskForPermissionsConsent card as a response. This card sends an instruction card to the user's Alexa app, and the card contains instructions which tell how to turn on location sharing for Alexa or for your skill.
Case 3 – The user's hardware has location sharing turned off or the user has not opted to share location with Alexa. For example, the location services on the user's device, such as a mobile phone, might be turned off. In this case, consider asking the user to turn on location sharing with Alexa.

Two or more of the cases might apply at the same time. For example, the user might not have granted location sharing permissions for your skill, and the device's location sharing might also be turned off.

The following example code returns a response that generates an AskForPermissionsConsent card for a hypothetical skill called Ride Hailer. We recommend the use of the Alexa Skills Kit SDK for Node.js to simplify the response creation, as shown here.

var isGeolocationSupported = context.System.device.supportedInterfaces.Geolocation;
if ( isGeolocationSupported ) {   //  does the device support location based features?
        var geoObject = context.Geolocation;
        if ( ! geoObject || ! geoObject.coordinate ) {
          return responseBuilder
            .speak('Ride Hailer would like to use your location. To turn on location sharing, please go to your Alexa app, and follow the instructions.')
            .withAskForPermissionsConsentCard(['alexa::devices:all:geolocation:read'])
            .getResponse();
        } else {
          // use location data
        }
}

The response has two sections: card and outputSpeech. The card's type is AskForPermissionsConsent, which indicates to Alexa what kind of instruction card to send to the user. This card enables you to specify a list of permissions scopes inside the permissions list. For location permissions, your skill must pass alexa::devices:all:geolocation:read as part of the list of permissions.

Along with sending the instruction card, your skill must specify what Alexa says to the user. The following examples ask the user for permission to share their location with your skill.

{Skill_name} wil graag je locatie gebruiken. Ga naar je Alexa-app en volg de instructies om locatiedeling in te schakelen.

{Skill_name} would like to use your location. To turn on location sharing, please go to your Alexa app, and follow the instructions.

{Skill_name} souhaite utiliser votre position. Pour activer le partage de position, veuillez accéder à votre application Alexa et en suivre les instructions.

{Skill_name} möchte deinen Standort verwenden. Um die Standortfreigabe zu aktivieren, gehe zu deiner Alexa-App und folge den Anweisungen.

{Skill_name} आपके स्थान का उपयोग करना चाहेंगे। स्थान साझाकरण चालू करने के लिए, कृपया अपने एलेक्सा ऐप पर जाएं और निर्देशों का पालन करें।

{Skill_name} vorrebbe utilizzare la tua posizione. Per attivare la condivisione della posizione, vai alla tua app Alexa e segui le istruzioni.

{Skill_name} <スキル名＞は、お客様の位置情報を使用します。位置情報の共有を有効にするには、Alexaアプリに移動し、指示に従って操作してください。

{Skill_name} gostaria de usar sua localização. Para compartilhar sua localização, vá até seu aplicativo Alexa, e siga as instruções.

{Skill_name} quisiera usar tu ubicación. Para dar permiso a compartir tu ubicación, ve a tu aplicación Alexa y sigue las instrucciones.

Put your speech in the outputSpeech section of the response. Without verbal cues, the user will likely assume your skill is in an error state.

After this response is returned, the following sequence of events occurs:

The user hears "Ride Hailer would like to use your location. To turn on location sharing, please go to your Alexa app, and follow the instructions".
Alexa independently verifies whether there are missing permissions for location sharing to happen.
Alexa sends a home card with instructions for turning on location sharing, and the session terminates.

Depending on which permissions are missing, Alexa will send different instructional cards to the user's Alexa app. If your skill has permission to use the user's location, but Alexa doesn't, the content of the card differs from when your skill doesn't have permission to use the user's location.

If, however, neither Alexa nor your skill has the user's permission, the following instructional card is created.

4. After the user takes the actions instructed in the card and retries using your skill, the context.Geolocation object should contain a valid coordinates object.

Amazon can receive device location	Skill can receive location from Amazon	Skill location access	Skill action
TRUE	TRUE	YES	None
TRUE	FALSE	NO	Permission card to request location permissions
FALSE	TRUE	NO	Ask the user to turn on location sharing to Alex
FALSE	FALSE	NO	Permission card to request location permissions

Detect which specific permissions are needed

As previously described, you can determine whether your skill and Alexa each has permissions to access device location. Your skill can use this information to further customize your speech when the AskForPermissionsConsent card is returned.

To determine whether your skill has permissions to read location, check the value in context.System.user. This object contains metadata about the current user, including the permissions.scopes object, which tracks the set of permissions the user has granted to your skill. You can inspect the values for each individual scope, such as scopes['alexa::devices:all:geolocation:read'].status, which should be "GRANTED" if your skill has permissions.

If you want your skill to throw the instructions card only when your skill is lacking permissions, use code similar to the following:

if ( isGeolocationSupported ) {   // Does the device support location based features?
	var geoObject = context.Geolocation;
	if ( ! geoObject || ! geoObject.coordinate ) {
var skillPermissionGranted = context.System.user.permissions.scopes['alexa::devices:all:geolocation:read'].status === "GRANTED";
if ( !skillPermissionGranted) {
	// Return the AskForPermissionsConsent card here
	...

If the skill permissions are present, but geolocation data is not available in the request, your skill should re-prompt the user.

If Case 1 and Case 2 don't apply, consider Case 3, where your skill is having trouble getting device location despite no permissions issues with Alexa or your skill. In this case, check whether the user's device has location sharing turned on, or if there are some other technical issues. For example, the user might be driving inside a tunnel, leading to loss of GPS reception.

To check whether the device has location services turned on, inspect the locationServices object inside context.Geolocation. The purpose of this object, if it exists, is to tell you whether the device is sharing location or not. However, note that the locationServices object might not be available if the user device did not provide it.

If context.Geolocation.locationServices.access is "ENABLED" and context.Geolocation.locationServices.status is "RUNNING", the device is sharing location. Otherwise, the device is not set up to share location.

If location sharing is turned on, but your skill doesn't receive device location, you should let the user know about that, with a message like "Ride Hailer is having trouble accessing your location. Please wait a moment, and try again later."

If location sharing is turned off, however, your skill can request the user to turn on location sharing on his or her device, with a message like "Ride Hailer is having trouble accessing your location. Please go to your device's settings to turn on location sharing, and try again."

Was this page helpful?

Provide feedback

Last updated: Aug 23, 2024