Geolocation Sensor

Editor’s Draft,

This version:
https://wicg.github.io/geolocation-sensor/
Editor:
Anssi Kostiainen (Intel Corporation)
Participate:
GitHub (new issue, open issues)
Tests:
web-platform-tests
Polyfills:
geolocation-sensor.js
geolocation.js

Abstract

This specification defines the GeolocationSensor interface for obtaining geolocation of the hosting device.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

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:

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.

  1. Let p be a new promise.

  2. Let options be the first argument.

  3. Let signal be the options’ dictionary member of the same name if present, or null otherwise.

  4. If signal’s aborted flag is set, then reject p with an "AbortError" DOMException and return p.

  5. 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.

  6. Invoke geo.start().

  7. 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.

  8. 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.

  9. 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:

  1. Let reading be a GeolocationSensorReading.

  2. For each keyvalue of latest geolocation reading:

    1. Set reading[key] to value.

  3. Invoke geo.stop().

  4. 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.

6. Abstract Operations

6.1. Construct a geolocation sensor object

input

options, a GeolocationSensorOptions object.

output

A GeolocationSensor object.

  1. Let allowed be the result of invoking check sensor policy-controlled features with GeolocationSensor.

  2. If allowed is false, then:

    1. Throw a SecurityError DOMException.

  3. Let geo be the new GeolocationSensor object.

  4. Invoke initialize a sensor object with geo and options.

  5. Return geo.

7. Acknowledgements

Tobie Langel for the work on Generic Sensor API and the geolocation.js polyfill.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[GENERIC-SENSOR]
Rick Waldron; et al. Generic Sensor API. URL: https://w3c.github.io/sensors/
[HR-TIME-2]
Ilya Grigorik; James Simonsen; Jatinder Mann. High Resolution Time Level 2. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[PERMISSIONS]
Mounir Lamouri; Marcos Caceres; Jeffrey Yasskin. Permissions. URL: https://w3c.github.io/permissions/
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/
[WGS84]
National Imagery and Mapping Agency. Department of Defence World Geodetic System 1984. Technical Report, Third Edition. URL: http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf

Informative References

[GEOLOCATION-API]
Andrei Popescu. Geolocation API Specification 2nd Edition. URL: http://dev.w3.org/geo/api/spec-source.html

IDL Index

[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;
};