Contents
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_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 | Feed version lookup key; can be an integer ID or a SHA1 value | |
| feed_key | string | Feed lookup key; can be an integer ID or Onestop ID | |
| after | integer | Return records past this record ID | |
| limit | integer 0 ... 100 | Maximum number of records to return | limit=1 |
| format | enum | 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
(integer)
(integer)
Unique integer ID
sha1
(string)
(string)
SHA1 hash of the zip file
Exampleab5bdc8b6cedd06792d42186a9b542504c5eef9a
fetched_at
(datetime)
(datetime)
Time when the file was fetched from the url
Example2021-07-09T05:11:00Z
url
(datetime)
(datetime)
URL used to fetch the file
Example2020-01-01T02:03:04.569789Z
earliest_calendar_date
(date)
(date)
The earliest date with scheduled service
Example2020-01-01
latest_calendar_date
(date)
(date)
The latest date with scheduled service
Example2020-12-31
feed
(object)
(object)
A subset of fields for the feed associated with this feed version
files
(object array)
(object array)
Metadata for each text file present in the main directory of the zip archive
name
(string)
(string)
File name
Examplestops.txt
sha1
(string)
(string)
SHA1 of this file
Examplecfd72af293bf9f6939be20ad6890cb4c20f322b1
header
(string)
(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)
(integer)
Number of rows, not including header
csv_like
(boolean)
(boolean)
True if the file appears to be a valid CSV file
size
(int64)
(int64)
File size, in bytes
feed_infos
(object array)
(object array)
Data from the feed version 'feed_info.txt' file
id
(int64)
(int64)
feed_publisher_name
(string)
(string)
GTFS feed_publisher_name
feed_publisher_url
(string)
(string)
GTFS feed_publisher_url
feed_contact_email
(string)
(string)
GTFS feed_contact_email
feed_contact_url
(string)
(string)
GTFS feed_contact_url
feed_lang
(string)
(string)
GTFS feed_lang
default_lang
(string)
(string)
GTFS default_lang
feed_start_date
(string)
(string)
GTFS feed_start_date
feed_end_date
(string)
(string)
GTFS feed_end_date
feed_version
(string)
(string)
GTFS feed_version: a string optionally provided in feed_info.txt. Not necessarily a Transitland feed version entity.
feed_version_gtfs_import
(object)
(object)
Status report of feed version importing and processing
in_progress
(boolean)
(boolean)
True if the feed is currently being imported
success
(boolean)
(boolean)
True if the feed has been successfully imported
exception_log
(string)
(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)
(object)
The number of warnings generated per file, if any
skip_entity_error_count
(object)
(object)
The number of entities skipped due to entity errors per file, if any
skip_entity_filter_count
(object)
(object)
The number of entities skipped by a filter per file, if any
skip_entity_marked_count
(object)
(object)
The number of entities skipped by a marker per file, if any
interpolated_stop_time_count
(integer)
(integer)
The number of stop_time records where an interpolated arrival or departure time was set during import
geometry
(object)
(object)
Geometry in GeoJSON format
type
(string)
(string)
GeoJSON geometry type
ExampleLineString
coordinates
(number array)
(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}/download — Download 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.