You Are Here (And So Is Everybody Else)

1.   Geolocation is the art of figuring out where you are in the world and (optionally) sharing that information with people you trust. There is more than one way to figure out where you are — your IP address, your wireless network connection, which cell tower your phone is talking to, or dedicated GPS hardware that calculates latitude and longitude from information sent by satellites in the sky.

 

 

2.   User Agents must not send location information to Web sites without the express permission of the user.

 

3.   The simplest use of the geolocation API looks like this:

function get_location() {

  navigator.geolocation.getCurrentPosition(show_map);

}

 

The call to getCurrentPosition() will return immediately, but that doesn’t mean that you have access to the user’s location. The first time you are guaranteed to have location information is in the callback function. The callback function looks like this:

 

 

function show_map(position) {

  var latitude = position.coords.latitude;

  var longitude = position.coords.longitude;

  // let's show a map or do something interesting!

} 

 

 

4.   The callback function will be called with a single parameter, an object with two properties: coords and timestamp . The timestamp is just that, the date and time when the location was calculated. The coords object has properties like latitude and longitude which are exactly what they sound like: the user’s physical location in the world.

 Only three of the properties are guaranteed to be there (coords.latitude , coords.longitude , and coords.accuracy ). The rest might come back null , depending on the capabilities of your device and the backend positioning server that it talks to. The heading and speed properties are calculated based on the user’s previous position, if possible.

 

5.   You can pass a second argument to the getCurrentPosition() function which is an error handling callback function. If anything goes wrong, your error callback function will be called with a PositionError object which has a code and message property. The code property will be one of :

  a)   PERMISSION_DENIED (1) if the user denies your access to their location.

  b)   POSITION_UNAVAILABLE (2) if the network is down or the positioning satellites can’t be contacted.

  c)   TIMEOUT (3) if the network is up but it takes too long to calculate the user’s position.

 

6.   The getCurrentPosition() function has an optional third argument, a PositionOptions object . There are three properties you can set in a PositionOptions object: enableHighAccuracy , timeout and maximumAge . All the properties are optional. You can set any or all or none of them. The timer doesn’t start counting down until after the user gives permission to even try to calculate their position. You’re not timing the user; you’re timing the network. The maximumAge property allows the device to answer immediately with a cached position calculated whthin maximumAge milliseconds before.

 

7.   The watchPosition() function has the same structure as getCurrentPosition() . It takes two callback functions, a required one for success and an optional one for error conditions, and it can also take an optional PositionOptions object that has all the same properties. The difference is that your callback function will be called every time the user’s location changes. The watchPosition() function itself returns a number. You should probably store this number somewhere. If you ever want to stop watching the user’s location change, you can call the clearWatch() method and pass it this number, and the device will stop calling your callback function.

 

8.   Gears is an open source browser plugin from Google. It provides features for older browsers. One of the features that Gears provides is a geolocation API . It’s not quite the same as the W3C geolocation API , but it serves the same purpose.

 

9.   geo.js is an open source, MIT -licensed JavaScript library that smooths over the differences between the W3C geolocation API , the Gears API , and the API s provided by mobile platforms. To use it, you’ll need to add two <script> elements at the bottom of your page:

 

<script src="gears_init.js"></script>

<script src="geo.js"></script> 

 

First, you need to explicitly call an init() function. The init() function returns true if a supported geolocation API is available. To actually find your location, you need to call the getCurrentPosition() function:

if (geo_position_js.init()) {

  geo_position_js.getCurrentPosition(geo_success, geo_error);

}

 

geo.js does not currently support the watchPosition() function.