Alerts can be tied to different entities on a feed and be simultaneously applied to a combination of stops, stations, agencies, routes, and more.
This article will guide you through on common combinations in which an alert can be applied.
informed_entity usage
When multiple informed_entity are specified for a single alert, the alert will be applied on entities that fulfill any of the specified values.
In the example below, there are two informed_entity each specifying a different route. This applies the alert on all trips that belong to both routes and all stops that were visited by trips from both routes.
id: "2"
alert {
informed_entity {
route_id: "1"
}
informed_entity {
route_id: "2"
}
...
}
When multiple fields are populated for the same informed_entity, it’s only applied on entities that fulfill all populated values.
In the example below, the informed_entity specifies both a route_id and stop_id. This only applies the alert for segments of trips that belong to the route at this particular stop. It won’t show if a trip from the specified route doesn’t visit the specified stop during the transit journey and vice versa for any trip visiting the specified stop that doesn’t belong to the specified route.
id: "2"
alert {
informed_entity {
route_id: "1"
stop_id: "2"
}
...
}
active_period usage
The trip field in informed_entity lets you select a particular trip date and time. The other fields let you select entities like affected stops, but don’t provide enough information to indicate when the alerts should be applied.
The active_period must be used in combination with informed_entity to define the time period that the alert will be applied on the respective entities. However, this doesn’t define when the alert may be seen by the users.
For example, an alert is created with an active_period that affects all trips on December 25th and was created on December 20th.
Users can view the alert if they search ahead starting from December 20th for trips running on December 25th, but not on trips running outside the defined active_period.
If active_period isn’t provided, the alert will be applied on the informed_entity effective immediately upon creation and will be applied until it’s dropped from the feed.
To prevent undesired pre-knowledge of alert content, only create the alert when you want users to see them. E.g. Alert on upcoming new social distancing measures should only be published during official press releases.
Combinations of entity selectors
Agency wide
Applied on:
- All routes and trips belonging to the agency
- All bus stops in which trips belonging to the agency visit
Implementation details:
informed_entityshould only have theagency_idfield populatedactive_periodshould define the time range in which this alert is in effect
Example scenario: Signalling fault on train tracks affecting all train services provided by the agency A from 10am-12pm UTC on December 20th.
id: "1"
alert {
informed_entity {
agency_id: "A"
}
active_period {
start: 1608458400
end: 1608465600
}
effect: MODIFIED_SERVICE
cause: OTHER_CAUSE
...
}Route
Applied on:
- All trips that belong to the specified route
- All bus stops with trips that belong to the route visit
Implementation details:
informed_entityshould only have theroute_idfield populatedactive_periodshould define the time range that the alert is in effect
Example scenario: A sightseeing route is canceled from December 10th-20th due to a medical emergency.
id: "1"
alert {
informed_entity {
route_id: "12"
}
active_period {
start: 1607558400
end: 1608508799
}
effect: NO_SERVICE
cause: MEDICAL_EMERGENCY
...
}Route in a particular direction
Applied on:
- All trips that belong to the specified route that have the specified
direction_id - All bus stops in with trips that belong to the route visit
Implementation details:
informed_entityshould only have both theroute_idanddirection_idfield populatedactive_periodshould define the time range that the alert is in effect
Example scenario: A sightseeing route is canceled from December 10th-20th due to a medical emergency.
id: "1"
alert {
informed_entity {
route_id: "12"
direction_id: 1
}
active_period {
start: 1607558400
end: 1608508799
}
effect: NO_SERVICE
cause: MEDICAL_EMERGENCY
...
}Mode of transport
Applied on:
- All trips having the specified route type
- All bus stops in where trips belong to the route visit
Implementation details:
informed_entityshould only have theroute_idfield populatedactive_periodshould define the time range that the alert is in effect
Example scenario: All ferry trips are cancelled on December 20th due to severe flooding.
id: "1"
alert {
informed_entity {
route_type: 4
}
active_period {
start: 1608422400
end: 1608508799
}
effect: NO_SERVICE
cause: WEATHER
...
}Stop
Applied on:
- All trips visiting this stop
- The stop itself
Implementation details:
informed_entityshould only have thestop_idfield populatedactive_periodshould define the time range that the alert is in effect
Example scenario: The stop is closed from December 10th-20th due to construction.
id: "1"
alert {
informed_entity {
stop_id: "4"
}
active_period {
start: 1607558400
end: 1608508799
}
effect: NO_SERVICE
cause: CONSTRUCTION
...
}Trip
Applied on:
- All trips visiting this stop
- All stops visited by the trip
Implementation details:
- For more information, refer to the Selecting a Trip article.