JSON/REST API Reference¶

The JSON/REST JavaScript API is designed to provide you with a Google Gears-compatible network location provider. When using the Gears Geolocation object, you can specify the address of the CLP as a network location provider in the JavaScript of a Gears-enabled Web page. For information on the Geolocation API, go to http://code.google.com/apis/gears/api_geolocation.html.

However, if you are using a custom application, the CLP implements the Google Gears Geolocation API network protocol in order to act as a compatible network location provider. The Geolocation API network protocol is a simple JSON over HTTP request/response system with the JSON request payload sent using a HTTP POST operation. In order for the request to be processed and posted, you must specify the attributes for the HTTP request. For information on the Google Gears Geolocation API Network Protocol, go to http://code.google.com/apis/gears/geolocation_network_protocol.html.

This reference describes the JSON/REST JavaScript API, as well as the Geolocation API Network Protocol, used to access the CLP. This reference also includes a sample code that shows how an application attempts to obtain an accurate position from the test CLP by comparing JavaScript code samples from both Clearwire and Google Gears. Also included is a sample code that shows how an application attempts to obtain a position from the test CLP first, and then reverts to the Google location service when unable to retrieve a position from the CLP.

To see a live demo showing the use of both Clearwire and Google location services to retrieve current location, go to http://developer.clear.com/ClearLocationDemo.html. You must be connected to the Clearwire WiMAX network and use a Gears-enabled Web browser to enable the demo.

• JavaScript API
• Geolocation API Network Protocol
• Enabling Location Sample Code
• Using Location with Google Maps Sample Code

Go to Top

JavaScript API¶

The JSON/REST JavaScript API is designed to provide you with a Google Gears-compatible network location provider. When using the Gears Geolocation object, you can specify the address of the CLP as a network location provider in the JavaScript of a Gears-enabled Web page.

The following Google Gears PositionOptions class attributes are used to specify the input message for the CLP. For information on the Geolocation API, go to http://code.google.com/apis/gears/api_geolocation.html.

Go to Top

Go to Top

Go to Top

Example¶

try {
    var geolocation = google.gears.factory.create('beta.geolocation');
    geolocation.getCurrentPosition(
        successCallback,
        errorCallback,
        { enableHighAccuracy: true, gearsRequestAddress: true,gearsLocationProviderUrls: 
["http://testlocation.clearwire-wmx.net:8000/json/","http://www.google.com/loc/json"]}
    );
  } catch (e) {
    setError('Error using Geolocation API: ' + e.message);
    return;
  }

Go to Top

Geolocation API Network Protocol¶

If you are using a custom application to communicate with the CLP, the CLP implements the Google Gears Geolocation API network protocol in order to act as a compatible network location provider. The Geolocation API network protocol is a simple JSON over HTTP request/response system with the JSON request payload sent using a HTTP POST operation. If a device is connected to WiMAX, the request is posted to a power system to retrieve location data; if not, the request is posted to Google.

In order for the request to be processed and posted, you must specify the attributes for the HTTP request, as described below. For more information on the Google Gears Geolocation API Network Protocol, go to http://code.google.com/apis/gears/geolocation_network_protocol.html.

• Request Specification
• Response Specification

Request Specification¶

The details of the request protocol are as follows.

Go to Top

Go to Top

Go to Top

Go to Top

{    
    "host" : "_null_.localdomain", 
    "radio_type" : "unknown", 
    "request_address" : true, 
    "version" : "1.1.0" 
}

Go to Top

Response Specification¶

The details of the response are as follows. If a position is successfully determined, the location property is populated with the fields described below; otherwise, it is null.

Location

Go to Top

Address Object

Go to Top

Example

{
    "location":{
        "address":{
            "region":"NY",
            "postal_code":"14621",
            "street":"16 Ilex Pl",
            "street_number":"",
            "country_code":"US",
            "country":"USA",
            "city":"Rochester" 
        },
        "longitude":-77.5883,
        "latitude":43.1792,
        "accuracy":2011
    }
}

Go to Top

Sample Code Performing JavaScript Comparisons Between Clearwire and Google¶

In this example, the application attempts to obtain a position from the test CLP by comparing JavaScript code samples from both Clearwire and Google Gears. The code makes use of both these location providers to ascertain that location with the highest accuracy is used by the application. Use this sample to enable location with any Web site.

<html>
<head>
<title>Google Geolocation API Example doing accuracy comparison</title>

<script type="text/javascript" src="./gears_init.js"></script>

<script type="text/javascript">

var bestPosition;
var call = 0;
var locations = new Array(2);

//initialize gears

try
{
var geo = google.gears.factory.create('beta.geolocation');
}
catch (e)
{
    alert("You need gears from http://gears.google.com ; error= "+ e.toString());
}

