Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

timetable.service_times #1

Closed
faultyserver opened this issue Mar 28, 2017 · 4 comments
Closed

timetable.service_times #1

faultyserver opened this issue Mar 28, 2017 · 4 comments

Comments

@faultyserver
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Member Author

Closing as implemented by #6.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant