API (v1)
Overview (deprecated)Services
- Destinations
- Locations
- Routes
- Service Advisories
- Statuses
- Stop Features
- Stop Schedules
- Stops
- Streets
- System Messages
- Time
- Trip Planner
- Variants
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 an Emergency Service Plan 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/v1/statuses/schedule?api-key=YOUR-API-KEY
If this returns "esp-1", "esp-2", or "esp-3" 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:
https://api.winnipegtransit.com/v1/stops?lon=-97.138&lat=49.895&distance=250&api-key=YOUR-API-KEY
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:
https://api.winnipegtransit.com/v1/stops/10541/schedule?max-results-per-route=2&api-key=YOUR-API-KEY
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!