Skip to content

Public API resources

Public API

The Transiter public API is based around hierarchal resources, like many REST APIs. This is the resource hierarchy:

System
|- Agency
|- Alert
|- Feed
|   |- Feed update
|- Route
|   |- Trip
|       |- Vehicle with no ID
|- Stop
|- Transfer
|- Vehicle with ID

For each resource there is a proto message type, a list endpoint, and a get endpoints. For stops, the message is Stop, the list endpoint is [ListStops], and the get endpoint is [GetStop].

The URLs in the HTTP API are determined by the hierarchy; thus:

  • List all systems has URL /systems,
  • Get system with ID <system_id> has URL /systems/<system_id>,
  • List all routes in the system has URL /systems/<system_id>/routes,
  • Get route has URL /systems/<system_id>/routes/<route_id>,

and so on.

Many resources refer to other resources across the hierarchy. For example, each route has an agency it is attached to. Each stop has a list of service maps, each of which contains a set of routes. In these situations the resource message contains a reference to the other resource. The Route message contains an agency reference, in the form of an Agency.Reference message. These reference messages contain at least enough information to uniquely identify the resource. However they also contain additional information that is considered generally useful; thus, the Stop.Reference message contains the stop's name. What counts as "considered generally" is obviously very subjective and open to change.

The following table summarizes all of the resources and their types. The right-most column describes the source_of the resource. The public API is a read-only API so all of the resources come from somewhere else.

Resource Reference type List endpoint Get endpoint Source
Agency Agency.Reference [GetAgency] [ListAgency] GTFS static
Alert System [Alert] [Alert.Reference] GTFS realtime
Feed System system config
Feed update Feed Transiter update process
Route System GTFS static
Trip Route GTFS realtime
Stop System GTFS static
System None system config
Transfer System GTFS static
Vehicle System or trip GTFS realtime

Agency

The Agency resource.

This resource corresponds to the agency type in the GTFS static specification. Most of the fields in the resource come directly from the agency.txt table. Transiter adds some additional related fields (alerts).

Field Type Description
id string ID of the agency. This is the agency_id column in agency.txt.
resource Resource Generic metadata about the agency resource.
system System.Reference System corresponding to this agency. This is the parent resource in Transiter's resource hierarchy.
name string Name of the agency. This is the agency_name column in agency.txt.
url string URL of the agency. This is the agency_url column in agency.txt.
timezone string Timezone of the agency. This is the agency_timezone column in agency.txt.
language string Language of the agency. This is the agency_lang column in agency.txt.
phone string Phone number of the agency. This is the agency_phone column in agency.txt.
fare_url string URL where tickets for the agency's services ban be bought. This is the agency_fare_url column in agency.txt.
email string Email address of the agency. This is the agency_email column in agency.txt.
routes Route.Reference
alerts Alert.Reference List of active alerts for the agency.

These are determined using the informed_entity field in the GTFS realtime alerts message.

Agency.Reference

Reference is the reference type for the agency resource.

Field Type Description
id string
resource Resource
system System.Reference
name string

Alert

The Alert resource.

This resource corresponds to the alert type in the GTFS realtime specification.

TODO; alphabetize the messages

Field Type Description
id string ID of the alert. This corresponds to the ID field in the feed entity message corresponding to the alert.
resource Resource Generic metadata about the alert resource.
system System.Reference System corresponding to this alert. This is the parent resource in Transiter's resource hierarchy.
cause Alert.Cause Cause of the alert. This corresponds to the cause field in the realtime alert message.
effect Alert.Effect Effect of the alert. This corresponds to the effect field in the realtime alert message.
current_active_period Alert.ActivePeriod The current active period, if the alert is currently active. If the alert is not active this is empty.
all_active_periods Alert.ActivePeriod All active periods for this alert. Transiter guarantees that these active periods have no overlap.
header Alert.Text Header of the alert, in zero or more languages. This corresponds to the header_text field in the realtime alert message.
description Alert.Text Description of the alert, in zero or more languages. This corresponds to the description_text field in the realtime alert message.
url Alert.Text URL for additional information about the alert, in zero or more languages. This corresponds to the url field in the realtime alert message.

Alert.ActivePeriod

The active period message describes a period when an alert is active. It corresponds the the time range message in the GTFS realtime specification.

Field Type Description
starts_at int64 Unix timestamp of the start time of the active period. If not set, the alert be interpreted as being always active up to the end time.
ends_at int64 Unix timestamp of the end time of the active period. If not set, the alert be interpreted as being indefinitely active.

