|
GeolocationAPI
Provides the geolocation of a device running a Gears-enabled web browser.
SummaryThe Geolocation API allows web apps to retrieve the user's current position. The API should provide the following features:
API Proposalinterface 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())
};Examplesvar 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 DetailsThe 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. PrivacyIt must be clear to users when an application is using the Geolocation API. We could implement one or both of the following UI elements:
Network Location Provider ProtocolMany 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.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 FormatThe response format is also JSON. An example response is: {
"location": {
"latitude": 51.0,
"longitude": -0.1,
"altitude": 30.1,
"accuracy": 1200.1,
"altitude_accuracy": 10.1,
"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 detailsIf 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?
JSON Protocol VersioningThe version of the JSON protocol is expressed as a string with format <major>.<minor>.<release>. These fields are updated as follows.
The version history of the protocol is shown below.
Questions and CommentsIf you have any questions about the Geolocation API, be sure to check out the official Geolocation documentation. If you still have questions or comments, please use one of the Gears mailing lists, rather than adding comments to this document. |
Sign in to add a comment
The information seems complete except for:
What's the URL for the HTTP POST request?
Any example of how much (read: little) info I need to send if I have only cell info from one cell?
Any thoughts of using URL arguments as input and XML as output? Easier to use from other languages than Javascript.
My scenario doesn't involve Gears.
Cheers
aggree with redsmurph!
another question, the source looks like a Symbian code other than web or windows application, maybe a background introduction is better?
Regards Peng
What is the highest accuracy attainable for: 1. Fixed broadband locations? 2. Mobile devices?
Accuracy improvement suggestion: Have you considered averaging locations of individual cell sites in data sets where they are the only cell site detected by mobile devices?
i.e. where movement is - on average unrestricted and evenly distributed - clusters of mobile devices around a single point should return locations as a cluster averaged on the true position.
Does anyboy know the url to post?
url to post: http://www.google.com/loc/json
is this API need API Key; for, i always got 404 Error
The URL works for me, but any request i get this message:
Bad Request Version not supported.
Found: use "version":"1.0"
Are API and service subject to agreement? (as all Google services are) if Yes where ?
I noticed that you can add as many cell_towers you want, but longitude and latitude remains unchanged. Like only first CellID is taken in consideration.
More cellIDs input shouldn't give more precise position?
Randy P. SMith 4601 S Crysler Independence, mo 64055 - 35833 358-2638
Is it according to GOOG's terms and conditions to use the server side facilities of Google Gears location API by "hand rolled" HTTP POST request?
Although this blog seems not to be moderated, here some obscurities, probably someone notes that:
1) According to the doc, the cell_id element is of string type. According to the sample it is of int. Both is accepted, so please fix the doc.
2) mcc and mnc are Int32 outside the cell_id struct (inside int16). Should be unified.
3) Shouldn't the cell_towers struct contain the carrier element too?
4) At least for german locations I tested the returned address object (if reverse geocoding is requested) does not contain street and house number information, although this information is given in "ordinary" geocding mode. Is this "by design"?
Regards
... the latter "although this information is given" is meant: If provided street and street number a valid geocode (which may be resolved on a map) is returned using Google Maps geocoding functions. Reverse geocoding of the same geocode using Gears location api does miss the street/street number info. Sorry for being not specific enough.
Sorry to echo MrPatrol? and Neil Young on this; is there a proper method to establish a contact with google for business/commercial licensing? I would like to make a proposal; however, it is important to me to make sure that it profitable enough for google so that it is worth their time. Steve Block, or anyone at google, I can be reached at nine seven two 659 1626 extension 150. Thanks and my appologies for the unstructured inquiry and contact request. Ray B
"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."
Who is the third party location service provider? Is this currently Google or ? How can I send money to Google for this service?
Thanks for the comments. A few answers ...
> 1) According to the doc, the cell_id element is of string type. According to > the sample it is of int. Both is accepted, so please fix the doc. The server will accept an integer because we use a JSON format, so JavaScript? type conversion rules apply. I've updated the sample to use a string to avoid confusion.
> 2) mcc and mnc are Int32 outside the cell_id struct (inside int16). Should be > unified. This document was used for development work. The JSON format in use by Gears makes no distinction between int16 and int32. A definitive user-facing document for the JSON format will be posted soon.
> 3) Shouldn't the cell_towers struct contain the carrier element too? No, A device can be in contact with multiple cell towers, it can only use one carrier at a given point in time.
> Who is the third party location service provider? Is this currently Google? The Geolocation API allows the user to specify the network location provider, but the default is the Google provider. See the Geolocation API documentation for details.
In general, it's best to post questions to one of the Gears mailing lists, rather than here.
Steve
I extracted the necessary values from my Sony Ericsson K810 which has no GPS or wifi using: String cellid=System.getProperty("com.sonyericsson.net.cellid"); String mcc = System.getProperty("com.sonyericsson.net.cmcc"); String mnc = System.getProperty("com.sonyericsson.net.cmnc"); String lac = System.getProperty("com.sonyericsson.net.lac");
I then hand rolled a python script to call the given URL with the specified json object, using these values. First of all, I got a JSON Bad Parse error because the service didn't like the lac and cellid which appeared to be in hex and I sent as strings. I tried again using the decimal conversions of these values and got a 200 OK status, but an empty Json object. I tried once more with some random cellid and lac values and in some cases retrieved the expected result with lat and lng values etc.
When I use the Google Maps j2me app, it is able to resolve my location at the same position. Does it use any different technology to resolve location? What are any possible reasons that my hand rolled request is not getting resolved? And finally, am I violating the terms of use by calling the service directly and not using the gears framework?
Thanks for your time, Harry.
It seems that the Geolocation API is able to automatic retrieve cell-id information,and the Geolocation API can use the cell-id information to get user's location. All above what I say is right or not ? I am confused if the API can automatic get location ,how it determine via cell-id or GPS (If my device have all) Can I specify the Geolocation API to get location via cell-id?
There are some curious little parsing problems with json responses. Latitude and longitude CANNOT be integers, but can be '20.' or '20.1'. horizontal_accuracy MUST be an integer, since if a float, you get a malformed response error. I suspect there are other problems like this in how the parser handles json responses. So if pulling your hair out over malformed response errors, look at integer vs. float values.
Steve- given that wimax networks now exist (XOHM), can we talk about updating this API to support wimax? Not to mention that Google is an investor...
Hi, I love it ;)
What are the terms of usage of anything on the www.google.com/loc/json portal?
Specifically, it says in the TOS that you can't use google services other than through provided APIs .. is connecting to the www.google.com/log/json with a web request and providing the JSON request above as part of the request breaking this or is it part of how it's intended to be used?
Hi, i'd also like to know if this can be used by POST to the GOOGLE Location Provider also. www.google.com/loc/json.
I wonder if there's an API in progress for this, in case there Licence problems in use the URL directly.
Steve thanks for your answers above. I didn't know about the multi-provider-single-carrier issue, but this sounds logical, if thought twice :)
Currently I'm trying to make the get_location run with just a WiFi? BSSID, but it always returns a position, based upon my IP (far, far away). I'm doing this using BSSIDs, which are resolvable using SkyHookWireless?' API. Q: Does Gears support WiFi? - only based positioning currently? GSM cell based positioning works fine.
Regards
Is there a way to connect the GeolocationAPI to '''GPS''' devices API (satellite positioning is becoming now very widespread in many mobile devices, including now some mobile phones not just GPS navigation devices, whose prices have dramatically dropped)?
Also the retreived geolocation should be able to list '''several locations''', if present in the client device, each one tagged with the source provider (generic IP geolocation, WiFi? provider, GSM carrier, GPS..), allowing users to view which one is most aaccurate and use one of them (the position.accuracy field is not always consistant)
For IP geolocation, there are several databases on the web, more or less accurate or up to date. But for many Internet providers, this just gives the location of the ISP office (as registered in the WHOIS database for the assigned IP address block), because IP addresses are assigned randomly by the ISP at each connection (only the ISP knows the exact routing to the connected client). In addition, once they are assigned, these IP blocks are not always maintained if their use by the ISP change over time (for example when an ISP deploys new BAS equipement for ADSL: the IP does not necessarily indicates the physical DSLAM, but most often only a BAS which may be located anywhere in the country, and even sometimes in another country). For ISP customers connected by modem through POT lines, this IP location may even be completely non significant. all that can be said from this IP is that it belongs to the network of some ISP.
One the opposite, some IP locations may be very accurate, such as the IP addresses provided by FON wifi hotspot (if the hotspot is fully parametered by its maintainer). Connection through cable TV or fibre providers may also provide much better positioning (but this often requires some acces to some database, not just reverse-ip DNS and WHOIS data).
Note: not all devices require authorization, the IP address notably is public.
Please update the response information to match what google gears currently does. 'accuracy' is a new property and it is required. horizontal_accuracy and vertical_accuracy are gone. Using them instead of accuracy causes a malformed response error. Thanks.
Thanks for all the comments. A few responses ...
- Answers to many of the questions about use of the API can be found in the Geolocation API documentation at http://code.google.com/apis/gears/api_geolocation.html. This Wiki page is intended to document work in progress for those developing Gears, not to serve as definitive documentation of the API.
- Regarding the JSON protocol, I've updated this document to reflect the current behaviour in Gears. Note that official documentation of the protocol will soon be added to the Geolocation API documentation.
- The Gears Terms of Service prohibits direct use of the Google location server (http://www.google.com/loc/json) via HTTP requests. This service may only be accessed through the Geolocation API.
Hi All,
Hi,
I was in Fance few weeks ago and was suprised by some of the results i got back: (data as: MCC, MNC, LAC, CELL_ID)
First result was great for data : 208 10 28602 7473 (45.823502, 6.724991)
Second result was not so great for data : 208 10 6 6961 (55.952674, -3.189814) The second result is in Scotland, Edinburgh
MCC and MNC are the same for both datas....should you do reverse geo coding to make sure the location match the MCC? (i think it will be better to return no result when the MCC doesnot match the lat, lon)
Thanks
Hi,
Could any of you help me with sending a JSON object via a http POST request in Symbian C++ or just C++ code?
Thanks
Hi,
it would be great if You could integrate a form field in the Gears Location settings for defining a certain location manually (as a fallback position or if You want information for a different place than where You are). It would even better, if users could create several "location profiles" (for example: actual location, at home, my favorite place in Paris, ...)
i was wondering if its possible to get teh SSIDS and Cell information from google gears too
Will Google ever release a public API for use outside Gears?
Plz can anyone give one sample request using IP