REST API - Feed versions

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 specified format

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

ParameterTypeDescriptionExample
idinteger
0 ... unlimited
Search for a specific internal ID
feed_version_keystring

Feed version lookup key; can be an integer ID or a SHA1 value
feed_keystring

Feed lookup key; can be an integer ID or Onestop ID
afterinteger

Return records past this record ID
limitinteger
0 ... 100
Maximum number of records to returnlimit=1
format enum
jsongeojsonpng
Response formatformat=geojson
sha1string

Feed version SHA1sha1=e535eb2b3...
feed_onestop_idstring

Feed OnestopIDfeed_onestop_id=f-9q9-caltrain

Response format

Array of objects
Description Feed version record
id
(integer)
Unique integer ID
sha1
(string)
SHA1 hash of the zip file

Exampleab5bdc8b6cedd06792d42186a9b542504c5eef9a

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

Example2021-07-09T05:11:00Z

url
(datetime)
URL used to fetch the file

Example2020-01-01T02:03:04.569789Z

earliest_calendar_date
(date)
The earliest date with scheduled service

Example2020-01-01

latest_calendar_date
(date)
The latest date with scheduled service

Example2020-12-31

feed
(object)
A subset of fields for the feed associated with this feed version
files
(object array)
Metadata for each text file present in the main directory of the zip archive
name
(string)
File name

Examplestops.txt

sha1
(string)
SHA1 of this file

Examplecfd72af293bf9f6939be20ad6890cb4c20f322b1

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

Exampletrip_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_infos
(object array)
Data from the feed version 'feed_info.txt' file
id
(int64)
feed_publisher_name
(string)
GTFS feed_publisher_name
feed_publisher_url
(string)
GTFS feed_publisher_url
feed_contact_email
(string)
GTFS feed_contact_email
feed_contact_url
(string)
GTFS feed_contact_url
feed_lang
(string)
GTFS feed_lang
default_lang
(string)
GTFS default_lang
feed_start_date
(string)
GTFS feed_start_date
feed_end_date
(string)
GTFS feed_end_date
feed_version
(string)
GTFS feed_version: a string optionally provided in feed_info.txt. Not necessarily a Transitland feed version entity.
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.

Exampleno 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
geometry
(object)
Geometry in GeoJSON format
type
(string)
GeoJSON geometry type

ExampleLineString

coordinates
(number array)
An array of coordinates; may be nested arrays if geometry is Polygon or MultiLineString

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


Downloading source GTFS

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

Description Download this feed version GTFS zip for this feed, if redistribution is allowd by the source feed's license. Available only using Transitland professional or enterprise plan API keys.