Alert.Cause

Cause is the same as the cause enum in the GTFS realtime specification, except UNKNOWN_CAUSE has value 0 instead of 1 to satisfy proto3 requirements.

Name Number Description
UNKNOWN_CAUSE 0
OTHER_CAUSE 2
TECHNICAL_PROBLEM 3
STRIKE 4
DEMONSTRATION 5
ACCIDENT 6
HOLIDAY 7
WEATHER 8
MAINTENANCE 9
CONSTRUCTION 10
POLICE_ACTIVITY 11
MEDICAL_EMERGENCY 12

Alert.Effect

Effect is the same as the effect enum in the GTFS realtime specification, except UNKNOWN_EFFECT has value 0 instead of 1 to satisfy proto3 requirements.

Name Number Description
UNKNOWN_EFFECT 0
NO_SERVICE 1
REDUCED_SERVICE 2
SIGNIFICANT_DELAYS 3
DETOUR 4
ADDITIONAL_SERVICE 5
MODIFIED_SERVICE 6
OTHER_EFFECT 7
STOP_MOVED 9
NO_EFFECT 10
ACCESSIBILITY_ISSUE 11

Alert.Reference

Reference is the reference type for the agency resource.

Field Type Description
id string
resource Resource
system System.Reference
cause Alert.Cause
effect Alert.Effect

Alert.Text

The text message describes an alert header/description/URL in a specified language. It corresponds the the translation message in the GTFS realtime specification.

Field Type Description
text string Content of the text.
language string Language of this text.

ChildResources

Description of a collection of child resources for a resource. This message and fields using this message exist to support API discoverability.

Field Type Description
count int64 Number of child resources.
href string URL of the endpoint to list child resources.

Feed

The feed resource.

Each feed is defined in the system configuration file. Feeds are included in the public API because there are non-admin use-cases for this resource. For example, an app might publish the staleness of realtime data by checking for the last succesful feed update.

More detailed information on a feed -- its full configuration, and the current status of its periodic updates -- can be retrieved through the admin API.

Field Type Description
id string ID of the feed, as specified in the system configuration file.
resource Resource Generic metadata about the feed resource.
system System.Reference System corresponding to this feed. This is the parent resource in Transiter's resource hierarchy.
updates ChildResources Updates for this feed.

Feed.Reference

Reference is the reference type for the feed resource.

Field Type Description
id string
resource Resource
system System.Reference

FeedUpdate

The feed update resource.

Each feed update event -- triggered manually though the admin API, or automatically by the scheduler -- generates a feed update resource. This resource is updated as the feed update progresses. A background task in Transiter periodically garbage collects old updates.

Field Type Description
id string ID of the feed update. This is the primary key of the associated Postgres database row so it's actually globally unique.
resource Resource Generic metadata about the feed update resource.
feed Feed.Reference Feed corresponding to this update. This is the parent resource in Transiter's resource hierarchy.
started_at int64 Unix timestamp of when the update started.
finished bool Whether the update has finished. If false, the update is still in progress.
finished_at int64 Unix timestamp of when the update finished. Only populated if the update is finished.
result FeedUpdate.Result Result of the update. Only populated if the update is finished.
content_length int32 Number of bytes in the downloaded feed data. Only populated if the update succesfully downloaded the data.
content_hash string Hash of the downloaded feed data. This is used to skip updates if the feed data hasn't changed. Only populated if the update succesfully downloaded the data.
error_message string Error message of the update. Only populated if the update finished in an error

FeedUpdate.Result

Name Number Description
UPDATED 0 Finished succesfully.
NOT_NEEDED 1 The update was skipped because the downloaded data was identical to the data for the last succesful update.
DOWNLOAD_ERROR 2 Failed to download feed data.
EMPTY_FEED 3 Feed data was empty.
INVALID_FEED_CONFIG 4 The feed configuration is invalid. This typically indicates a bug in Transiter because
the feed configuration is validated when the system is being installed.
INVALID_PARSER 5 The parser specified in the feed configuration is invalid.
PARSE_ERROR 6 Failed to parse the feed data.
This means the feed data was corrupted or otherwise invalid.
UPDATE_ERROR 7 Failed to update the database using the new feed data.
This typically indicates a bug in Transiter or a transient error connecting to the database.
INTERNAL_ERROR 8 An internal unspecified error occured.

Resource

The resource message contains generic metadata that applies to all resources.

Field Type Description
path string
href string

