Transport for London Buses node

[zobalogh]

Introduction

TODO: Discuss "search mode". => ask me

• Search mode would be some way to make a query node operate with dynamic settings coming in as input. In search mode a bus query node could feed back bus information about nearby stops to the flow so that then a more appropriate query could then be sent to the same or a second bus query node. This is a very hazy idea but without designing something, it's hard to use the query node dynamically.

This node will use the Transport for London (TfL) provided "Live bus and river bus arrivals API". The API is documented as http://www.tfl.gov.uk/cdn/static/cms/documents/tfl-live-bus-and-river-bus-arrivals-api-documentation.pdf .

These nodes are Bus Stop focused. (Get bus stop data or events related to bus stops.)

Generally, we have the following two main scenarios we'd like to support:

• Send a notification when a bus is about to approach/have left a particular bus stop: So that I leave home just in time to catch the bus => Input node
• Send me bus departure/arrival information for the bus stop closest to a certain location or an exact bus stop: Useful for when I'm standing at a particular bus stop and waiting for buses. => Query node

TfL has more than 19000 bus stops, 700 bus routes and 8000 buses. Therefore listing all of them as options in a node are not viable.

• Therefore the UI will support a two stage bus stop selector interface (both input and query nodes), where the user has to specify a pair of latitude and longitude coordinates and a radius. Using this, only bus stops within this radius will be listed.
• Alternatively, the bus stop selector should support finding the closest bus stop to the user's current location. (No radius is specified)
• Future versions could perhaps do more intelligent searches where a final destination is also considered for the buses serving a particular stop. This will NOT be implemented under this issue.

Input Node

The main purpose of the input node is to send out a notification message when certain events happen at bus stops. Examples: bus arrival, bus departure. => trigger a message.

Alternatively trigger a message n time before bus arrival.

• UI options, NOT passed to flow:
  • lat/lon:Find a bus stop at a particular location
  • radius: Find a bus stop within a particular radius (using lat and lon). 0 Radius means finding nearest stop.
• node options:
  • TfL Credentials: stored in credentials
  • Bus Stop: a drop down from which the user selects the actual bus stop. The option actually just sets a particular bus stop ID integer (as per API)
  • Arrival/Departure: Whether we're interested in bus's departure/arrival
  • Line number (fetch for particular bus stop, show as drop down): Which bus line/route we're interested in
  • Advance notice (milliseconds): How much advance notice do we want before the actual departure/arrival is predicted to happen?

The node refreshes state every 30 seconds as the API refreshes its state this frequently.

Query Node

The query node is mainly used to get status for a particular bus stop if we are already waiting at the stop for a bus. It can give us information about when a particular bus arrives/leaves the stop. The arrival/departure prediction is queried & then sent upon incoming input message.

• UI options, NOT passed to flow:
  • lat/lon:Find a bus stop at a particular location
  • radius: Find a bus stop within a particular radius (using lat and lon). 0 Radius means finding nearest stop.
• node options:
  • TfL Credentials: stored in credentials
  • Bus Stop: a drop down from which the user selects the actual bus stop. The option actually just sets a particular bus stop ID integer (as per API)
  • Arrival/Departure: Whether we're interested in bus's departure/arrival
  • Line number (fetch for particular bus stop, show as drop down): Which bus line/route we're interested in.

Issues to be considered

• API endpoint is http://countdown.api.tfl.gov.uk/interfaces/ura/instant_V1
• API returns JSON but it might not match all standards apparently due to "performance reasons" apparently
• The user needs to register with TfL and the user also needs to register their IP address as an approved client
• Node settings dialog must say "Data provided by Transport for London"
• Important factor to consider: stop closures, messages relating to certain stops => do we want to show/list closed stops?
• currently we're on v 1.5 of the API
• apparently a bus stop might not have any real time info attached to it, this is to be handled
• null values in StopCode1, StopCode2, StopPointType or StopPointIndicator might mean that the stop is out of service or is a bus stand
• StopID is the primary data key
• Lat and lon data for a particular bus stop might be returned in scientific notation (example 1.87E-4)
• Bus stops have a property of stopPointType which could signal a "dummy" stop or stops for announcement systems, etc. Referring to the docs is essential.

Example flows:

* I'm at home, my home geocoordinates are X, Y. I'm heading to work. I need notification when to leave home (takes me 5 minutes to walk to bus stop). So I need to get a 7 minute advance warning when bus number N is about to depart from stop.

[zobalogh]

@knolleary Ready for initial review. Thanks === > EDIT: actually, we'll discuss it tomorrow whether we're focusing on TfL or Fitness this sprint. So maybe it wasn't the smartest idea for me to open these issues (and asking @Raminios to open another issue.) Anyway, a design is here now and let's keep it here until we're deciding on priorities.

[zobalogh]