AMP
RU
English Français العربية Español Italiano Indonesia 日本語 한국어 Português Türkçe 中文

amp-user-location

Description Requests the user's location and provides it to AMP components.
Availability Experimental. 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 Layouts nodisplay

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

id (required)

The id attribute is required and allows the component to be referenced in AMP Actions and Events.

src (optional)

The src attribute specifies a remote configuration for the amp-user-location component.

<amp-user-location
  id="location"
  src="https://www.example.com/amp-user-location.json"
  layout="nodisplay"
></amp-user-location>

Alternatively, a local configuration can be specified in a script tag.

<amp-user-location id="location" layout="nodisplay">
  <script type="application/json">
    {
      "fallback": {"lat": 40, "lon": -40},
      "maximumAge": 60000,
      "timeout": 5000
    }
  </script>
</amp-user-location>

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

Event Description
approve This 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.
deny This 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.
error This 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