//callback for position updates
function updatePosition(position) 
{

locations[call] = position;
call++;

alert('call ' + call + ": " + position.latitude + ',' + position.longitude + 
' with accuracy of ' + position.accuracy + ' meters.');

//make second call
if (call == 1)
{
    callTwo();
    return;
}

if (call == 2)
{
    findBestPosition();
}

}

function findBestPosition()
{

if (locations[0] == null && locations[1] == null)
    {
        alert('Both attempts to get location failed');
        return;
    }

    //in case of an error in a call, there will be no position object in array
    if (locations[0] == null && locations[1] != null)
    {
        bestPosition = locations[1];
        showBestPosition('Clearwire');
        return;
    }

    if (locations[1] == null && locations[0] != null)
    {
        bestPosition = locations[0];
        showBestPosition('Google');
        return;
    }

    //two calls have been made. compare accuracy from each.
    if (locations[0].accuracy <= locations[1].accuracy)
    {
        bestPosition = locations[0];
       showBestPosition('Google');
    }
    else
    {
        bestPosition = locations[1];
             showBestPosition('Clearwire');
    }

}

function showBestPosition(provider)
{
//show best location
    alert('Current lat/lon is: ' + bestPosition.latitude + ',' + bestPosition.longitude + 
' with accuracy of ' + bestPosition.accuracy + ' meters.' + ' Provided by ' + provider);

    //bestPosition is what the web page would then use.
}

//callback for errors
function handleError(positionError) 
{
  alert('Attempt to get location failed: ' + positionError.message);
call++;

//if not on wimax, what does our server send, if anything? I assume it sends a gears error 
response and that appears to be the case.

//make default call in case of error in first call
if (call == 1)
{
    callTwo();
}

if (call == 2)
{
    findBestPosition();
}

}

function initLocation()
{

//first call
var providers = ["http://www.google.com/loc/json"];
//the options change parameters in the json request
var options = {enableHighAccuracy:true,  gearsLocationProviderUrls:providers, 
gearsRequestAddress:true}; geo.getCurrentPosition(updatePosition, handleError, options);
}

function callTwo()
{
//second call
var providers = ["http://testlocation.clearwire-wmx.net:8000/json/"];
//the options change parameters in the json request
var options = {enableHighAccuracy:true,  gearsLocationProviderUrls:providers, 
gearsRequestAddress:true}; geo.getCurrentPosition(updatePosition, handleError, options);
}

</script>

</head>

<body onLoad="initLocation();">

This test page is running a gears query now. Read the alert boxes.

</body>
</html>

Go to Top

Sample Code Querying Google Location Service As Backup¶

In this example, the application attempts to obtain a position from the test CLP. If the test CLP is unable to provide a position, the Google location service is queried to provide a WiFi or an IP location-based position. You can use this sample to enable location with Google Maps.

<html>
<head>
<title>Hello World Geolocation</title>
<link rel="stylesheet" type="text/css" 
href="http://code.google.com/apis/gears/samples/sample.css">
</head>
<body>

<h1>Gears Geolocation Demo</h1>
<div id="view-source">&nbsp;</div>

<p id="status"></p>

<p><b>This page demonstrates basic usage of the Geolocation API.</b></p>

<!-- ====================================== -->
<!-- End HTML code.  Begin JavaScript code. -->

<script type="text/javascript" 
src="http://code.google.com/apis/gears/gears_init.js"></script>
<script type="text/javascript" 
src="http://code.google.com/apis/gears/samples/sample.js"></script>
<script>

init();

function init() {
  if (!window.google || !google.gears) {
    addStatus('Gears is not installed', 'error');
    return;
  }

  addStatus('Getting location...');

  function successCallback(p) {
    var address =  p.gearsAddress.street + ' '
                  + p.gearsAddress.city + ', '
                  + p.gearsAddress.region + ', '
                  + p.gearsAddress.country + ' ('
                  + p.latitude + ', '
                  + p.longitude + ')';

    clearStatus();
    addStatus('Your address is: ' + address);
  }

  function errorCallback(err) {
    var msg = 'Error retrieving your location: ' + err.message;
    setError(msg);
  }

  try {
    var geolocation = google.gears.factory.create('beta.geolocation');
    geolocation.getCurrentPosition(
        successCallback,
        errorCallback,
        { enableHighAccuracy: true, gearsRequestAddress: true,gearsLocationProviderUrls: 
["http://testlocation.clearwire-wmx.net:8000/json/",
"http://www.google.com/loc/json"]}
    );
  } catch (e) {
    setError('Error using Geolocation API: ' + e.message);
    return;
  }

}
</script>
</body>
</html>

Go to Top

Next Topics

• Resources and Tools
• Getting Started
• Architecture