Arrivals web service V2
Base HTTP URL: http://developer.trimet.org/ws/v2/arrivals
Base HTTPS URL: https://developer.trimet.org/ws/v2/arrivals
The criteria for how many arrivals are returned is configurable via minutes and arrivals parameters.
More arrival statuses are included and reasons for status exceptions are provided when available.
Detours applicable for the routes served at each stop are included in results.
Streetcar results are included by default.
In order to reduce result size blockPosition elements are included only when requested.
Experimental attributes arrival[@inCongestion] and arrival[@loadPercentage].
Request parameters:
| Name | Value | Description | |
|---|---|---|---|
| locIDs | comma delimited list of location IDs (required) | The location IDs to report arrivals. These are also called stop_ids in GTFS or Stop IDs on trimet.org. Arrivals are reported for each unique route and direction that services each stop identified by their location ID. Up to 128 location IDs can be reported at once. | |
| appID | string (required) | Your appID received during registration. | |
| json | boolean (optional) "true" (default) or "false" | If false results will be returned in XML format rather than the default json format. | |
| callback | string (optional) | If present returns the json result in a jsonp callback function. Only used if json is set to true. | |
| showPosition | boolean (optional) "true" or "false" (default) | If true arrival elements will include blockPosition elements when available. | |
| minutes | integer (optional) default is 20 | Arrivals for each route and direction served at the stops in locIDs will be returned up to the first that is further than minutes away. Maximum is 60.
For example: If minutes is set to 20 (the default) results may include arrivals 10 minutes and 23 minutes away. If minutes where instead set to 40 results would include the first two arrivals at 10 and 23 minutes and an additional arrival 45 minutes away. | |
| arrivals | integer (optional) default is 2 | At least this many arrivals for each route and direction served at the stops in locIDs will be returned. After an arrival further than an hour away is included this criterion is terminated. This means that if there are arrivals after the hour mark only the first will be included.
For example: If arrivals is set to 2 (the default) results may include arrivals 10 minutes and 23 minutes away. If arrivals where instead set to 4 results would include the first two arrivals at 10 and 23 minutes and an additional arrival 45 and a scheduled arrival 65 minutes away. | |
| begin | date time (optional) | Seconds since epoch, or string in 'yyyy-MM-ddTHH:mm:ss' format. If present arrivals after this time will be included. If set to a value prior to the current time, the current time will be used instead. All arrivals will be returned between begin and end parameters. Any arrival that can be estimated (up to an hour away from the current time) will be included. Otherwise all arrivals will be scheduled. Currently does not apply to streetcar arrivals. | |
| end | date time (optional) | Seconds since epoch, or string in 'yyyy-MM-ddTHH:mm:ss' format. If present arrivals before this time will be included. Requires begin parameter. If end is omitted while begin is present end will default to one hour after begin. Maximum time between begin and end is one day. |
Response fields:
note: all times values are in Unix time format, milliseconds since epoch.
| Name | Description | |
|---|---|---|
| resultSet | Root element of all results | |
| resultSet[@queryTime] | Time the result was generated. | |
| errorMessage | This element will occur if there was an error processing your request and contains a description of the problem. | |
| errorMessage[@content] | Contains a description of the error. content is in an attribute of [errorMessage] for json results and the text content of errorMessage for XML results. | |
| arrival | Contains arrival details. | |
| arrival[@id] | Id for arrival. Unique for service day. | |
| arrival[@blockID] | The block id of the arrival. A block is a unit of work for a day, a series of trips. | |
| arrival[@departed] | Indicates if the vehicle has begun the trip which will arrival at the requested stop. | |
| arrival[@detoured] | Boolean indicates the arrival may be effected by a detour along the route. | |
| arrival[@detour] | If arrival[@detoured] is true this attribute will be present. If the response is in JSON this attribute will contain an array of detour ids. For responses in XML the arrival element will contain simple detour elements with an id attribute. These ids can be used to match a detour[@id]. | |
| arrival[@dir] | The direction of the route for this arrival. | |
| arrival[@estimated] | The estimated time for this arrival. If this value is not present the arrival could not be estimated. | |
| arrival[@feet] | Number of feet the vehicle is away from the stop at the time the position was last reported. | |
| arrival[@fullsign] | The full text of the overhead sign of the vehicle when it arrives at the stop. | |
| arrival[@inCongestion] (Experimental) | Set to true if vehicle is reporting its not moving while in traffic. Bus only. | |
| arrival[@loadPercentage] (Experimental) | Vehicles (bus only) can report when load thresholds have been crossed. Currently there are three possible thresholds, 0%, 70% and 90%. These thresholds may change so values 0 to 100 may be possible. | |
| arrival[@locid] | The location id or stopID for the arrival. | |
| arrival[@route] | The route number of the arrival. | |
| arrival[@streetCar] and arrival[@nextBusFeed] | When these optional fields are present and set to true, the estimated time is provided by Portland Streetcar's API. When that API is not responding this system will instead show scheduled times for Streetcar and these flags will not be present. There are two fields to support legacy systems that require one or the other. |
|
| arrival[@scheduled] | The scheduled stop time (or interpolated scheduled stop time when the stop is not a time point) of the arrival. When streetCar is true "scheduled" times are not available and this field will instead hold the same value as estimated. | |
| arrival[@shortSign] | The short version of text from the overhead sign of the vehicle when it arrives at the stop. | |
| arrival[@dropOffOnly] | Boolean value. When true the vehicle is only dropping off passengers and is non-boarding. | |
| arrival[@status] | four possible values: estimated = arrival time was estimated with vehicle position information scheduled = scheduled arrival time is available only. No real time information available for estimation. Bus's radio may be down or vehicle may not be in service. Arrivals are not estimated when further than an hour away. delayed = status of service is uncertain. canceled = scheduled arrival was canceled for the day | |
| arrival[@reason] | This attribute is only present when arrival[@status] is neither estimated or scheduled. Its value is short description of why the arrival was canceled, delayed, or was set to dropOffOnly. Current possible values are: Bridge lift Bus Bridge Collision Construction Detour Fire Maintenance Mechanical issue Operating issue Passenger assistance Passenger crowding Police activity Traffic issue Train blockage Unknown - used when a reason has not yet been coded. |
|
| arrival[@tripID] | The trip id for the arrival. | |
| arrival[@newTrip] | Will be true when the trip is new and was not part of the published schedule. When true the value arrival[@tripID] will not be found in GTFS. | |
| arrival[@replacedService] | Optional attribute. When present and set to true this arrival was previously cancelled but has been filled by replacement service. | |
| arrival[@piece] | The piece of the block for this arrival. Blocks are separated into pieces of work through the day. | |
| arrival[@vehicleID] | The id of the vehicle to arrive. May be null if no information is available (when the arrival is scheduled or canceled). | |
| arrival[@showMilesAway] | Boolean value, when true it may be more useful to display how far away the vehicle is from the stop than to only show the estimated arrival time. For example, in snow and ice conditions. | |
| arrival[@routeColor] | Route color designation that matches public facing material. Left empty (xml) or null (json) when unspecified. Provided as a six character Hex string. | |
| trackingError | Optional child element of arrival elements is present when the most recent data recevied from our CAD (Computer Aided Dispatch) indicated it was unable to match the vehicle's service navigation. | |
| trackingError[@timestamp] | The timestamp of the last tracking error for the vehicle. | |
| trackingError[@offRoute] | Optional flag indicates if recent tracking errors indicated the vehicle had gone off route. | |
| trackingError[@desc] | Placeholder for tracking error descriptions. Currently only null. | |
| blockPosition | This child element of arrival elements are only shown if showPosition request parameter is set to true and position information is available for the vehicle serving the arrival. This element contains the last position of the vehicle along its block. Includes path information from this position to the stop requested. | |
| blockPosition[@id] | The block id of the arrival. A block is a unit of work for a day, a series of trips. | |
| blockPosition[@at] | The time this position was reported. | |
| blockPosition[@vehicleID] | The id of the vehicle to arrive. | |
| blockPosition[@feet] | Number of feet the vehicle is away from the stop at the time the position was reported. | |
| blockPosition[@heading] | The heading of the vehicle at the time of the position was reported, if available. May be null. | |
| blockPosition[@lat] | The latitude of the vehicle at the time the position was reported. | |
| blockPosition[@lng] | The longitude of the vehicle at the time the position was reported. | |
| blockPosition[@routeNumber] | Route number the vehicle is servicing. | |
| blockPosition[@direction] | Direction of the route the vehicle is servicing. | |
| blockPosition[@tripID] | TripID the vehicle is servicing. Will match published GTFS schedule if blockPosition[@newTrip] is false. | |
| blockPosition[@newTrip] | Will be true when the trip the block is serving is new and was not part of the published schedule. When true the value blockPosition[@tripID] will not be found in GTFS. | |
| blockPosition[@signMessage] | Vehicle's over head sign text message. | |
| blockPosition[@signMessageLong] | Vehicle's full over head sign text message. | |
| blockPosition[@nextLocID] | Location ID (or stopID) of the next stop this vehicle is scheduled to serve. | |
| blockPosition[@nextStopSeq] | Stop sequence for the next stop this vehicle is scheduled to serve. Some trips serve the same stop twice. | |
| blockPosition[@lastLocID] | Location ID (or stopID) of the previous stop this vehicle was scheduled to serve. | |
| blockPosition[@lastStopSeq] | Stop sequence for the next stop this vehicle is scheduled to serve. Some trips serve the same stop twice. | |
| trip | This child of the blockPosition will occur for every trip the vehicle must traverse to arrive at the stop requested. There may be more than one if the vehicle is on a different trip than the arrival. | |
| trip[@desc] | A description for the route's direction on this trip. | |
| trip[@destDist] | The number of feet along this trip the vehicle must traverse to arrival at the stop requested. If the vehicle must traverse the entire trip this number will always be the entire length of the trip. | |
| trip[@dir] | The direction of the route of this trip. | |
| trip[@pattern] | The pattern number for the trip. | |
| trip[@progress] | The number of feet the vehicle has traversed along this trip's pattern. | |
| trip[@route] | The route number for this trip. | |
| trip[@id] | The tripID of this trip. | |
| trip[@newTrip] | Will be true when the trip is new and was not part of the published schedule. When true the value trip[@id] will not be found in GTFS. | |
| detour | Contains information about a detour that may apply to one or more routes at the time the query was made. Note that this element is the same as alert element found in the Alerts V2 web service. The element name detour is used here to maintain compatibility with existing applications. |
|
| detour[@id] | A unique identifier of the detour. | |
| detour[@begin] | Time the detour begins. This will always be a time prior to the time the query was made. This field is used internally and may be of little use outside of TriMet. | |
| detour[@desc] | A plain text description of the detour. | |
| detour[@end] | The time the detour will become invalid. Note that this will always be a time after the time the query was made. Some end times will be very far in the future and will be removed once the detour is no longer in effect. This field is used internally and may be of little use outside of TriMet. | |
| detour[@header_text] | Nullable field contains short text description of alert/detour suitable for a header field. | |
| detour[@info_link_url] | Contains a url where more information can be found about the detour. Will be null if not available. | |
| detour[@system_wide_flag] | Boolean value indicates if the message is applicable for the TriMet system in general. | |
| route | Contains information about a route.
Can appear as a child of detour element where it describes a route the detour is applicable to. When in a detour element it can have an extra attribute, route[@no_service_flag]. Can appear as a child of the reportingStatus element where it describes a route that is reporting arrivals in a modified way. When in a reportingStatus element it can have an extra attribute, route[@status]. |
|
| route[@id] | This route's unique identifier (an integer). | |
| route[@desc] | The description of the route number. | |
| route[@route] | The route's number (an integer). Will be the same as route[@id]. | |
| route[@type] | The type of the route, either 'B' for bus, or 'R' for fixed guidway (either rail or aerial tram). | |
| route[@routeSubType] | The subtype of the route, provides a little more detail than route[@type]. Current possible values are: Light Rail, Aerial Tram, BRT, Bus, Commuter Rail, Shuttle, Streetcar |
|
| route[@no_service_flag] | Boolean value indicates if service is canceled for this route. | |
| route[@detour] | Optional attribute indicates if this route has a detour in effect. This field is only present in top level route elements and is omitted when embedded in a detour element. | |
| route[@routeColor] | Route color designation that matches public facing material. Left empty (xml) or null (json) when unspecified. Provided as a six character Hex string. | |
| route[@frequentService] | Boolean value indicates if the route provides frequent service. | |
| route[@routeSortOrder] | Orders the routes in a consistent manner for presentation to customers. Routes with smaller route_sort_order values should be displayed first. | |
| location | Contains information about a location, usually a stop.
Can appear as a child of the resultSet where it describes the stops requested. Can appear as a child of detour elements where it describes a stop the detour is applicable to. When in a detour element it can have an extra attribute, location[@no_service_flag]. Can appear as a child of the reportingStatus element where it describes the stop that is reporting arrivals in modified way. When in a reportingStatus element it can have an extra attribute, location[@status]. |
|
| location[@desc] | The public location description of the stop. | |
| location[@dir] | The direction of traffic at the stop. | |
| location[@lat] | The latitude of the stop. | |
| location[@lng] | The longitude of the stop. | |
| location[@id] | Unique id for location. Location ID or stopID of the stop. | |
| location[@passengerCode] | Passenger access code for the stop. 'E' = Either boarding or alighting 'A' = Alighting only 'B' = Boarding only 'N' = Neither boarding nor alighting |
|
| location[@no_service_flag] | Boolean value indicates if service is canceled for this location. This attribute is only present when the location is a child of a detour element. | |
| reportingStatus | This optional element occurs to indicate arrivals are being reported in a unusual way or not at all. It can have two children array elements location and route. | |
| location[@status] and route[@status] | String attribute is present in location and route elements only when a child of the reportingStatus element. Indicates how arrivals are being reporting for the location or route. Typically these are set during inclement weather conditions.
possible values: reportEstimatesOnly = Arrivals are only being reported if they can be estimated within the next hour. canceled = Service is canceled, no arrivals will be reported. reportSchedule = Only schedule times are being reported. No estimates are available. notReported = No arrivals are being reported, scheduled or estimated. This might occur when conditions such as snow and ice cause vehicles along the route to travel off their trip patterns. In such cases predictions are highly inaccurate or impossible. |