Services

Other versions

End to End Example

Here is an example of the steps that a GPS-enabled mobile application could take to use Winnipeg Transit's Open Data
Web Service to check the times that buses will be arriving at a stop near the user's current location.

Step 1: Check Service Status

The first thing that you should always do is check the Service Status under which Winnipeg Transit is operating. If
Blue or Red Priority Service is in effect, then any results received through the Open Data Web Service may not be
reliable. Here is an example that fetched the current Service Status:

https://api.winnipegtransit.com/v3/statuses/schedule

If this returns "blue" or "red" service, you should stop here and inform your users accordingly. Their best bet in
these cases is to visit winnipegtransit.com for the latest information. In all but these exceptional cases, this query
will return "regular", so continue to Step 2.

Step 2: Find Nearby Stops

Using the GPS coordinates available to the mobile device, you can issue a Stops request to identify nearby stops. Here
is an example:

This request will return stops within a certain distance of the given location, 250 meters for the given example. To
minimize redundant queries and maximize application response, you should cache the results for later use. This way if
a user selects one stop from these results but later selects a different stop, your application won't need to send
another identical request.

After the user selects a stop from the results, you will probably want to retrieve and display bus schedules for that
stop.

Step 3: Stop Schedules

The last and most useful step is to retrieve schedule information for that stop. These results are real-time, updated
based on what our vehicles report back to our central servers. Given a stop number, it is easy to get this information
using a Stop Schedule request:

The results returned by such a request are a little more complicated than those in the first two steps. In this XML
there will be 2 elements at the root, the first being a stop element that provides information about the stop that
these times are for. You already have this information from the previous step, so it can be ignored. The important
information is the route-schedules element, which contains information about when buses from different routes will be
at this stop.

The route-schedules element contains a list of route-schedule elements. Each route that has buses operating at the
stop within the requested time period will have route-schedule elements (the time period defaults to two hours from
the time that the request was made). A route-schedule element consists of two elements: route and scheduled-stops. The
route element has information about the route, like name and number, while the scheduled-stops element is a list of
scheduled-stop elements. These scheduled-stop elements contain bus departure information.

Each scheduled-stop element has both the estimated and scheduled times that the bus will arrive at that stop and leave
from the stop. An element has information about the bus's specific route variant (a route can have several different
variants) as well as information about the bus itself such as the bus number, whether or not that bus has a bike rack
installed, WiFi available, etc.

With this information you can show the user when buses will be arriving at the stop that they selected. You can also
do more powerful stuff like letting your users filter by things like route or bike racks.

It's important to note that a request like this is time sensitive, hence the times, buses, and even routes can and
will change depending on the date and time of day. While it might cut down on data usage to cache this data,
make sure that these results are refreshed regularly
so that your users will have the most accurate and up to date Winnipeg Transit data at their fingertips. It's
certainly better to refresh frequently (e.g. every few minutes) with a smaller window (e.g. 60 minutes into the
future) than to make less frequent, larger requests.

It is also important to remember that the time on our servers may differ from the time on the device making your
request. To help provide more accurate relative times we provide the query-time attribute which will contain the time
that our servers finished processing your request

Hopefully this helps you understand how to make use of Winnipeg Transit's Open Data Web Service. Good luck coding!