Permalink
Browse files

Document more API endpoints

  • Loading branch information...
1 parent e9de3ef commit b45542c7a142b9fd98955ddb9c15cd052333ab67 @Sutto committed Sep 27, 2012
Showing with 124 additions and 12 deletions.
  1. +8 −0 README.md
  2. +2 −1 app/models/bus_stop.rb
  3. +2 −2 app/models/train_station.rb
  4. +103 −1 doc/api/busses.md
  5. +9 −8 doc/api/trains.md
View
@@ -1,5 +1,13 @@
# Transperth API
+## Want to use the API?
+
+Howdy partner! This API is running for use in building applications.
+
+To find out more, visit the [hosted API documentation](http://doc.perthtransit.com/).
+
+## About
+
This sample app is an example application for [RocketPants](https://github.com/filtersquad/rocket_pants) and makes use
of ActiveRecord, RocketPants and API Smith for an API client.
View
@@ -29,7 +29,8 @@ def self.import!
end
def serializable_hash(options = {})
- result = super only: %w(id stop_number display_name description lat lng)
+ result = super only: %w(stop_number display_name description lat lng)
+ result['identifier'] = stop_number
if options[:compact]
result['compact'] = true
else
@@ -39,9 +39,9 @@ def times
def serializable_hash(options = {})
if options[:compact]
- super(:only => [:name, :lat, :lng, :cached_slug]).merge 'compact' => true
+ super(:only => [:name, :lat, :lng]).merge 'compact' => true, 'identifier' => cached_slug
else
- super(:only => [:name, :lat, :lng, :cached_slug], :methods => 'times').merge 'compact' => false
+ super(:only => [:name, :lat, :lng], :methods => 'times').merge 'compact' => false, 'identifier' => cached_slug
end
end
View
@@ -1,3 +1,105 @@
# Bus Times
-## Getting busses for a specific stop
+## Getting stops near a given location
+
+To get a list of bus stops near a given location, you need to
+hit the `/1/bus_stops` location with a `near` paramter specifying
+formatted `lat,lng` pair.
+
+This will return the five closest bus stops within 2.5km of the specified coordinate.
+
+```http
+GET /1/bus_stops?near=-32.1366,116.0176 HTTP/1.1
+```
+
+```http
+HTTP/1.1 200 OK
+Cache-Control: max-age=180, public, must-revalidate
+Content-Type: application/json; charset=utf-8
+
+{
+ "count": 5,
+ "response": [{
+ "compact": true,
+ "description": null,
+ "display_name": "Albany Hwy After Galliers Av",
+ "lat": "-32.1365533333333",
+ "lng": "116.017569444444",
+ "stop_number": "10004",
+ "identifier": "10004"
+ }, {
+ "compact": true,
+ "description": null,
+ "display_name": "Albany Hwy Before Carawatha Av",
+ "lat": "-32.1359372222222",
+ "lng": "116.017875",
+ "stop_number": "10205",
+ "identifier": "10205"
+ }, {
+ "compact": true,
+ "description": null,
+ "display_name": "Albany Hwy Before Caroline St",
+ "lat": "-32.1376488888889",
+ "lng": "116.017727777778",
+ "stop_number": "10206",
+ "identifier": "10206"
+ }, {
+ "compact": true,
+ "description": null,
+ "display_name": "Albany Hwy After Rogers L",
+ "id": 24421,
+ "lat": "-32.1391138888889",
+ "lng": "116.017382222222",
+ "stop_number": "10003",
+ "identifier": "10003"
+ }, {
+ "compact": true,
+ "description": null,
+ "display_name": "Albany Hwy After Caroline St",
+ "lat": "-32.1394066666667",
+ "lng": "116.01758",
+ "stop_number": "10207",
+ "identifier": "10207"
+ }]
+}
+```
+
+## Getting busses for a specific stop
+
+Finally, from a specific bus stop, you can get a list of times for the given bus stop.
+
+Please note that these are only scheduled times and do not necessarily reflect the busses current status.
+
+```http
+GET /1/bus_stops/12331 HTTP/1.1
+```
+
+```http
+HTTP/1.1 200 OK
+Cache-Control: max-age=180, public, must-revalidate
+Content-Type: application/json; charset=utf-8
+
+{
+ "response": {
+ "description": "Wanneroo Rd / Beach Rd",
+ "display_name": "Wanneroo Rd After Beach Rd",
+ "id": 26542,
+ "lat": "-31.8436127777778",
+ "lng": "115.823664444444",
+ "stop_number": "12331",
+ "times": [{
+ "approximate": false,
+ "comment": null,
+ "destination": "To Wellington St Bus Stn",
+ "route": "388",
+ "time": "19:35"
+ }, {
+ "approximate": true,
+ "comment": null,
+ "destination": "To Morley Bus Stn",
+ "route": "371",
+ "time": "19:41"
+ }]
+ }
+}
+```
View
@@ -26,21 +26,21 @@ Content-Type: application/json; charset=utf-8
{
"count": 69,
"response": [{
- "cached_slug": "armadale",
+ "identifier": "armadale",
"compact": true,
"lat": "-32.1376083",
"lng": "116.0104606",
"name": "Armadale",
"url": "http://api.perthtransit.com/1/train_stations/armadale"
}, {
- "cached_slug": "ashfield",
+ "identifier": "ashfield",
"compact": true,
"lat": "-31.9129489",
"lng": "115.9359944",
"name": "Ashfield",
"url": "http://api.perthtransit.com/1/train_stations/ashfield"
}, {
- "cached_slug": "bassendean",
+ "identifier": "bassendean",
"compact": true,
"lat": "-31.9037106",
"lng": "115.94718",
@@ -53,7 +53,8 @@ Content-Type: application/json; charset=utf-8
## Nearby Train Stations
By providing a `near` parameter with a formatted `lat,lng` pair, you can filter
-to only stations within a five kilometre distance from the specified location.
+to only stations within a 2.5 kilometre distance from the specified location up
+to a limit of 5.
For example,
@@ -69,21 +70,21 @@ Content-Type: application/json; charset=utf-8
{
"count": 3,
"response": [{
- "cached_slug": "armadale",
+ "identifier": "armadale",
"compact": true,
"lat": "-32.1376083",
"lng": "116.0104606",
"name": "Armadale",
"url": "http://api.perthtransit.com/1/train_stations/armadale"
}, {
- "cached_slug": "sherwood",
+ "identifier": "sherwood",
"compact": true,
"lat": "-32.1376083",
"lng": "116.0104606",
"name": "Sherwood",
"url": "http://api.perthtransit.com/1/train_stations/sherwood"
}, {
- "cached_slug": "challis",
+ "identifier": "challis",
"compact": true,
"lat": "-32.1263406",
"lng": "116.0129372",
@@ -113,7 +114,7 @@ Etag: "example-etag-goes-here"
{
"response": {
- "cached_slug": "perth",
+ "identifier": "perth",
"compact": false,
"lat": "-31.9510908",
"lng": "115.8599254",

0 comments on commit b45542c

Please sign in to comment.