Geolocation API
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The Geolocation API allows the user to provide their location to web applications if they so desire. For privacy reasons, the user is asked for permission to report location information.
WebExtensions that wish to use the Geolocation
object must add the "geolocation"
permission to their manifest. The user's operating system will prompt the user to allow location access the first time it is requested.
Concepts and usage
You will often want to retrieve a user's location information in your web app, for example to plot their location on a map, or display personalized information relevant to their location.
The Geolocation API is accessed via a call to navigator.geolocation
; this will cause the user's browser to ask them for permission to access their location data. If they accept, then the browser will use the best available functionality on the device to access this information (for example, GPS).
The developer can now access this location information in a couple of different ways:
Geolocation.getCurrentPosition()
: Retrieves the device's current location.Geolocation.watchPosition()
: Registers a handler function that will be called automatically each time the position of the device changes, returning the updated location.
In both cases, the method call takes up to three arguments:
- A mandatory success callback: If the location retrieval is successful, the callback executes with a
GeolocationPosition
object as its only parameter, providing access to the location data. - An optional error callback: If the location retrieval is unsuccessful, the callback executes with a
GeolocationPositionError
object as its only parameter, providing access information on what went wrong. - An optional object which provides options for retrieval of the position data.
For further information on Geolocation usage, read Using the Geolocation API.
Interfaces
Geolocation
-
The main class of this API — contains methods to retrieve the user's current position, watch for changes in their position, and clear a previously-set watch.
GeolocationPosition
-
Represents the position of a user. A
GeolocationPosition
instance is returned by a successful call to one of the methods contained insideGeolocation
, inside a success callback, and contains a timestamp plus aGeolocationCoordinates
object instance. GeolocationCoordinates
-
Represents the coordinates of a user's position; a
GeolocationCoordinates
instance contains latitude, longitude, and other important related information. GeolocationPositionError
-
A
GeolocationPositionError
is returned by an unsuccessful call to one of the methods contained insideGeolocation
, inside an error callback, and contains an error code and message.
Extensions to other interfaces
-
The entry point into the API. Returns a
Geolocation
object instance, from which all other functionality can be accessed.
Security considerations
The Geolocation API allows users to programmatically access location information in secure contexts.
Access may further be controlled by the Permissions Policy directive geolocation
.
The default allowlist for geolocation
is self
, which allows access to location information in same-origin nested frames only.
Third party usage is enabled by setting a Permissions-Policy
response header to grant permission to a particular third party origin:
Permissions-Policy: geolocation=(self b.example.com)
The allow="geolocation"
attribute must then be added to the iframe element with sources from that origin:
<iframe src="https://b.example.com" allow="geolocation"/></iframe>
Geolocation data may reveal information that the device owner does not want to share.
Therefore, users must grant explicit permission via a prompt when either Geolocation.getCurrentPosition()
or Geolocation.watchPosition()
is called (unless the permission state is already granted
or denied
).
The lifetime of a granted permission depends on the user agent, and may be time based, session based, or even permanent.
The Permissions API geolocation
permission can be used to test whether access to use location information is granted
, denied
or prompt
(requires user acknowledgement of a prompt).
Examples
See Using the Geolocation API for example code.
Specifications
Specification |
---|
Geolocation # geolocation_interface |
Browser compatibility
BCD tables only load in the browser