logo
Welcome Guest! To enable all features please Login or Register.

Notification

Icon
Error

Login


Options
View
Go to last post Go to first unread
Ryan  
#1 Posted : Thursday, September 1, 2011 9:38:09 AM(UTC)
Ryan

Rank: Administration

Groups: Administrators, Registered
Joined: 6/1/2011(UTC)
Posts: 88
United States
Location: Urbana

Thanks: 1 times
Was thanked: 6 time(s) in 6 post(s)
We are getting ready to start working on v1.1 of the API and we wanted to give our developers a chance to give us feedback on our proposed changes. Keep in mind that v1.0 will be unaffected and remain available at the current URL.

v1.1 Proposed Changes

  • JSONP callback support
    • We have actually already implemented this, but we will add official support in the documentation for this feature.
  • Web Service endpoint
    • We would like to add a web service endpoint to the API. This will make it easier for .NET and other frameworks to easily consume our API. It will aslo require a few changes in the way we do things which I will discuss later.
  • Add changeset_id parameter to static data
    • Many of the method calls contain large amounts of data and change very infrequently (e.g. stops.getList.) Currently the only way to track when this data changes is to watch the GTFS RSS feed. We are planning to start returning a changeset_id property with these calls which when passed back into the methods will only return data if it is newer. This will let you cache some of the large infrequently changing data sets.
  • Change all optional parameters to required
    • To support a WS endpoint we have to make all parameters required. We will still keep all the functionality of the current optional parameters. Since most of the optional parameters are just result filters we will still provide a way to get all data without a filter.
  • Add notifications when request limit is reached
    • Send developers email notifications when their key reaches it's request limit. We would like some feedback on how often you would like to be notified. Right now we are thinking once a day so that you don't get bombarded with emails if you hit your limit.
  • Add directions to trips
    • Add direction bit to to all trip objects. Add bit definition to all route objects. This will allow the data to stay consistent with GTFS, but will make the direction more distinct and accessible to developers.
  • Add block_id field to trips
    • A block_id is used to determine what a single physical vehicle does and can be used to determine if a bus switches routes.
  • Method name changes
    • In order to support a WS endpoint and to stay consistent across all our endpoints we will be renaming methods to remove the dot notation and underscores. For example calendar_dates.getListByDate will become getCalendarDateListByDate and departures.getListByStop will become getDepartureListByStop.
  • Add general status object to every request/remove err field and stat attribute
    • We've decided to make the status more general since not all codes are the result of errors or issues. (e.g. 304 Not Modified)
  • Change all dates to YYYYMMDD
    • To better match GTFS, we're changing all dates (responses and expected parameters) to YYYYMMDD.
  • Add route object to departures
    • We will add a route object to the getDepartureListByStop method. so it will look something like this:
      Code:
      
      {
         "departures":[
            {
               "destination":{
                  "stop_id":"WASHLRMN:2"
               },
               "direction":"EAST",
               "expected":"9/27/2011 12:08:08 PM",
               "headsign":"5E Green",
               "location":{
                  "lat":40.114507,
                  "lon":-88.245167
               },
               "monitored":true,
               "origin":{
                  "stop_id":"MPLPKLWNDL:1"
               },
               "route":{
                  "one_definition":"west",
                  "route_color":"00a638",
                  "route_id":"GREEN",
                  "route_long_name":"Green",
                  "route_short_name":"5",
                  "route_text_color":"000000",
                  "zero_definiton":"east"
               },
               "scheduled":"9/27/2011 12:08:00 PM",
               "shape_id":"5E",
               "stop_id":"IT:1",
               "trip_id":"5GN566",
               "vehicle_id":"1185"
            }
         ],
         "stat":{
            "code":200,
            "msg":"ok"
         }
      }
      

We would like to hear your feedback about these changes. Obviously these are incremental changes and we are not adding much new functionality. We will be looking at adding some major new functionality to the next release.

Edited by user Tuesday, November 29, 2011 4:43:17 PM(UTC)  | Reason: added bullet point

Benjamin  
#2 Posted : Saturday, September 3, 2011 12:39:42 PM(UTC)
Benjamin

Rank: Advanced Member

Groups: Registered
Joined: 7/10/2011(UTC)
Posts: 34

Thanks: 1 times
Ryan wrote:
Change all dates to YYYYMMDD

While you’re at it, I have two related feature requests…

  • Include a time zone in any date/time pairs you return. Something in a standard format like “Sat, 03 Sep 2011 18:29:33 +0000” would be great. (I guess maybe this conflicts with the change you’re proposing… are you talking about just removing the hyphens to go from “2011-09-03” to “20110903”?)
  • For all timely responses (responses whose values can be expected to change frequently, like departures.getListByStop), include a field including the server time. My app calculates the difference between the current time and the “expected” time from the API call and displays it to the user, but this will be wrong if the user’s clock is off. (I could update my app to check in with an NTP server periodically, but even then, what if the “official” time is different from the MTD server time? There would be the least potential for error if I got both the current time and the bus-arrival time “from the horse’s mouth”, as it were.)


