Transport for Ottawa, Canada Getting Started: API Access Guide

Getting started overview

Integrating with the Transport for Ottawa, Canada (OC Transpo) API allows developers to access real-time public transit data for the City of Ottawa. This includes information on bus routes, O-Train schedules, and trip planning capabilities, which can be used to build custom applications or enhance existing services. The OC Transpo API is a RESTful interface, primarily returning data in XML format, although JSON can often be parsed from the XML responses. Access is free for non-commercial use, with specific contact required for commercial applications.

This guide outlines the necessary steps to get started: obtaining API credentials, understanding the basic request structure, and making your first successful call to retrieve transit data. Familiarity with HTTP methods and XML data structures will be beneficial.

Here is a quick reference for the initial setup:

Create an account and get keys

To access the OC Transpo API, you need to obtain an Application ID and an API Key. These credentials serve to identify your application and manage access to the transit data. The process involves submitting an online request form on the official OC Transpo developer portal.

1. Navigate to the Developer Portal: Visit the OC Transpo Developer Page. This page provides an overview of the API and links to the necessary resources.
2. Locate the API Key Request Section: Scroll down to the section titled "API Key Request" or similar. This section will contain a link or embedded form for requesting access.
3. Complete the Request Form: You will be asked to provide details such as your name, email address, and a brief description of how you intend to use the API. For non-commercial use, access is generally granted without further negotiation. For commercial applications, you may be prompted to contact OC Transpo directly for specific terms and agreements. Ensure all required fields are accurately completed.
4. Receive Credentials: After submitting the form, OC Transpo will typically send your unique Application ID and API Key to the email address you provided. This process may take a short period for verification. Keep these credentials secure, as they are essential for all API interactions.

It is important to review the Terms of Use associated with the API to ensure your application complies with OC Transpo's policies, particularly regarding data usage and commercial applications.

Your first request

Once you have your Application ID and API Key, you can make your first call to the OC Transpo API. A common starting point is to retrieve a list of all routes or stop information. We will use the GetRouteSummaryForStop method as an example, which requires a stop number to retrieve routes serving that stop.

Prerequisites:

• Your Application ID and API Key.
• A known stop number (e.g., 3010 for a common stop in downtown Ottawa).
• A tool for making HTTP requests (e.g., curl, Postman, or a programming language's HTTP client).

API Endpoint Structure:

The base URL for the OC Transpo API is typically https://api.octranspo1.com/v1.2/. Each method is appended to this base URL, along with your credentials and method-specific parameters.

Example Request: GetRouteSummaryForStop

This method retrieves a summary of routes and their upcoming trips for a specific bus stop. The required parameters are AppID, ApiKey, and StopNo.

curl -X GET \
  "https://api.octranspo1.com/v1.2/GetRouteSummaryForStop?appID=YOUR_APP_ID&apiKey=YOUR_API_KEY&stopNo=3010"

Replace:

• YOUR_APP_ID with your actual Application ID.
• YOUR_API_KEY with your actual API Key.
• 3010 with any valid OC Transpo stop number you wish to query.

Expected Response (XML):

A successful response will return an XML document containing details about the routes serving the specified stop, including route numbers, directions, and upcoming trip times. The structure will resemble:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetRouteSummaryForStopResponse xmlns="http://tempuri.org/">
      <GetRouteSummaryForStopResult>
        <Error></Error>
        <RouteNo>95</RouteNo>
        <Direction>East</Direction>
        <Trips>
          <Trip>
            <TripStartTime>10:30</TripStartTime>
            <AdjustedScheduleTime>5</AdjustedScheduleTime>
            <BusType>60FT</BusType>
          </Trip>
          <Trip>
            <TripStartTime>10:45</TripStartTime>
            <AdjustedScheduleTime>20</AdjustedScheduleTime>
            <BusType>60FT</BusType>
          </Trip>
        </Trips>
      </GetRouteSummaryForStopResult>
    </GetRouteSummaryForStopResponse>
  </soap:Body>
</soap:Envelope>

This XML output provides the route number (e.g., 95), direction (East), and details for upcoming trips, including start times and estimated arrival adjustments. You would typically parse this XML in your application to extract the relevant data.

Common next steps

After successfully making your first API call, consider these next steps to further develop your application:

1. Explore More Endpoints: Review the full OC Transpo API reference to discover other available methods. Key methods include GetNextTripsForStop for real-time predictions, GetRouteInfo for detailed route paths, and GetStopInfo for stop locations.
2. Implement Error Handling: Integrate robust error handling into your code. The API returns error messages within the XML response (e.g., in the <Error> tag) if there are issues with your request (e.g., invalid stop number, expired API key).
3. Parse XML Responses: Develop robust XML parsing logic for the API responses. While the API returns XML, many programming languages offer libraries to easily parse XML into more manageable data structures (e.g., objects or dictionaries), or even convert it to JSON for easier processing.
4. Rate Limiting and Caching: Be mindful of potential rate limits. Although not explicitly detailed in the public documentation, it is good practice to cache data where appropriate to reduce the number of API calls, especially for static information like route details. Implement a back-off strategy for repeated requests.
5. Build a User Interface: Start building a front-end application to display the transit data. This could be a web application, a mobile app, or a desktop tool. Consider using mapping libraries like Google Maps Platform to visualize bus and train routes and stop locations.
6. Stay Updated: Periodically check the OC Transpo developer page for any updates to the API, new features, or changes in terms of service.

Troubleshooting the first call

Encountering issues with your initial API request is common. Here are some troubleshooting steps:

• Check Credentials: Double-verify that your appID and apiKey in the request URL exactly match the credentials provided to you. Any typo will result in an authentication failure.
• Verify Stop Number: Ensure the stopNo parameter uses a valid, existing OC Transpo stop number. An invalid stop number will prevent the API from returning relevant data. You can find valid stop numbers on the OC Transpo website or through other API methods if available.
• URL Encoding: Confirm that your API key and other parameters are correctly URL-encoded, especially if they contain special characters. Most HTTP client libraries handle this automatically, but if manually constructing URLs, it's a common oversight.
• Network Connectivity: Ensure your development environment has stable internet access and is not blocked by a firewall from reaching api.octranspo1.com.
• Examine API Response for Errors: Always inspect the XML response for an <Error> tag. The content within this tag often provides specific details about what went wrong (e.g., "Invalid Key", "Invalid Stop Number").
• Review Documentation: Refer back to the OC Transpo API documentation for the specific method you are calling. Pay close attention to required parameters and their expected formats.
• Use a Browser: For simple GET requests, try pasting the entire API URL (with your credentials) directly into a web browser. This can help confirm if the issue is with the URL itself or your client application.
• Contact Support: If you've exhausted other options, the OC Transpo developer page may provide contact information for technical support regarding API access.