API Guide: Reference

The Reference view in the API Guide provides in-depth information on each API call available for Swiftly data.

Access

The Reference can be accessed by navigating to "Menu" at the corner right side of your screen > API Guide > and clicking on the Reference tab.

Don't have permission to access this view? You'll need API Guide access. Please contact your Account Manager for instructions on how to obtain access.

Overview

The API Reference is very intuitive to use. Each endpoint contains information on the use case for each API, its available endpoints, parameters, and expected status codes. Below is a typical description of an API endpoint on the Swiftly API Guide tool.

⚠️  Are you interfacing with the API as an agency consultant or partner?

You can access the external API Reference Guide using Stoplight at:

https://swiftly-inc.stoplight.io/docs/swiftly-docs/6zpcgvbu5wbb3-swiftly-api-reference

Parameters

Each endpoint will show you the path parameters required to run an API call. These are typically required. 

On the other hand, query parameters are typically optional, but not always. Think of query parameters as filters for the data—they allow you to specify exactly what API information you want.

Responses

Did you receive an error 500? Was your query not successful? Use the responses tab to troubleshoot failed queries by looking at all non-200 responses.

Testing widget 

The final section of the reference documentation is a testing widget. This widget allows you to test an API call within the Swiftly platform and provides a way to see what kind of information you need to input plus the data output from API call. Details on how to run a test call below. 

In this example, I'll be using the "By Route" On-Time Performance API endpoint:

The only required parameters are:

1. “Path Parameter”: agencyKey

For this example, we’re using a Swiftly Demo dashboard so that the agencyKey will be swiftly-demo-small. The agencyKey comes from the URL of the Swiftly Dashboard for your agency once logged in, and is also listed in the “Introduction” tab for the API key:

• URL: https://dashboard.goswift.ly/swiftly-demo-small/api-guide/reference

2. “Query Parameter”: startDate

The startDate parameter needs a specific date format as described in the documentation:

“The query date range start date as a string in the format MM-DD-YYYY.”

• For the month of April 2025 this will be 04-01-2025
• Since we only want data for the month of April, an 'endDate' will be required which will be 04-30-2025

3. "Query Parameter": format=csv

Many of Swiftly's API will, by default, return in JSON. But this is not the data format you will need to import into a spreadsheet. Use this query parameter to return your requested data in CSV format, aka "comma separated values".

Here's how the API Request Panel should look:

There are many parameters available, depending on the endpoint, that will help you structure the API request for the data you're most interested in. Please review all query parameters to weigh your options on what data you'll need and it's structure. The more the data returned is "filtered" by parameters, the less data clean-up you'll need to do once you're working with it!

• Note that some queries will return full results once the "Send API Request" button is toggled, but other requests that return a large amount of data will not be successful – here you will need to use the Command Line or an HTTP Client.

Common pitfalls

I'm getting the following 403 error: "The included API key does not have access to this module and/or this agency".

Check your API Key to ensure you're correctly querying the right agency. If you have the correct API key selected, your key may not have enough permissions to query the agency's API endpoints.

Please feel free to reach out to [e-mail] for more help.

I'm getting an internal server error (500) when querying Speed Maps or On-time Performance.

Typically, this occurs when the startDate and endDate parameters cover too wide a data range and the query times out.

Try narrowing your queries to the next smallest interval until your query is successful.

For example:

If the request failed at startDate: 2025-01-01  and endDate: 2025-02-01, try reducing the range to two weeks: ex: startDate: 2025-01-14  and endDate: 2025-02-01