Most of these changes don’t affect me, but I’m glad to see that CUMTD is sticking with this and continuing to improve their stuff! Nice work guys :-)

Edited by user Sunday, September 4, 2011 3:38:09 PM(UTC)  | Reason: The error information is available online

Sean  
#3 Posted : Tuesday, September 6, 2011 7:35:00 AM(UTC)
Sean

Rank: Administration

Groups: Administrators
Joined: 4/11/2011(UTC)
Posts: 42

Was thanked: 3 time(s) in 3 post(s)
Benjamin wrote:
  • Include a time zone in any date/time pairs you return. Something in a standard format like “Sat, 03 Sep 2011 18:29:33 +0000” would be great. (I guess maybe this conflicts with the change you’re proposing… are you talking about just removing the hyphens to go from “2011-09-03” to “20110903”?)


Changing the date format is feeling like a worse idea after the weekend. No matter what we do, we really need it to be consistent across the board for all methods so that all dates and times match the exact same format. Removing the hyphens will make the data match GTFS, but at the same time feels kind of goofy. Leaving the hyphens seems to work better with date/time combos and with adding time zones. Does it matter if our formatting differs from GTFS? What do you think Benjamin?

Edited by user Tuesday, September 6, 2011 7:36:10 AM(UTC)  | Reason: Not specified

Benjamin  
#4 Posted : Tuesday, September 6, 2011 10:23:36 AM(UTC)
Benjamin

Rank: Advanced Member

Groups: Registered
Joined: 7/10/2011(UTC)
Posts: 34

Thanks: 1 times
Sean wrote:
Changing the date format is feeling like a worse idea after the weekend. No matter what we do, we really need it to be consistent across the board for all methods so that all dates and times match the exact same format. Removing the hyphens will make the data match GTFS, but at the same time feels kind of goofy. Leaving the hyphens seems to work better with date/time combos and with adding time zones. Does it matter if our formatting differs from GTFS? What do you think Benjamin?

Well, I don’t use GTFS, but… my feeling is that parsing or emitting dates is really easy as long as you know in advance what the format needs to be. Trying to extract time zone information, on the other hand, is relatively difficult. I guess what I’m saying is that I’d have no problem with something funky like YYYYMMDD as long as I didn’t have to try to infer the time zone. (For me, I’d prefer just to put every date/time in the XML schema “2002-05-30T09:30:10-06:00” format, but I understand that you have to comply with the GTFS spec first and foremost.)
Sean  
#5 Posted : Tuesday, September 6, 2011 3:10:54 PM(UTC)
Sean

Rank: Administration

Groups: Administrators
Joined: 4/11/2011(UTC)
Posts: 42

Was thanked: 3 time(s) in 3 post(s)
Would you want time zones on dates as well as times?
Benjamin  
#6 Posted : Wednesday, September 7, 2011 12:03:17 AM(UTC)
Benjamin

Rank: Advanced Member

Groups: Registered
Joined: 7/10/2011(UTC)
Posts: 34

Thanks: 1 times
I’m not sure that’s necessary, but I also don’t really use dates per se, just times.
Sean  
#7 Posted : Thursday, September 8, 2011 8:53:24 AM(UTC)
Sean

Rank: Administration

Groups: Administrators
Joined: 4/11/2011(UTC)
Posts: 42

Was thanked: 3 time(s) in 3 post(s)
Do you want a timezone on arrival_time and departure_time of stop_time methods? Since stop_times don't represent a specific day, the timezone could vary with daylight savings time which is kind of a problem. Any suggestions?
Benjamin  
#8 Posted : Thursday, September 8, 2011 5:51:47 PM(UTC)
Benjamin

Rank: Advanced Member

Groups: Registered
Joined: 7/10/2011(UTC)
Posts: 34

Thanks: 1 times
Oh, that’s a good question. I’d be inclined to leave off the time zones for stop_time, with the times intended to be interpreted as CST or CDT as appropriate. How does CUMTD service work the night of the time change? Do the buses repeat/omit an hour, or do they run as if the time change hadn’t happened yet?
Islam  
#9 Posted : Tuesday, November 15, 2011 12:13:16 PM(UTC)
Islam

Rank: Newbie

Groups: Registered
Joined: 11/14/2011(UTC)
Posts: 3

This looks awesome! Going to hold out for this :)
Users browsing this topic
Forum Jump  
You cannot post new topics in this forum.
You cannot reply to topics in this forum.
You cannot delete your posts in this forum.
You cannot edit your posts in this forum.
You cannot create polls in this forum.
You cannot vote in polls in this forum.