Skip to content

Back end REST API dokumentaatio

Jump to bottom
Antti Saikkonen edited this page Dec 12, 2016 · 6 revisions

STOP 2.0 WEB API

Served currently in two different addresses:

"Test" server (used by the mobile production apps): http://stop20.herokuapp.com

Server intended for front end development: http://stop20-dev.herokuapp.com

Overview

GET: /stops

  • query parameter: lat: integer
  • query parameter: lon: integer
  • query parameter: rad: integer OPTIONAL (default 160)

Returns list of stops (max. 5) within coordinates and the vehicles that stop there (max. 30min).

GET: /stops/beacons

  • query parameter: major: integer
  • query parameter: minor: integer

Returns list of stops (max. 5) within radius of the specific beacon and the vehicles that stop there (max. 30min).

POST: /stoprequests

  • body format: JSON
  • fields:
    • trip_id: string
    • stop_id: string
    • device_id: string OPTIONAL
    • push_notification: boolean OPTIONAL (default: true)

Make a stop request at given stop for given trip. Optionally (for mobile users) add device id to receive a push notification when the vehicle is close to arriving at the stop. Returns an id for the request (needed for canceling).

POST: /stoprequests/cancel

  • query parameter: request_id: integer

Cancel given request.

POST: /stoprequests/report

  • body format: JSON
  • fields:
    • trip_id: string
    • stop_id: string

For vehicle drivers to report when no one leaves or boards the vehicle even though there were stop requests.

GET: /routes

  • query parameter: trip_id: string
  • query parameter: stop_id: string OPTIONAL

Returns a list of stops on the trips route. If a stop id is given only information regarding that specific stop is returned.

POST: /vehicles/beacons

  • body format: JSON
  • fields:
    • beacons: array of major and minor string pairs

Returns a list of vehicles found with the beacon values.

Exceptions

If there's something wrong about your request you should get a response that tells you more about it:

{
    "error": "descriptive message"
}

If your request or our code is very wrong you will get some default Heroku internal server error response:

< some html />

Examples

GET: http://stop20.herokuapp.com/stops?lat=60.19350&lon=24.90646&rad=200

Response:

{
  "stops": [
    {
      "stop": {
        "distance": 6,
        "schedule": [
          {
            "arrival": 5,
            "destination": "Pikku Huopalahti",
            "line": "10",
            "route_id": "HSL:1010",
            "trip_id": "HSL:1010_20161031_Su_1_1849",
            "vehicle_type": 0
          },
          ...
        ],
        "stop_code": "0135",
        "stop_id": "HSL:1180439",
        "stop_name": "Jalavatie"
      }
    },
    ...
  ]
}

GET: http://stop20.herokuapp.com/stops/beacons?major=10&minor=10

Response:

{
  "stops": [
    {
      "stop": {
        "distance": 6,
        "schedule": [
          {
            "arrival": 11,
            "destination": "Pikku Huopalahti",
            "line": "10",
            "route_id": "HSL:1010",
            "trip_id": "HSL:1010_20161031_Su_1_1901",
            "vehicle_type": 0
          },
          ...
        ],
        "stop_code": "0135",
        "stop_id": "HSL:1180439",
        "stop_name": "Jalavatie"
      }
    },
    ...
  ]
}

POST: http://stop20.herokuapp.com/stoprequests

{
	"trip_id": "HSL:1010_20161031_Su_1_1901",
	"stop_id": "HSL:1180439",
	"device_id": "e8goxp95Rjw:APA91bFP49-bAzXbw_mfgrEc7wQ6-yKva2DDgJMnSz-mSiIOfylGjylnoiszi-Av2e09JJgj5Q9ucMUINJy7zs291zi7m6NfT8Eic6CX2iug-Uixt-kt-qSQYmuy5sadfkNjnsj"
}

Response:

{
  "request_id": 9
}

POST: http://stop20.herokuapp.com/stoprequests/cancel?request_id=9

Response: empty body if it succeeds

GET: http://stop20.herokuapp.com/routes?trip_id=HSL:1010_20161031_Su_1_1901

Response:

{
  "stops": [
    {
      "arrives_in": -11,
      "stop_code": "0708",
      "stop_id": "HSL:1070425",
      "stop_name": "Tarkk´ampujankatu"
    },
    ...
  ]
}

POST: http://stop20.herokuapp.com/vehicles/beacons

{
    "beacons": [
        {
            "major": "100",
            "minor": "100"
        },
        ...
    ]
}

Response:

{
    "vehicles": [
        {
            "major":"1111",
            "minor":"2222",
            "trip_id":"HSL:1070T_20161201_Ma_2_1419",
            "line":"70T",
            "destination":"Kamppi via Ooppera",
            "vehicle_type": 3
        },
        {
            "major":"1234",
            "minor":"5678",
            "error":"No realtime data from the bus"
        }
    ]
}
Clone this wiki locally