Geolocation API Network Protocol

This document describes the network protocol that Gears uses to communicate with the network location providers used by the Geolocation API.

Contents

  1. Overview
  2. Example
  3. Request Specification
  4. Response Specification

Overview

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.

Example

An example request and response are shown below.

Gears Request


{
  "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
    }
  ]
}

Server Response


{
  "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"
}

Request Specification

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

Location Object

Name Description Required Type
latitude Current latitude in degrees (WGS84 datum). No double
longitude Current longitude in degrees (WGS84 datum). No double

Cell Data Object

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

WiFi Data Object

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

Response Specification

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

Address 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