Route

The Route resource.

This resource corresponds to the route type in the GTFS static specification. Most of the fields in the resource come directly from the routes.txt table. Transiter adds some additional related fields (agency, alerts) and computed fields (estimated headway, service maps).

Field Type Description
id string ID of the route. This is the route_id column in routes.txt.
resource Resource Generic metadata about the route resource.
system System.Reference System corresponding to this route. This is the parent resource in Transiter's resource hierarchy.
short_name string Short name of the route. This is the route_short_name column in routes.txt.
long_name string Long name of the route. This is the route_long_name column in routes.txt.
color string Color of the route. This is the route_color column in routes.txt.
text_color string Text color of the route. This is the route_text_color column in routes.txt.
description string Description of the route. This is the route_desc column in routes.txt.
url string URL of a web page about the route. This is the route_url column in routes.txt.
sort_order int32 Sort order of the route. This is the route_sort_order column in routes.txt.
continuous_pickup Route.ContinuousPolicy Continuous pickup policy. This is the continuous_pickup column in routes.txt.
continuous_drop_off Route.ContinuousPolicy Continuous dropoff policy. This is the continuous_dropoff column in routes.txt.
type Route.Type Type of the route. This is the route_type column in routes.txt.
agency Agency.Reference Agency this route is associated to.

This is determined using the agency_id column in routes.txt.
alerts Alert.Reference Active alerts for this route.

These are determined using the informed_entity field in the GTFS realtime alerts message.
estimated_headway int32 An estimate of the interval of time between consecutive realtime trips, in seconds.

If there is insufficient data to compute an estimate, the field will be empty.

The estimate is computed as follows. For each stop that has realtime trips for the route, the list of arrival times for those trips is examined. The difference between consecutive arrival times is calculated. If there are N trips, there will be N-1 such arrival time diffs. The estimated headway is the average of these diffs across all stops.
service_maps Route.ServiceMap List of service maps for this route.

Route.ContinuousPolicy

Enum describing possible policies for continuous pickup or drop-off.

Name Number Description
ALLOWED 0 Continuous pickup or drop-off allowed.
NOT_ALLOWED 1 Continuous pickup or drop-off not allowed.
PHONE_AGENCY 2 Must phone the agency to arrange continuous pickup or drop-off.
COORDINATE_WITH_DRIVER 3 Must coordinate with driver to arrange continuous pickup or drop-off.

Route.Reference

Reference is the reference type for the route resource.

Field Type Description
id string
resource Resource
system System.Reference
color string

Route.ServiceMap

Message describing the service maps view in routes.

See the service maps documentation for more information on this message and the associated field.

Field Type Description
config_id string Config ID of the service map, as specified in the system configuration file.
stops Stop.Reference Ordered list of stop at which this route calls.

This list may be empty, in which case the route has no service in the service map.

Route.Type

Enum describing possible route types. This corresponds to possible values of the route_type column in routes.txt.

Name Number Description
LIGHT_RAIL 0
SUBWAY 1
RAIL 2
BUS 3
FERRY 4
CABLE_TRAM 5
AERIAL_LIFT 6
FUNICULAR 7
TROLLEY_BUS 11
MONORAIL 12
UNKNOWN 100

Stop

The Stop resource.

This resource corresponds to the stop type in the GTFS static specification. Most of the static fields in the resource come directly from the stops.txt table. Transiter adds some additional related fields (transfers, alerts, stop times) and computed fields (service maps).

Field Type Description
id string ID of the stop. This is the stop_id column in stops.txt.
resource Resource Generic metadata about the stop resource.
system System.Reference System corresponding to this stop. This is the parent resource in Transiter's resource hierarchy.
code string Code of the stop. This is the stop_code column in stops.txt.
name string Name of the stop. This is the stop_name column in stops.txt.
description string Description of the stop. This is the stop_desc column in stops.txt.
zone_id string Zone ID of the stop. This is the zone_id column in stops.txt.
latitude double Latitude of the stop. This is the stop_lat column in stops.txt.
longitude double Longitude of the stop. This is the stop_lon column in stops.txt.
url string URL of a webpage about the stop. This is the stop_url column in stops.txt.
type Stop.Type Type of the stop. This is the platform_type column in stops.txt.
parent_stop Stop.Reference Parent stop. This is determined using the parent_station column in stops.txt.
child_stops Stop.Reference Child stops. This are determined using the parent_station column in stops.txt.
timezone string Timezone of the stop. This is the stop_timezone column in stops.txt.
wheelchair_boarding bool If there is wheelchair boarding for this stop. This is the wheelchair_boarding column in stops.txt.
platform_code string Platform code of the stop. This is the platform_code column in stops.txt.
service_maps Stop.ServiceMap List of service maps for this stop.
alerts Alert.Reference Active alerts for this stop.

