interface navigator.GeolocationRequest {
  // Get the current position.
  // The callback function will be called with the resulting Geolocation
  // object.
  void request(PositionCallback callback);
  
  // Get the current position, with options!
  void request(RequestOptions options);
  
  // The default level of accuracy that the user has chosen to give about
  // their location. It takes the same strings as "desiredAccuracy". This
  // is the highest value of position data that will be given without
  // prompting the user for permission. If the user has disallowed access
  // to their location, defaultAccuracy is null.
  readonly string defaultAccuracy;
};

interface RequestOptions {
  // A callback for when everything goes correctly.
  PositionCallback success;
  
  // Optional.
  // A callback for when bad things happen, it gets a GeoError object.
  ErrorCallback error;

  // Optional.
  // desiredAccuracy can be one of the following strings:
  //    "exact" -- means to give the Geolocation as precisely as possible
  //    "neighborhood" -- means to give the Geolocation good to 1km
  //    "city" -- means to give the Geolocation good to 10km
  string desiredAccuracy;
  
  // 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.
  
}

interface Geolocation {
  readonly double latitude;   // in degrees
  readonly double longitude;  // in degrees
  readonly double altitude;   // in meters, or null if no data.
  readonly double accuracy;   // in meters
  readonly double altitudeAccuracy; // in meters, or null if no data
  int timestamp;              // time of the location read, in seconds since
                              // the epoch
}

interface GeoError {
  string message; // Human readable error message.
  
  // Other attributes can be added as necessary for particular devices.
  // Only the "message" attribute is guaranteed to be exists.
}

interface Address {
  // Any of the below can be null, if not known.
  
  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
}

void PositionCallback(Geolocation position);
void ErrorCallback(GeoError error);