How to select an entity using Alert

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_entity should only have the agency_id field populated
• active_period should 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_entity should only have the route_id field populated
• active_period should 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_entity should only have both the route_id and direction_id field populated
• active_period should 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_entity should only have the route_id field populated
• active_period should 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_entity should only have the stop_id field populated
• active_period should 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.