RE: Geolocation API

Shyam and I discussed this a bit - here are my addition 5 cents:

>    7.2.  For the provider architecture to be truly extensible and useful as a W3C standard, interface details of the providers MUSt also be documented in detail.

[Andrei]: Do you mean that the protocol between UA implementing the geolocation
API and the server acting as a network location provider should be
documented in detail?  If that is the case, I tend to agree. However,
it's not entirely obvious if such a protocol should be in the scope of
a W3C spec or not. That's definitely a discussion we should have very
soon as we need to decide what is the exact scope of the Geolocation
API specification.

[AlecB]: Even if it does get decided that this is in-scope (which I personally am not sure that it should be), I think it should be 'if-implemented,' i.e. a browser can use any other protocol/technology to gain access to location data that it wants, but if it uses the W3C, then it has to follow the spec.

> 8.  The user-agent MAY allow the user to control accuracy of Position data exposed to a given authority (web-site) based on user-determined trust levels. The Position data exposed through this API MUST honor that user preference.
>

[Andrei]: This is interesting, but could you please describe the idea in a bit
more detail? How would the trust levels be defined? How would the user
decide which level to choose? How would the browser translate the
trust level into something meaningful to the geolocation API?

[AlecB]: My thoughts are in the "Geolocaton:Security and Privacy" thread


Here are some possible interface modifications to the Gears API that incorporates alternative names, status events, minimum report intervals and 'trust levels' (or 'data fuzzing').

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

  // Get the current position.
  // The callback function will be called with the result.
  ReportStatus getLocation(        LocationCallback locationCallback,
                                   optional ReportOptions options);

  // Watch the current position over time.
  // The callback function will be called with the result.
  int listenForReports(   LocationCallback locationCallback,
                          StatusCallback statusCallback,
                          optional ReportOptions options);

  // Get the report generation status
  ReportStatus getReportStatus();

  // Stop watching the current position.
  void stopListeningForReports(int listenerId);
};

void LocationCallback(LocationReport report);
void StatusCallback(ReportStatus status);

interface LocationReport {
  readonly double latitude;  // latitude in degrees
  readonly double longitude;  // longitude in degrees
  readonly double altitude;  // height in meters above the WGS 84 reference ellipsoid, or null if unsupported by device.
  readonly double errorRadius;  // in meters
  readonly double verticalAccuracy;  // in meters, or null if unsupported
  readonly Date timestamp;      // time when location was established
  readonly string errorMessage; // human readable, suitable for logs
  readonly Address address;     // reverse geocoded address, if requested and available
  // TODO: Consider adding heading
  // TODO: Consider adding speed
};

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
}

// Or could use constant int, or any equivalent format
var ReportStatus = {
NOT_AVAILABLE:0,
ERROR:1,
ACCESS_DENIED:2,
INITIALIZING:3,
READY:4}

interface ReportOptions {
  // Optional. Provides a hint about how accurate a location fix the application would like
  // to receive. This should be in meters or possibly a fixed range of values (such as 1-10)
  // if more accurate data is available, noise should be added to reduce the accuracy to this
  // level. This allows for the 'enableHighAccuracy' field on a continuous scale.
  int requestedAccuracy;
  // Optional. Provides a hint as to what the minimum time (ms) that should be allowed to elapse
  // between asynchronous calls. For example, if this were called with 10 min, the callback should
  // only be called every 10 min with a new report
  int minReportInterval

  // Optional. 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 requestAddress;

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

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