This document describes the network protocol that Gears uses to communicate with the network location providers used by the Geolocation API.
The Gears Geolocation API can make use of network servers to obtain a position fix. The server determines the client's position using a set of data provided by the client. This data includes the client's IP address and information about any cell towers or WiFi nodes it can detect. This document describes the protocol used to send this data to the server and to return a response to the client.
Communication is done over HTTP, with Gears making the request using HTTP
POST. Both request and response are formatted as JSON, and the content type of
both is application/json
.
An example request and response are shown below.
{
"version": "1.1.0",
"host": "maps.google.com",
"access_token": "2:k7j3G6LaL6u_lafw:4iXOeOpTh1glSXe",
"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
}
]
}
{
"location": {
"latitude": 51.0,
"longitude": -0.1,
"altitude": 30.1,
"accuracy": 1200.4,
"altitude_accuracy": 10.6,
"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"
}
},
"access_token": "2:k7j3G6LaL6u_lafw:4iXOeOpTh1glSXe"
}
The details of the request protocol are provided below.
Name | Description | Required | Type |
---|---|---|---|
version | The protocol version, currently, "1.1.0". | Yes | string |
host | The host of the web page that is requesting the location. | Yes | string |
access_token | An identifier which is set by the server and included in all subsequent requests to that server. | No | string |
home_mobile_country_code | The mobile country code for the device's home network. | No | int |
home_mobile_network_code | The mobile network code for the device's home network. | No | int |
radio_type | Mobile radio type (gsm|cdma|wcdma). | No | string |
carrier | Carrier name. | No | string |
request_address | Request the server to provide an address. | No | boolean |
address_language | Specifies the language of the requested address. Uses RFC 3066. | No | string |
location | Current position. See description below. | No | object |
cell_towers | Array of cell data objects. See description below. | No | array |
wifi_towers | Array of WiFi data objects. See description below. | No | array |
Name | Description | Required | Type |
---|---|---|---|
latitude | Current latitude in degrees (WGS84 datum). | No | double |
longitude | Current longitude in degrees (WGS84 datum). | No | double |
Name | Description | Required | Type |
---|---|---|---|
cell_id | Unique identifier of the cell. (CID for GSM, BID for CDMA) | No | int |
location_area_code | Location Area Code (LAC for GSM, NID for CDMA) | No | int |
mobile_country_code | Mobile Country Code (MCC for GSM and CDMA) | No | int |
mobile_network_code | Mobile Network Code (MNC for GSM, SID for CDMA) | No | int |
age | The number of milliseconds since this cell was primary. If age is 0, the cell_id represents a current measurement. | No | int |
signal_strength | Radio signal strength measured in dBm. | No | int |
timing_advance | Represents the distance from the cell tower. Each unit is roughly 550 meters. | No | int |
Name | Description | Required | Type |
---|---|---|---|
mac_address | The mac address of the WiFi node. | No | string |
signal_strength | Current signal strength measured in dBm. | No | int |
age | The number of milliseconds since this access point was detected. | No | int |
channel | Channel. | No | int |
signal_to_noise | Current signal to noise ratio measured in dB. | No | int |
ssid | SSID. | No | string |
If the request is malformed, the server must respond with HTTP status 400. The details of the error should be described in plain text in the response.
If the request is valid, the server must reply with HTTP status 200 and the
body should specify an object with a location
property. If a
position fix was successfully determined, the location
property
must be populated with the fields descibed below. Otherwise, it must be
null.
Name | Description | Required | Type |
---|---|---|---|
latitude | Latitude of the fix, in degrees (WGS84 datum). | Yes | double |
longitude | Longitude of the fix, in degrees (WGS84 datum). | Yes | double |
altitude | Altitude of the fix, in meters (WGS84 datum). | No | double |
accuracy | The horizontal accuracy of the fix, in meters at a 95% confidence level. This is required unless the request specified a valid location object, i.e. a request for a reverse-geocode of a known position. | No | double |
altitude_accuracy | The accuracy of the altitude, in meters. | No | double |
address | The address of the fix if requested and available. See description below. | No | object |
Name | Description | Required | Type |
---|---|---|---|
street_number | The building's street number. | No | string |
street | Street name. | No | string |
premises | Premises, e.g. building name. | No | string |
city | City name. | No | string |
county | County name. | No | string |
region | Region, e.g. a state in the US. | No | string |
country | Country. | No | string |
country_code | Country code (ISO 3166-1). | No | string |
postal_code | Postal code. This is the zip code in the US and postcode in the UK. | No | string |
The response object may also optionally include an access_token
property. This is set by the server and used to identify the client in future
requests.
Name | Description | Required | Type |
---|---|---|---|
access_token | An identifier which is set by the server and included in all subsequent requests to that server. | No | string |