REST API - Feed versions

Feed versions represent a specific GTFS file that was published at a particular point in time, and are generally accessed and referenced using the SHA1 checksum of the GTFS archive.

Feed versions contain a number of elements are derived from the source data in addition to the GTFS entities, including service levels over the duration of the feed, summaries of included CSV files, a convex hull geometry that contains all stops, etc.

New feed versions

The static GTFS URL for each feed is checked approximately once per hour, and a new feed version is created any time new data is observed. New feed versions are given the SHA1 checksum value of the entire GTFS Zip archive.

Data is considered new if the total checksum of the individual GTFS CSV files, processed in alphabetical order, has not been observed previously. Checking for uniqueness in individual file content avoids the common situation where timestamps or other non-GTFS files inside the archive change but the GTFS CSV data itself has not been updated.

Active feed version

Each feed has at most one active feed version, selected as the best feed version for the current day. In most cases it will be the most recently fetched feed version, unless that feed version only contains service for dates in the future. Requests to other endpoints, such as map tiles, routes, stops, etc., will use data from this feed version unless another version is explicitly specified using the feed_version_sha1 parameter.

Request overview

The feed versions API provides a number of searching and filtering parameters; results are based on this GraphQL query.


Request parameters

GET /api/v2/rest/feed_versions Feed Versions — Search for feed versions

GET /api/v2/rest/feeds_versions.{format} Request feed versions in specified format

GET /api/v2/rest/feeds_versions/{feed_version_key} Request a feed version by ID or SHA1

GET /api/v2/rest/feeds_versions/{feed_version_key}.{format} Request a feed version by ID or SHA1 in format

GET /api/v2/rest/feeds/{feed_key}/feed_versions Request feed versions by feed ID or OnestopID

Parameter Type Description Example
id integer
0 ... unlimited
Search for a specific internal ID
feed_version_key string

Equivalent to id (if an integer) or sha1 (if string)
after integer

Return records past this record ID
limit integer
0 ... 100
Maximum number of records to return limit=1
format enum
jsongeojsonpng
Response format format=geojson
sha1 string

Feed version SHA1 sha1=e535eb2b3...
feed_onestop_id string

Feed OnestopID feed_onestop_id=f-9q9-caltrain

Response format

Array of objects
Description: Feed version record
id
(int64)
Unique integer ID

Example:123

sha1
(string)
SHA1 hash of the zip file

Example:ab5bdc8b6cedd06792d42186a9b542504c5eef9a

fetched_at
(datetime)
Time when the file was fetched from the url

Example:2021-07-09T05:11:00Z

url
(datetime)
URL used to fetch the file

Example:2020-01-01T02:03:04.569789Z

earliest_calendar_date
(date)
The earliest date with scheduled service

Example:2020-01-01

latest_calendar_date
(date)
The latest date with scheduled service

Example:2020-12-31

geometry
(object)
Geometry in GeoJSON format
type
(string)
GeoJSON geometry type

Example:LineString

coordinates
(number array)
An array of GeoJSON coordinates

Example:[ [ -122.496, 37.778 ], [ -122.425, 37.786 ] ]

files
(object array)
Metadata for each text file present in the main directory of the zip archive
name
(string)
File name

Example:stops.txt

sha1
(string)
SHA1 of this file

Example:cfd72af293bf9f6939be20ad6890cb4c20f322b1

header
(string)
Header row, as a comma-separated string. This value may be filtered and cleaned up from the source file

Example:trip_id,stop_id,arrival_time,departure_time,stop_sequence

rows
(integer)
Number of rows, not including header
csv_like
(boolean)
True if the file appears to be a valid CSV file
size
(int64)
File size, in bytes
feed_version_gtfs_import
(object)
Status report of feed version importing and processing
in_progress
(boolean)
True if the feed is currently being imported
success
(boolean)
True if the feed has been successfully imported
exception_log
(string)
An error message returned from a failed feed import. An empty string if no error.

Example:no entities in required file routes.txt

warning_count
(object)
The number of warnings generated per file, if any
skip_entity_error_count
(object)
The number of entities skipped due to entity errors per file, if any
skip_entity_filter_count
(object)
The number of entities skipped by a filter per file, if any
skip_entity_marked_count
(object)
The number of entities skipped by a marker per file, if any
interpolated_stop_time_count
(integer)
The number of stop_time records where an interpolated arrival or departure time was set during import
feed
(object)
A subset of fields for the feed associated with this feed version

Downloading source GTFS

GET /api/v2/rest/feed_versions/{feed_version_key}/download Download this feed version

Description: Download this feed version GTFS zip for this feed, if allowed by the source feed's license