Summary

The Geolocation API allows web apps to retrieve the user's current position. The API should provide the following features:

• One-shot position requests (e.g. for recommendations sites -- "where am I right now?")
• Repeated position updates (e.g. for continuously updating one's location on a map)
• Ability to get the last-known position cheaply before doing an expensive new request
• Compatibility with future use as a singleton in the standard DOM (e.g. window.geolocation)

API Proposal

interface Geolocation {
  // Last known position, or null if there is no last known position.
  readonly Position lastPosition;

  // Get the current position.
  // The success callback function is always called exactly once with a good position,
  // as soon as one is available, or the error callback is called exactly once with an
  // error message, if none of the location providers find a good fix. The error callback
  // is optional and null may be passed.
  void getCurrentPosition(function successCallback, optional function errorCallback, optional PositionOptions options);

  // Watch the current position over time.
  // The success callback function will be called when ...
  // - with a good position, as soon as one is available, or
  // - whenever the position changes significantly, subject to a maximum callback 
  //    frequency.
  // The error callback is called if a fatal error occurs which will prevent a position
  // fix from ever being obtained by this watch.  The error callback
  // is optional and null may be passed.
  int watchPosition(function successCallback, optional function errorCallback, optional PositionOptions options);

  // Stop watching the current position.
  void clearWatch(int watchId);
};

The signature of the success callback is ...
function successCallback(Position position);

The signature of the error callback is ...
function errorCallback(PositionError error);


interface Position {
  readonly double latitude;  // latitude in degrees (WGS84 datum)
  readonly double longitude;  // longitude in degrees (WGS84 datum)
  readonly int altitude;  // height in meters (WGS84 datum), or null if unsupported by device.
  readonly int accuracy;  // in meters
  readonly int altitudeAccuracy;  // in meters, or null if unsupported
  readonly Date timestamp;      // time when location was established
  readonly Address gearsAddress;     // reverse geocoded address, if requested and available. Gears extension
  // TODO: Consider adding heading
  // TODO: Consider adding speed
};

interface PositionError {
  readonly int code;
  readonly string message; // human readable, suitable for logs
}

interface Address {
  readonly string streetNumber; // street number
  readonly string street;       // street address
  readonly string premises;     // premises, e.g. building name
  readonly string city;         // city name
  readonly string county;       // county name
  readonly string region;       // region, e.g. a state in the US
  readonly string country;      // country
  readonly string countryCode;  // country code (ISO 3166-1)
  readonly string postalCode;   // postal code
}

interface PositionOptions {
  // Optional. Provides a hint that the application would like to receive the
  // best possible results. This may result in slower response times or
  // increased battery consumption. The user may also deny this capability,
  // or the device may not be able to provide more accurate results than if
  // the flag wasn't specified. Defaults to false.
  bool enableHighAccuracy;

  // Optional. Gears extension. Requests reverse geocoded address information as part of
  // the position data. Reverse geocoding is not performed if this flag is not
  // specified or set to false.
  bool gearsRequestAddress;

  // Optional. Gears extension. Specifies the language in which the address (if requested) should be returned. Uses RFC 3066.
  string gearsAddressLanguage.

  // Optional. This is a Gears extension that specifies one or more URLs to
  // contact to convert geolocation signals into positions. Each URL is
  // queried and the one that returns the highest accuracy position is
  // returned. If unset, the  defaults to a single Google-implemented service.
  // The array can also be cleared, or set to null, so that no location
  // providers will be used.
  // For more information on the protocol that Gears uses to communicate with
  // location providers, see below.
  string[] gearsLocationProviderUrls;

  // TODO: Consider adding distanceThreshold (for use with watch())
};

Examples

var geo = google.gears.factory.create('beta.geolocation');

// Get the position.
geo.getCurrentPosition(function(position) {
  updateMap(position.latitude, position.longitude);
});

// Watch the position over time.
var watchId = geo.watchPosition(function(position) {
  updateMap(position.latitude, position.longitude, position.accuracy);
});

geo.clearWatch(watchId);

// Only get the position if the last known position is more than a minute old.
var now = new Date().getTime();
var threshold = now - 60000;

if (geo.lastPosition &&
    geo.lastPosition.timestamp.getTime() > threshold) {
  updateMap2(geo.lastPosition);
} else {
  loc.getCurrentPosition(function(position) {
    updateMap2(position);
  });
}

Implementation Details

The Geolocation API is an abstraction for various location APIs that currently exist on mobile platforms (GPS-based, network/cellid-based). Geolocation implementations could be straightforward mappings to native APIs (e.g the S60 Location Acquisition API) or have a more complex design that combines several location providers (e.g. a GPS-based provider and a cell id-based provider) and returns the location from the most accurate provider at any given time.

The Gears implementation chooses the location provider to invoke subject to the criteria specified with PositionOptions. When location data is requested, the first result that satisfies the criteria is returned via the PostionCallback function. Subsequent invocations will always use the most accurate location data available. This caters for the common case where a less accurate fix from a network-based location provider can be obtained quickly followed by a more accurate GPS fix later.

Privacy

It must be clear to users when an application is using the Geolocation API. We could implement one or both of the following UI elements:

1. A separate dialog from the Gears security dialog to enable the Geolocation API. If the general-purpose dialog gave access to position data, it would be easy for users to forget they allowed access to Gears, or to fail to realize enabling Gears also exposes their position data.
2. Some persistent UI that indicates the Geolocation API is being used. For example, there could be a bar across the bottom of the browser with an icon of a globe or map. Perhaps this UI should be 'active' somehow, indicating that something is happening, so that the user cannot forget it is being used.

Network Location Provider Protocol

Many devices do not have native access to GPS or other location data. Additionally, GPS can take a long time to get an accurate location fix, drains battery, and does not work indoors. Because of these problems, the location API also has the ability to send various signals that the devices has access to (nearby cell sites, wifi nodes, etc) to a third-party location service provider, who can resolve the signals into a location estimate.

The protocol between the device and the location service provider is HTTP POST. The request and response are both formatted as JSON.

Client identification is not explicitly included in the protocol. Cookies can be used for this.

Request Format

{
  "version": "1.0",
  "host": "maps.google.com",
  "home_mobile_country_code": 310,
  "home_mobile_network_code": 410,
  "radio_type": "gsm",
  "carrier": "Vodafone",
  "request_address": true,
  "address_language": "en_GB",
  "location": {
    "latitude": 51.0,
    "longitude": -0.1
  },
  "cell_towers": [
    {
      "cell_id": 42,
      "location_area_code": 415,
      "mobile_country_code": 310,
      "mobile_network_code": 410,
      "age": 0,
      "signal_strength": -60,
      "timing_advance": 5555
    },
    {
      "cell_id": 88,
      "location_area_code": 415,
      "mobile_country_code": 310,
      "mobile_network_code": 580,
      "age": 0,
      "signal_strength": -70,
      "timing_advance": 7777
    }
  ],
  "wifi_towers": [
    {
      "mac_address": "01-23-45-67-89-ab",
      "signal_strength": 8,
      "age": 0
    },
    {
      "mac_address": "01-23-45-67-89-ac",
      "signal_strength": 4,
      "age": 0
    }
  ]
}

Request field details

Location data elements

Cell-Id data elements

Wifi-Id data elements

Response Format

The response format is also JSON. An example response is:

{
  "location": {
    "latitude": 51.0,
    "longitude": -0.1,
    "altitude": 30,
    "horizontal_accuracy": 1200,
    "vertical_accuracy": 10,
    "address": {
      "street_number": "100",
      "street": "Amphibian Walkway",
      "postal_code": "94043",
      "city": "Mountain View",
      "county": "Mountain View County",
      "region": "California",
      "country": "United States of America",
      "country_code": "US"
    }
  }
}

Response format details

If the request format is invalid, the server responds with HTTP status 400. The details of the error should be plain text in the response.

If the request format is valid, the server replies with HTTP status 200. If the location was successfully resolved, the location object is populated with the details. Otherwise, it is null. TODO: Consider adding an error property to the response, the contents of which Gears could pass back to JavaScript?