AMP

amp-user-location

DescriptionRequests the user's location and provides it to AMP components.
AvailabilityExperimental. The `amp-user-location` experiment must be enabled to use this component.
Required Script<script async custom-element="amp-user-location" src="https://cdn.ampproject.org/v0/amp-user-location-0.1.js"></script>
Supported Layoutsnodisplay

Behavior

The amp-user-location component can be used in combination with other components to send the user's location as part of other AMP components' requests. For example, to send the user's location with a form or an analytics request, the Variable Substitution variables can be used.

Attributes

The amp-user-location component only requires an id attribute.

AMP Actions

amp-user-location exposes the request action. This action is required to send the user's location to another AMP component. This will cause the browser to prompt the user to approve location access for the current domain, if the user has not already.

<button on="tap: location.request()">Use my location</button>
<amp-user-location id="location" on="approve:…" layout="nodisplay">
</amp-user-location>

AMP Events

amp-user-location exposes the following events

EventDescription
approveThis event is fired when the user triggers the `request` action and then approves the browser prompt to access their location, or the user has previously approved the prompt. The `event` object contains `lat` `lon` and `source` properties.
denyThis event is fired when the user triggers the `request` action and then denies the browser prompt to access their location, or the user has previously denied the prompt.
errorThis event is fired when the user triggers the `request` action and and error occurs. This can happen if the browser takes too long to retrieve the location information, if the hardware is unavailable, or other errors occur.

Variable Substitution

The user's location is also available via AMP variable substitution:

AMP_USER_LOCATION or ${ampUserLocation} returns the latitude and longitude separated by a comma. AMP_USER_LOCATION(LAT) or ${ampUserLocation(LAT)} returns the latitude. AMP_USER_LOCATION(LON) or ${ampUserLocation(LON)} returns the longitude. AMP_USER_LOCATION(SOURCE) or ${ampUserLocation(SOURCE)} returns the source. The source may be one of debug, fallback, geolocation, unavailable, or unsupported.

The AMP_USER_LOCATION_POLL or ${ampUserLocationPoll} substitution is also available with the same syntax as above. It will wait for the location to be requested before resolving, and will prevent a request from occurring until that time. Polling is useful when the location is required for the request.

Validation

See amp-user-location rules in the AMP validator specification.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub