RouteShout API

Introduction

Get an API Key

Login to manage your API Key

RouteShout exposes its data via an Application Programming Interface (API). The API is available for free for non-commercial use by outside developers. To perform an action using the API, you need to select a method and send a request to its endpoint with appropriate named parameters. Getting started with the RouteShout API is easy. Read on.

Data Disclaimer

RouteShout is a product of RouteMatch, Inc. RouteShout relies on the General Transit Feed Spec. (GTFS) for data collection. Transit agencies available within RouteShout either provide their GTFS data publicly or have data agreements directly with RouteShout. By accessing or using the RouteShout API you are agreeing to the RouteShout/Deeplocal Terms of Service and Privacy Policy along with any agency specific developer agreements.

If you're interested in adding data from a transit agency not in RouteShout, please email the URL to the agency's GTFS data files to support@routematch.com.

Note: If you are a transit agency and would rather not have your data in RouteShout, please contact us immediately at support@routematch.com.

Authentication

The API has very basic authentication, done by passing a unique API Key as a HTTP Get parameter key with each request. Since everyone has access to the same set of data, the primary use for authentication is caching and logging.

Response Format & Codes

This API currently relies strictly on the JSON format. Every response will always contain a hash with a status key, returning either 'ok' or 'fail'.

Success case: returns a hash with two or three keys, such as status, results and meta (not always included).

status (string) "ok"
response (array|hash) containing the result set
meta (hash) containing the total results available, current limit and offset values

Fail case: returns a hash with two keys, status and error.

status (string) "fail"
error (string) describes the error

Every response is accompanied by one of the following HTTP response codes:

200 success
401 unauthenticated
403 invalid authentication
500 server-side error

Support & Bugs

Please submit your support requests, bug reports and suggestions to the RouteShout Transit API support group.

Methods

rs.agencies.getList

Get a list of all available transit agencies in the system.

http://api.routeshout.com/v1/rs.agencies.getList?key=[api-key] 

{
	"response": [
		{
			"title": "Disney Transit",
			"timezone": "America/New_York",
			"id": 20,
			"state": "Florida"
		},
		{
			"title": "Lane Transit District",
			"timezone": "America/Los_Angeles",
			"id": 45,
			"state": "Oregon"
		},
		{
			"title": "Milwaukee County Transit System",
			"timezone": "America/Chicago",
			"id": 25,
			"state": "Wisconsin"
		},
		{
			"title": "Olympics",
			"timezone": "America/New_York",
			"id": 31,
			"state": "California"
		},
		...
	],
	"meta": [
		"total": 125,
		"limit": null,
		"offset": 0
	],
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.agencies.getList
Params
key [required] your API Key
limit limit # of results
offset offset the result-set (for pagination)
Returns
an array of agencies, with each item containing the following:
id transit agency unique id
title transit agency name
state transit agency state (currently USA only)
timezone timezone (ex: America/New_York)

rs.routes.getList

Get a list of all routes for a specific agency.

http://api.routeshout.com/v1/rs.routes.getList?key=[api-key]&agency=[agency-id] 

{
	"response": [
		{
			"type": 0,
			"short_name": "052",
			"long_name": "ALLENTOWN - GATEWAY CENTER VIA ALLENTOWN - I",
			"id": "52-I"
		},
		{
			"type": 0,
			"short_name": "052",
			"long_name": "ALLENTOWN - S HILLS JUNCTION VIA ALLENTOWN - O",
			"id": "52-O"
		},
		{
			"type": 3,
			"short_name": "100",
			"long_name": "WEST BUSWAY - ALL STOPS TO CARNEGIE - O",
			"id": "100-O"
		},
		{
			"type": 3,
			"short_name": "100",
			"long_name": "WEST BUSWAY - ALL STOPS TO DOWNTOWN & OAKLAND - I",
			"id": "100-I"
		},
		...
	],
	"meta": [
		"total": 125,
		"limit": null,
		"offset": 0
	],
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.routes.getList
Params
key [required] your API Key
agency [required] transit agency id
limit limit # of results
offset offset the result-set (for pagination)
Returns
an array of routes, with each item containing the following:
id route unique id
short_name route short name (ex: 500)
long_name route long name (ex: BELLEVUE - WEST VIEW OAKLAND-DOWNTOWN)
type 0 - Tram, Streetcar, Light rail.
1 - Subway, Metro.
2 - Rail.
3 - Bus (most often used).
4 - Ferry.
5 - Cable car.
6 - Gondola, Suspended cable car.
7 - Funicular.

rs.stops.getList

Get a list of all stops for a specific agency (and route).

http://api.routeshout.com/v1/rs.stops.getList?key=[api-key]&agency=[agency-id]&route=[route-id] 

{
	"response": [
		{
			"lon": -79.98854,
			"code": "S00030",
			"name": "10TH ST AT MURIEL",
			"id": "S00030",
			"lat": 40.429976
		},
		{
			"lon": -79.99499,
			"code": "P00330",
			"name": "2ND AVE OPP #622",
			"id": "P00330",
			"lat": 40.435944
		},
		{
			"lon": -79.964154,
			"code": "S05830",
			"name": "BECKS RUN RD AT #785",
			"id": "S05830",
			"lat": 40.408798
		},
		{
			"lon": -79.956593,
			"code": "TP7083",
			"name": "BECKS RUN RD AT E CARSON NS - NO STOP",
			"id": "TP7083",
			"lat": 40.4107262
		},
		...
	],
	"meta": [
		"total": 125,
		"limit": null,
		"offset": 0
	],
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.stops.getList
Params
key [required] your API Key
agency [required] transit agency id
route route id
limit limit # of results
offset offset the result-set (for pagination)
Returns
an array of stops, with each item containing the following:
id stop unique id
name stop name (ex: PENN MALL STATION AT SHELTER #1)
code stop display code (ex: PENNMALLA)
lat latitude of the stop location
lon longitude of the stop location

rs.stops.getListByTrip

Get a list of all stops and their arrival and departure times for a specific trip.

http://api.routeshout.com/v1/rs.stops.getListByTrip?key=[api-key]&agency=[agency-id]&trip=[trip-id]

{
	"response": [
		{
			"lon": -80.255573,
			"code": "W08025",
			"name": "PGH INTERNL AIRPORT LOWER LEVEL (DOOR 6)",
			"id": "W08025",
			"lat": 40.496082,
			"arrival_time": "08:37 AM",
			"departure_time": "08:37 AM",
			"sequence": 1
		},
		{
			"lon": -80.226807,
			"code": "W70047",
			"name": "MOON PARK N RIDE AT SHELTER",
			"id": "W70047",
			"lat": 40.504142,
			"arrival_time": "08:38 AM",
			"departure_time": "08:38 AM",
			"sequence": 2
		},
		{
			"lon": -80.222287,
			"code": "W23828",
			"name": "UNIVERSITY BLVD AT MOON PARK-N-RIDE",
			"id": "W23828",
			"lat": 40.502672,
			"arrival_time": "08:40 AM",
			"departure_time": "08:40 AM",
			"sequence": 3
		},
		{
			"lon": -80.222892,
			"code": "W23810",
			"name": "UNIVERSITY BLVD AT ALLEGHENY RESIDENCE",
			"id": "W23810",
			"lat": 40.5046533,
			"arrival_time": "08:42 AM",
			"departure_time": "08:42 AM",
			"sequence": 4
		},
		...
	],
	"meta": [
		"total": 125,
		"limit": null,
		"offset": 0,
		"route": {
			"type": 3,
			"short_name": "100",
			"long_name": "WEST BUSWAY - ALL STOPS TO DOWNTOWN & OAKLAND - I",
			"id": "100-I"
		}
	],
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.stops.getListByTrip
Params
key [required] your API Key
agency [required] transit agency id
trip [required] trip id
limit limit # of results
offset offset the result-set (for pagination)
Returns
an array of stops, with each item containing the following:
id stop unique id
name stop name (ex: PENN MALL STATION AT SHELTER #1)
code stop display code (ex: PENNMALLA)
lat latitude of the stop location
lon longitude of the stop location
arrival_time arrival time at the stop
departure_time departure time from the stop
sequence position of the stop for the requested trip

rs.stops.getListByLocation

Get a list of all stops for a specific agency (and route) ordered by distance from location.

http://api.routeshout.com/v1/rs.stops.getListByLocation?key=[api-key]&agency=[agency-id]&lat=[latitude]&lon=[longitude] 

{
	"response": [
		{
			"lon": -80.255573,
			"distance": 0,
			"code": "W08025",
			"name": "PGH INTERNL AIRPORT LOWER LEVEL (DOOR 6)",
			"id": "W08025",
			"lat": 40.496082
		},
		{
			"lon": -80.226807,
			"distance": 2592,
			"code": "W70047",
			"name": "MOON PARK N RIDE AT SHELTER",
			"id": "W70047",
			"lat": 40.504142
		},
		{
			"lon": -80.222287,
			"distance": 2908,
			"code": "W23828",
			"name": "UNIVERSITY BLVD AT MOON PARK-N-RIDE",
			"id": "W23828",
			"lat": 40.502672
		},
		{
			"lon": -80.222892,
			"distance": 2923,
			"code": "W23810",
			"name": "UNIVERSITY BLVD AT ALLEGHENY RESIDENCE",
			"id": "W23810",
			"lat": 40.5046533
		},
		...
	],
	"meta": [
		"total": 125,
		"limit": null,
		"offset": 0
	],
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.stops.getListByLocation
Params
key [required] your API Key
agency [required] transit agency id
lat [required] latitude of the location (+/-90)
lon [required] longitude of the location (+/-180)
route route id
limit limit # of results
offset offset the result-set (for pagination)
Returns
an array of stops, with each item containing the following:
id stop unique id
name stop name (ex: PENN MALL STATION AT SHELTER #1)
code stop display code (ex: PENNMALLA)
lat latitude of the stop location
lon longitude of the stop location
distance stop's distance from the location (in meters)

rs.stops.getInfo

Get info on a specific stop.

http://api.routeshout.com/v1/rs.stops.getInfo?key=[api-key]&agency=[agency-id]&stop=[stop-id] 

{
	"response": {
		"id": "W23828",
		"name": "UNIVERSITY BLVD AT MOON PARK-N-RIDE",
		"code": "W23828",
		"lat": 40.502672,
		"lon": -80.222287
	},
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.stops.getInfo
Params
key [required] your API Key
agency [required] transit agency id
stop [required] stop id
Returns
hash containing stop info such as:
id stop unique id
name stop name (ex: PENN MALL STATION AT SHELTER #1)
code stop display code (ex: PENNMALLA)
lat latitude of the stop location
lon longitude of the stop location

rs.stops.getTimes

Get a list of upcoming stops for a specific agency and stop (within next 2 hours).

http://api.routeshout.com/v1/rs.stops.getTimes?key=[api-key]&agency=[agency-id]&stop=[stop-id] 

{
	"response": [
		{
			"type": "scheduled",
			"route_short_name": "89A",
			"arrival_time": "08:33 AM",
			"route_long_name": "GARFIELD HTS - IB",
			"departure_time": "08:33 AM"
		},
		{
			"type": "scheduled",
			"route_short_name": "81B",
			"arrival_time": "08:34 AM",
			"route_long_name": "LINCOLN HILL DISTRICT - O",
			"departure_time": "08:34 AM"
		},
		{
			"type": "scheduled",
			"route_short_name": "86B",
			"arrival_time": "08:37 AM",
			"route_long_name": "FRANKSTOWN STRIP DISTRICT - O",
			"departure_time": "08:37 AM"
		},
		...
	],
	"meta": {
		"timezone": "America/New_York"
	}
	"status": "ok"
}
URL http://api.routeshout.com/v1/rs.stops.getTimes
Params
key [required] your API Key
agency [required] transit agency id
stop [required] stop id
Returns
array containing stop times, with each item containing the following:
route_short_name route short name (ex: 500)
route_long_name route long name (ex: BELLEVUE - WEST VIEW OAKLAND-DOWNTOWN)
arrival_time arrival time at the stop
departure_time departure time from the stop
trip_id id of the trip that includes this stop time
type 'scheduled' or 'realtime' (when available)

rs.shape.getListByTrip

Get the longitude and latitude pairs for a specific trip.

http://api.routeshout.com/v1/rs.shape.getListByTrip?key=[api-key]&agency=[agency-id]&trip=[trip-id]

{
	"status":"ok",
	"response":[
		{"lon":-92.3185,"sequence":0,"lat":38.9525},
		{"lon":-92.3192,"sequence":1,"lat":38.9525},
		{"lon":-92.3201,"sequence":2,"lat":38.9525},
		{"lon":-92.3211,"sequence":3,"lat":38.9525},
		{"lon":-92.3226,"sequence":4,"lat":38.9525},
		{"lon":-92.3238,"sequence":5,"lat":38.9525},
		{"lon":-92.3265,"sequence":6,"lat":38.9526},
		{"lon":-92.3282,"sequence":7,"lat":38.9526},
		{"lon":-92.3308,"sequence":8,"lat":38.9527},
		{"lon":-92.3308,"sequence":9,"lat":38.9516},
		...
	],
	"meta": {
		"total":55
	}
}
URL http://api.routeshout.com/v1/rs.shape.getListByTrip
Params
key [required] your API Key
agency [required] transit agency id
trip [required] trip id
limit limit # of results
offset offset the result-set (for pagination)
Returns
an array of points, with each item containing the following:
lat the decimal latitude of the shape point
lon the decimal longitude of the shape point