These are determined using the informed_entity field in the GTFS realtime alerts message.
stop_times StopTime List of realtime stop times for this stop.

A stop time is an event at which a trip calls at a stop.
transfers Transfer Transfers out of this stop.

These are determined using the from_stop_id field in the GTFS static transfers.txt file.
headsign_rules Stop.HeadsignRule List of headsign rules for this stop.

Stop.HeadsignRule

Message describing a headsign rule.

Field Type Description
stop Stop.Reference Stop the rule is for.
priority int32 Priority of the rule (lower is higher priority).
track string NYCT track.
headsign string Headsign.

Stop.Reference

Reference is the reference type for the stop resource.

Field Type Description
id string
resource Resource
system System.Reference
name string

Stop.ServiceMap

Message describing the service maps view in stops.

See the service maps documentation for more information on this message and the associated field.

Field Type Description
config_id string Config ID of the service map, as specified in the system configuration file.
routes Route.Reference List of routes which call at this stop.

This list may be empty, in which case the stop has no service in the service map.

Stop.Type

Enum describing the possible stop types

Name Number Description
STOP 0
STATION 1
ENTRANCE_OR_EXIT 2
GENERIC_NODE 3
BOARDING_AREA 4

StopTime

Message describing a realtime stop time.

A stop time is an event in which a trip calls at a stop. This message corresponds to the GTFS realtime StopTimeUpdate message

Field Type Description
stop Stop.Reference The stop.
trip Trip.Reference The trip.
arrival StopTime.EstimatedTime Arrival time.
departure StopTime.EstimatedTime Departure time.
future bool If this stop time is in the future. This field is not based on the arrival or departure time. Instead, a stop time is considered in the future if it appeared in the most recent GTFS realtime feed for its trip. When this stop time disappears from the trip, Transiter marks it as past and freezes its data.
stop_sequence int32 Stop sequence.
headsign string Headsign.
track string Track, from the NYCT realtime extension.

StopTime.EstimatedTime

Message describing the arrival or departure time of a stop time. This corresponds to the GTFS realtime StopTimeEvent message.

Field Type Description
time int64
delay int32
uncertainty int32

System

The System resource.

Field Type Description
id string ID of the system as specified in the install request.
resource Resource Generic metadata about the system resource.
name string Name of the system as specified in the system configuration file.
status System.Status Status of the system.
agencies ChildResources
feeds ChildResources
routes ChildResources
stops ChildResources
transfers ChildResources

System.Reference

Reference is the reference type for the system resource.

Field Type Description
id string
resource Resource

System.Status

Enum describing the possible statuses of a system.

Name Number Description
UNKNOWN 0 Unknown status, included for protobuf reasons.
INSTALLING 1 The system is currently being installed through an asychronous install request.
ACTIVE 2 The system was successfully installed and is now active.
INSTALL_FAILED 3 The system was added through an asynchronous install request, but the install failed.
UPDATING 4 The system is currently being updated through an asynchronous update request.
UPDATE_FAILED 5 An asynchronous update of the system failed.
DELETING 6 The system is in the process of being deleted through an asynchronous delete request.

Transfer

Field Type Description
from_stop Stop.Reference TODO: id, system, resource Probably will use the pk of the DB row for the ID
to_stop Stop.Reference
type Transfer.Type
min_transfer_time int32
distance int32

Transfer.Type

Name Number Description
RECOMMENDED 0
TIMED 1
REQUIRES_TIME 2
NO_POSSIBLE 3

Trip

Field Type Description
id string
resource Resource Generic metadata about the trip resource.
route Route.Reference Route corresponding to this trip. This is the parent resource in Transiter's resource hierarchy. It is determined using the route_id field in the GTFS realtime feed.
started_at int64
vehicle Vehicle.Reference
direction_id bool
stop_times StopTime

Trip.Reference

Reference is the reference type for the trip resource.

Field Type Description
id string
resource Resource
route Route.Reference
destination Stop.Reference
vehicle Vehicle.Reference

Vehicle

No fields.

Vehicle.Reference

Reference is the reference type for the vehicle resource.

Field Type Description
id string

Other types