timetable.service_times

[faultyserver]

Migrated from propershark/timetable_cpp#14:

It'd be useful to have an RPC to determine when a particular route makes stops at a station. This would allow clients to say something like:

"Route 13 stops here Mon-Fri, 7:00am-6:00pm, every 5 min"

So, the call would look something like

timetable.service_times(station, route)

and would return

• a range of weekday-times (e.g. Mon 07:00...Mon 18:00 or Tue 19:00...Wed 02:00) for a particular level of service
• the time interval between stop times

timetable.service_times(station, route) -> [ (Date Range, Visit Interval) ]

[faultyserver]

For clarity, I'm not going to copy over the existing discussion, as there wasn't really a consensus on the spec of this RPC. However, new discussions will be added here.

[faultyserver]

From a discussion on March 28th:

Discussed:

• Bound the search to the next 7 days
• Invariant: datetimes are always in the agency's timezone
• Should service intervals be bound to 24 hour periods, or should they carry
  over to the next day? e.g., if a visit interval continues from Saturday until
  2am on Sunday, should the visit interval on Saturday continue until 2am, or
  should it stop at midnight and be resumed as the first interval on Sunday?
• Intervals that wrap the midnight boundary represent the end of their
  time range as a duration since the most recent midnight. This should
  never be later than the start of the time range.
• Timetable may return any number of visit intervals: it is up to clients to
  choose what to do if a large number of intervals are returned.
  => Fix the 1024 message buffer (Responses limited to 1024 characters timetable_cpp#4)

Side notes:

• Versioning in Timetable: clients should be able to cache. Timetable should
  (at some point) keep a monotonically increasing version number of sorts, based
  on the GTFS data it holds.

timetable.service_times(station, route)
  -> [[date-of-service, [[time-range, visit-interval]...]...]

timetable.service_times('BUS123', '1B') ->
// Array of service records.
// This array will always contain 7 entries, each one representing a day of the
// week. The first entry will always correspond to the current date according
// to the RPC provider.
// In this example, the first entry is a Saturday. The final entry would be the
// following Friday.
[
  // Service record
  (
    // Date of service entry
    20170325, // = Saturday
    // Array of visit intervals
    [
      // Interval record
      (
        // time range of visit interval
        (06:45:00, 07:50:00),
        // visit interval
        00:00:10
      ),
      // mid-day changes to a service's visit interval are represented as
      // separate elements in the intervals array.
      ((08:00:00, 16:55:00), 00:00:05), // = 8am- 4:55pm, every  5 minutes
      ((17:00:00, 22:50:00), 00:00:10)  // = 5pm-10:50pm, every 10 minutes
    ]
  ),
  
  // Dates with only one interval record will still contain that record in an
  // array to maintain consistency.
  (
    20170326, // = Sunday
    [
      ((00:00:00, 03:00:00), 00:00:30),  // = 5pm-10:50pm, every 10 minutes
      ((09:00:00, 22:00:00), 00:00:30),
      // Intervals that wrap the midnight boundary represent the end of their
      // time range as a duration since the most recent midnight. This *should*
      // never be later than the start of the time range.
      ((22:00:00, 03:00:00), 00:00:30)  // = 5pm-10:50pm, every 10 minutes
    ]
  ),

  // For consistency, dates on which no service is provided will contain a blank
  // array value.
  (
    20170327, // = Monday
    []
  ),

  // Even if multiple dates contain the same interval records, they will be
  // listed as distinct service records. It is the client's responsibility to
  // group these records by date if desired.
  (
    20170328, // = Tuesday
    [
      ((06:45:00, 07:50:00), 00:00:10),
      ((08:00:00, 16:55:00), 00:00:05),
      ((17:00:00, 22:50:00), 00:00:10)
    ]
  )
  
  ...
]

[faultyserver]

I think we've reached a consensus on what the call and response will look like, as well as most of the semantics involved. I'm going to accept this and start working on the actual specification tonight.

[faultyserver]

Closing as implemented by #6.