Fix the JS api, add more docs

doc/api/js.md

@@ -12,7 +12,7 @@ hosted versions or download your own. They also serve as an example of a simple
 
 ## Conventions
 
-Each API call returns a jQuery promise and uses JSONP to get the data. This, for all calls,
+Each API call returns a jQuery deferred and uses JSONP to get the data. This, for all calls,
 the `.done()` callback will be provided the raw data (either a JS array or JS object), whilst
 the `.fail()` callback will be provided with an error.
 
@@ -21,22 +21,139 @@ As an example:
 ```js
 PerthTransit.trainStations().done(function(stations) {
   $.each(stations, function() {
-    console.log("Station named", this.name)
+    console.log("Station:", this.name)
   });
 });
 ```
 
 Would print all Train Station names.
 
-## API Methods
+### Getting Specific Objects
 
-The following API endpoints are supported:
+Functions returning a single item accept either the `identifier` property from the object (e.g. `"armadale"` for a train station)
+or an instance of the object - The general process is to take the object returned from the list, and use the specific instance
+to get an expanded version including times.
 
-* `PerthTransit.trainStations()` - Returns a list of all train stations in Perth.
-* `PerthTransit.trainStations({lat: "123", lng: "345"})` - Returns up to 5 stations within a 2.5km radius of the given point, closest first.
-* `PerthTransit.trainStation("armadale")` - Returns a train station object (including times) from a identifier.
-* `PerthTransit.trainStation(armadale_station_object)` - From a train station object from the previous calls, returns the full object, including times.
-* `PerthTransit.busStops({lat: "123", lng: "345"})` - Returns up to 5 bus stops within a 2.5km radius of the given point, closest first.
-* `PerthTransit.busStop("12345")` - Returns a bus stop object (including times) from a stop number.
-* `PerthTransit.busStop(stop_object)` - From a bus stop object from the previous calls, returns the full object, including times.
-* `PerthTransit.smartRider("012345")` - Returns information for the given smartrider number.
+### Geolocated Data
+
+Functions that allow a location filter (`PerthTransit.trainStations` and `PerthTransit.busStops`), both accept objects in any one of the following
+forms:
+
+* `{"lat": 123, "lng": 456}`
+* `{"lat": 123, "lon": 456}`
+* `{"latitude": 123, "longitude": 456}`
+
+Or any object including those properties. Note that this means it works with the coords object from the browsers built in
+Geolocation APIs.
+
+## Nearby Stops and Stations
+
+The two simplest and most useful forms of the api, these use the [JavaScript Geolocation API](http://dev.w3.org/geo/api/spec-source.html) to
+attempt to load upto 5 of the closest train stations or bus stops (within a 2.5km distance).
+
+### Nearby Train Stations
+
+`PerthTransit.nearbyTrainStations` returns a deferred that is resolved when it recieves the train locations back. Note that the API doesn't currently
+trigger the fail / reject portion of the deferred when access is denied but this may be added.
+
+The response data will be a list of up to 5 compact train station objects.
+
+```js
+PerthTransit.nearbyTrainStations().done(function(stations) {
+  $.each(stations, function() {
+    console.log("Station:", this.name)
+  });
+});
+```
+
+### Nearby Bus Stops
+
+`PerthTransit.nearbyBusStops` returns a deferred that is resolved when it recieves the bus stop locations back. Note that the API doesn't currently
+trigger the fail / reject portion of the deferred when access is denied but this may be added.
+
+The response data will be a list of up to 5 compact bus stop objects.
+
+```js
+PerthTransit.nearbyBusStops().done(function(stops) {
+  $.each(stops, function() {
+    console.log("Bus Stop:", this.display_name)
+  });
+});
+```
+
+## Train Stations
+
+### Getting all Train Stations
+
+To get a list of all train stations in perth, simply use `PerthTransit.trainStations`.
+
+```js
+PerthTransit.trainStations().done(function(stations) {
+  $.each(stations, function() {
+    console.log("Station:", this.name)
+  });
+});
+```
+
+### Getting Train Stations near a specific point
+
+By providing a location object (discussed above), you can easily filter to stops near a given location:
+
+```js
+PerthTransit.trainStations({lat: -32.1376, lng: 116.0104}).done(function(stations) {
+  $.each(stations, function() {
+    console.log("Station:", this.name)
+  });
+});
+```
+
+### Getting a specific Train Station
+
+Using either an instance from the prior functions or a train station identifier, you can also get the full train station object, including live times:
+
+```js
+PerthTransit.trainStation("daglish").done(function(station) {
+  console.log(station.name, station.times);
+});
+```
+
+Or, using the object from the collection functions:
+
+```js
+PerthTransit.trainStation(daglishStation).done(function(station) {
+  console.log(station.name, station.times);
+});
+```
+
+## Bus Stops
+
+### Getting a Bus Stop near a specific point
+
+The bus stop api only provides access to those restricted by a location. To access them, use the
+`PerthTransit.busStops` function and provide a location object:
+
+```js
+PerthTransit.busStops({lat: -32.1376, lng: 116.0104}).done(function(stops) {
+  $.each(stops, function() {
+    console.log("Bus Stop:", this.display_name)
+  });
+});
+```
+
+### Getting a specific Bus Stop
+
+Using either an instance from the prior functions or a stop identifier / number, you can also get the full bus stop object, including times:
+
+```js
+PerthTransit.busStop("22064").done(function(stop) {
+  console.log(stop.display_name, stop.times);
+});
+```
+
+Or, using the object from the collection functions:
+
+```js
+PerthTransit.busStop(stopNearMyHouse).done(function(stop) {
+  console.log(stop.display_name, stop.times);
+});
+```

js-api/perth_transit-1.0.js

@@ -13,10 +13,12 @@
   };
 
   var dataWithLocation = function(location) {
-    if(location === undefined) {
+    if(!location) {
       return null;
     } else {
-      var near = "" + location.lat + "," + location.lng;
+      var lat = location.lat || location.latitude;
+      var lng = location.lng || location.lon || location.longitude;
+      var near = "" + lat + "," + lng;
       return {"near": near};
     }
   };
@@ -30,22 +32,39 @@
     }
   }
 
