Geolocation API

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 inside Geolocation, inside a success callback, and contains a timestamp plus a GeolocationCoordinates 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 inside Geolocation, inside an error callback, and contains an error code and message.

Extensions to other interfaces

Navigator.geolocation

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

Browser compatibility

Availability

As Wi-Fi-based locating is often provided by Google, the vanilla Geolocation API may be unavailable in China. You may use local third-party providers such as Baidu, Autonavi, or Tencent. These services use the user's IP address and/or a local app to provide enhanced positioning.

See also

• Using the Geolocation API
• Who moved my geolocation? (Hacks blog)