Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fix the JS api, add more docs

  • Loading branch information...
commit be946c8e06b85903defafcf89e93d2a78109238b 1 parent 240ba8f
@Sutto authored
View
141 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);
+});
+```
View
2  js-api/perth_transit-1.0-min.js
@@ -4,4 +4,4 @@
// Requires: jQuery
// License: MIT
// Copyright: Darcy Laycock
-(function(e,t){var n={version:1,root:"http://api.perthtransit.com/"},r=function(e){if(e===t)return null;var n=""+e.lat+","+e.lng;return{near:n}},i=function(e){var t=typeof e;return t==="number"||t==="string"?""+e:e.identifier};n.get=function(t,n){var r=this.urlFor(t,n),i=e.getJSON(r),s=function(e){return e.response},o=function(e){return e};return i.pipe(s,o)},n.urlFor=function(n,r){var i=this.root+this.version+"/"+n+"?callback=?";return r!==t&&(i=i+"&"+e.param(r)),i},n.trainStations=function(e){return this.get("train_stations",r(e))},n.trainStation=function(e){return this.get("train_stations/"+i(e))},n.busStops=function(e){return this.get("bus_stops",r(e))},n.busStop=function(e){return this.get("bus_stops/"+i(station))},n.smartRider=function(e){return this.get("smart_riders/"+e)},window.PerthTransit=n})(jQuery);
+(function(e,t){var n={version:1,root:"http://api.perthtransit.com/"},r=function(e){if(!e)return null;var t=e.lat||e.latitude,n=e.lng||e.lon||e.longitude,r=""+t+","+n;return{near:r}},i=function(e){var t=typeof e;return t==="number"||t==="string"?""+e:e.identifier},s=function(t){var n=e.Deferred(),r=function(e){var r=t(e.coords);r.then(n.resolve,n.reject)};return navigator.geolocation.getCurrentPosition(r,null,{maximumAge:6e5}),n};n.get=function(t,n){var r=this.urlFor(t,n),i=e.getJSON(r),s=function(e){return e.response},o=function(e){return e};return i.pipe(s,o)},n.urlFor=function(t,n){var r=this.root+this.version+"/"+t+"?callback=?";return n&&(r=r+"&"+e.param(n)),r},n.nearbyTrainStations=function(){return s(function(e){return n.trainStations(e)})},n.nearbyBusStops=function(){return s(function(e){return n.busStops(e)})},n.trainStations=function(e){return this.get("train_stations",r(e))},n.trainStation=function(e){return this.get("train_stations/"+i(e))},n.busStops=function(e){return this.get("bus_stops",r(e))},n.busStop=function(e){return this.get("bus_stops/"+i(e))},n.smartRider=function(e){return this.get("smart_riders/"+e)},window.PerthTransit=n})(jQuery);
View
35 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) {
Please sign in to comment.
Something went wrong with that request. Please try again.