+  var locationDeferred = function(invoker) {
+    var deferred = $.Deferred();
+    var positionCallback = function(position) {
+      var newDeferred = invoker(position.coords);
+      newDeferred.then(deferred.resolve, deferred.reject);
+    };
+    navigator.geolocation.getCurrentPosition(positionCallback, null, {maximumAge:600000});
+    return deferred;
+  }
+
   PerthTransit.get = function(path, options) {
     var url = this.urlFor(path, options);
-    var promise = $.getJSON(url)
+    var deferred = $.getJSON(url);
     var done   = function(data) { return data.response; };
     var failed = function(data) { return data; };
-    return promise.pipe(done, failed);
+    return deferred.pipe(done, failed);
   };
 
   PerthTransit.urlFor = function(path, options) {
     var fullURL = this.root + this.version + "/" + path + "?callback=?";
-    if(options !== undefined) {
-      fullURL = fullURL + "&" + $.param(options);
-    }
+    // We include the params if specified.
+    if(options) fullURL = fullURL + "&" + $.param(options);
     return fullURL;
   }
 
+  PerthTransit.nearbyTrainStations = function() {
+    return locationDeferred(function(location) { return PerthTransit.trainStations(location); });
+  };
+
+  PerthTransit.nearbyBusStops = function() {
+    return locationDeferred(function(location) { return PerthTransit.busStops(location); });
+  };
+
   PerthTransit.trainStations = function(location) {
     return this.get('train_stations', dataWithLocation(location));
   };
@@ -59,7 +78,7 @@
   };
 
   PerthTransit.busStop = function(stop) {
-    return this.get('bus_stops/' + extractIdentifier(station));
+    return this.get('bus_stops/' + extractIdentifier(stop));
   };
 
   PerthTransit.smartRider = function(smartRiderNumber) {