Geolocation Sensor

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Devices and Sensors Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). When sending e-mail, please put the text “geolocation-sensor” in the subject, preferably like this: “[geolocation-sensor] …summary of comment…”. All comments are welcome.

This document is a First Public Working Draft.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 February 2018 W3C Process Document.

1. Introduction

The GeolocationSensor API extends the Sensor interface [GENERIC-SENSOR] to provide information about the geolocation of the hosting device.

The feature set of the GeolocationSensor is similar to that of the Geolocation API [GEOLOCATION-API], but it is surfaced through a modern API that is consistent across contemporary sensor APIs, improves security and privacy, and is extensible. The API aims to be polyfillable (example) on top of the existing Geolocation API.

2. Examples

Get a new geolocation reading every second:

let geo = new GeolocationSensor({ frequency: 1 });
geo.start();

geo.onreading = () => console.log(`lat: ${geo.latitude}, long: ${geo.longitude}`);

geo.onerror = event => console.error(event.error.name, event.error.message);

Get a one-shot geolocation reading:

GeolocationSensor.read()
  .then(geo => console.log(`lat: ${geo.latitude}, long: ${geo.longitude}`))
  .catch(error => console.error(error.name));

3. Security and Privacy Considerations

Note: Investigate any geolocation-specific security and privacy considerations that are not mitigated by the Generic Sensor API [GENERIC-SENSOR], and define geolocation-specific mitigations.

4. Model

The term geolocation refers to the real-world geographic location of the hosting device represented in geographic coordinates [WGS84].

Note: An implementation can use multiple location information sources to acquire geolocation information, and this specification is agnostic with respect to those sources.

The Geolocation Sensor sensor type’s associated Sensor subclass is the GeolocationSensor class.

The Geolocation Sensor has an associated PermissionName which is "geolocation".

A latest geolocation reading is a latest reading for a Sensor of Geolocation Sensor sensor type. It includes entries whose keys are "latitude", "longitude", "altitude", "accuracy", "altitudeAccuracy", "heading", "speed" and whose values contain device’s geolocation.

Note: Consider adding a visual of the standard coordinate system for the Earth.

5. API

5.1. The GeolocationSensor Interface

[Constructor(optional GeolocationSensorOptions options), SecureContext, Exposed=Window]
interface GeolocationSensor : Sensor {
  static Promise<GeolocationSensorReading> read(optional ReadOptions readOptions);
  readonly attribute unrestricted double? latitude;
  readonly attribute unrestricted double? longitude;
  readonly attribute unrestricted double? altitude;
  readonly attribute unrestricted double? accuracy;
  readonly attribute unrestricted double? altitudeAccuracy;
  readonly attribute unrestricted double? heading;
  readonly attribute unrestricted double? speed;
};

dictionary GeolocationSensorOptions : SensorOptions {
  // placeholder for GeolocationSensor-specific options
};

dictionary ReadOptions : GeolocationSensorOptions {
  AbortSignal? signal;
};

dictionary GeolocationSensorReading {
  DOMHighResTimeStamp? timestamp;
  double? latitude;
  double? longitude;
  double? altitude;
  double? accuracy;
  double? altitudeAccuracy;
  double? heading;
  double? speed;
};

Normative changes to the Coordinates interface of the Geolocation API are the following:

Use unrestricted double to not throw TypeError on NaN, +Infinity or −Infinity. (Geolocation API defines NaN as a valid value for heading, yet uses double as its type.)
Use nullable to allow all attributes to default to null. (Geolocation API does not provide synchronous means to access these attributes, thus latitude, longitude and altitude are not nullable and "must be supported by all implementations".)

To construct a GeolocationSensor object the user agent must invoke the construct a geolocation sensor object abstract operation.

5.1.1. GeolocationSensor.read()

The read() method, when called, must run the following algorithm:

input: options, a ReadOptions object.
output: p, a promise.

Let p be a new promise.
Let options be the first argument.
Let signal be the options’ dictionary member of the same name if present, or null otherwise.
If signal’s aborted flag is set, then reject p with an "AbortError" DOMException and return p.
Let geo be the result of invoking construct a Geolocation Sensor object with options. If this throws a DOMException, catch it, reject p with that DOMException, and return p.
Invoke geo.start().
If signal is not null, then add the following abort steps to signal:
1. Invoke geo.stop().
2. Reject p with an "AbortError" DOMException and abort these steps.
Run these steps in parallel:
1. If notify error is invoked with geo, invoke geo.stop(), and reject p with the DOMException passed as input to notify error.
2. If notify new reading is invoked with geo, then resolve geolocation promise with geo and p.
Return p.

Implementations can reuse the same promise for multiple concurrent calls within the same browsing context if the arguments passed to read() are the same.

To resolve geolocation promise means to run the following steps:

Let reading be a GeolocationSensorReading.
For each key → value of latest geolocation reading:
1. Set reading[key] to value.
Invoke geo.stop().
Resolve p with reading.

5.1.2. GeolocationSensor.latitude

The latitude attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "latitude" as arguments. It represents the latitude coordinate of the geolocation in decimal degrees [WGS84].

5.1.3. GeolocationSensor.longitude

The longitude attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "longitude" as arguments. It represents the longitude coordinate of the geolocation in decimal degrees [WGS84].

5.1.4. GeolocationSensor.altitude

The altitude attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "altitude" as arguments. It represents the geolocation in meters above the WGS 84 ellipsoid [WGS84].

5.1.5. GeolocationSensor.accuracy

The accuracy attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "accuracy" as arguments. It represents the accuracy of the latest reading["latitude"] value and latest reading["longitude"] value in meters with a 95% confidence level.

If the latest reading["latitude"] value is null or latest reading["longitude"] value is null, it must return null.

5.1.6. GeolocationSensor.altitudeAccuracy

The altitudeAccuracy attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "altitudeAccuracy" as arguments. It represents the accuracy of the latest reading["altitude"] value in meters with a 95% confidence level.

If the latest reading["altitude"] value is null, it must return null.

5.1.7. GeolocationSensor.heading

The heading attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "heading" as arguments. It represents the direction of travel in degrees counting clockwise relative to the true north in the range 0 ≤ heading ≤ 360.

5.1.8. GeolocationSensor.speed

The speed attribute of the GeolocationSensor interface returns the result of invoking get value from latest reading with this and "speed" as arguments. It represents the magnitude of the horizontal component of the velocity in meters per second.