Api Documentation

Routes

The overview of defined API routes.

API endpoint for consuming train data updates.

The route returns all new train sightings and train sightings that were updated since the specified last-modified timestamp.

  • The train sightings are sorted by the ascending time of the last modification.

  • The response contains only a limited number of records. Further records can be fetched by querying the 'nextRequestLink' provided in the response. The data are complete, when the returned nextRequestLink is null.

  • The route should be used together with the /api/v3/trains/deleted_sightings route returning train sightings that were deleted since the provided timestamp.

The expected use-case of this route is to keep a local train database in sync with the Railstate data. The local database can be patched periodically (e.g. every 15 minutes) using the /api/v3/trains/full_sightings and /api/v3/trains/deleted_sightings endpoints. The time of the last synchronization is to be provided as the query parameter of the first request of the patch iteration (unless you want to start from an empty database). Then, the returned nextRequestLinks are to be followed, while applying all the retrieved train data updates. If the local database already contains a train sighting with the same 'sightingId', then its data should be overwritten by the newly retrieved ones (the latest version).

An example request to fetch all train data updates since the midnight Jan 1st, 2026 (UTC timezone):

/api/v3/trains/full_sightings?last_modification_time_from=2026-01-01T00:00:00.000Z

The API endpoint supports some limited options for filtering the train data (selecting sensor sites, or a time interval). However, for targeted searches it is recommended to use the /api/v3/trains/search endpoint, instead.


Query parameters

Name Type Required? Default value Description
last_modification_time_from Instant Default 1970-01-01T00:00:00Z Lower bound for the last modification time of the train sighting data.
regions List < RegionAtPartitionId > Optional A comma-separated list of queried region ids. If specified return only data for sensors inside the selected regions. If not specified, the data from all available sensor sites are returned. The region ids are specified in format "{region_id}@{partition_id}" (for example "CA@geo_countries").
sighting_id_secondary_cmp_criterion int Default -1 Secondary ordering criterion used if multiple sightings have the same last modification time. This field is expected to be used only in automatically generated links to get the next data block.
detection_time_to Instant Optional An upper bound for the train detection time.
detection_time_from Instant Optional A lower bound for the train detection time.
response_size int Default 200 The maximum number of train sightings returned in a single response. If the number of matching train sightings is greater than the specified response size, the response will contain a URL link to the API that can be used for fetching more data. Cannot be greater than 1000.
sensors List < SensorId > Optional A comma-separated list of queried sensor site ids. If not specified, return data from all sensors.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAINS_VIEWER

API usage counters

  • Search
  • Total

Fetch complete data of selected train sightings specified by the provided list of train sighting ids. The route returns the sightings in an arbitrary order. For invalid train sighting ids, there will be no corresponding sightings returned in the response.


Query parameters

Name Type Required? Default value Description
ids List < TrainSightingId > Optional A Comma-separated list of train sighting ids (integer identifiers of train sightings). At most 500 ids can be specified.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAINS_VIEWER

API usage counters

  • Search
  • Total

Fetch train sighting ids of the specified train trips (also known as train profiles). The route returns the sighting ids in an arbitrary order. For invalid train trip ids, there will be no corresponding sightings returned in the response.


Query parameters

Name Type Required? Default value Description
trip_ids List < TrainProfileId > Optional A Comma-separated list of train trip ids (integer identifiers of train trips). At most 500 ids can be specified.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAINS_VIEWER

API usage counters

  • Search
  • Total

Return the train sighting ids of the last known sightings of the currently active train trips in the rail network. For each active train return just the id of its last known sighting.

The .../api/v3/trains/train_sightings route can be used to fetch the full train consist data for the returned train sighting ids.

A train trip is considered to be active, if its last sighting is not older than 5 days, and if the majority of rail cars and locomotives of the train trip has not been seen in a more recent train trip so far. (For example, when the return trip of a unit train was detected, then the original train trip is no longer considered active).

It is possible to limit the geographical area of interest using the "sensors" and "regions" query parameters. If used, the API route returns data only about trains with their last known sighting at one of the selected sensors. The trains that have a later sighting at an unselected sensor are not included. (If both "sensors" and "regions" are specified simultaneously, the API will interpret it as a union of all the matching sensors).


Query parameters

Name Type Required? Default value Description
detection_time_from Instant Optional A lower bound for the train detection time.
regions List < RegionAtPartitionId > Optional A comma-separated list of queried region ids. If specified return only data for sensors inside the selected regions. If not specified, the data from all available sensor sites are returned. The region ids are specified in format "{region_id}@{partition_id}" (for example "CA@geo_countries").
sensors List < SensorId > Optional A comma-separated list of queried sensor site ids. If not specified, return data from all sensors.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAINS_VIEWER

API usage counters

  • Search
  • Total

UNDER DEVELOPMENT - THE INTERFACE CAN CHANGE

Fetch the selected attributes of train sightings matching the specified conditions. If the number of matching results is too large, the response will contain URL fetching the next block of data. The train sightings are ordered by the increasing detection time.

Check the data model documentation to see the mapping of attributes to the returned data elements.

An example of a request that fetches all manifest and petroleum unit train sightings in Alberta detected between 2026-06-20 12:00 AM and 2026-06-25 12:00 PM UTC that carried at least one hazardous material:

/api/v3/trains/search?detection_time_from=2026-06-20T00:00:00Z&detection_time_to=2026-06-25T12:00:00Z&train_type=manifest,petroleum%20unit&hazmat_un=any&region=CA%2FAB@geo_states&limit=100&attributes=train_sighting_id,detection,rail_car,car_hazmats

Query parameters

Name Type Required? Default value Description
attributes List < DataElement > Required A comma-separated list of data attributes that are to be returned. Each attribute corresponds to a group of properties in the API response data model. The documentation of the response model describes the mapping.
detection_time_to Instant Optional An upper bound for the train detection time.
detection_time_from Instant Optional A lower bound for the train detection time.
limit int Default 200 The requested number of records per single API response. The limits are not strictly obeyed. Usually, the response will contain slightly less data than requested. Additional restrictions may be applied depending on the type of the search request.
sightings_filter SearchMode Default "All sightings" The sightings filter (a.k.a. 'Results display' in the UI) allows for applying additional filters for the results. When 'All sightings' are used, all records matching the query are returned. The behavior of the 'Last sightings' option depends on the selected 'tracking mode'. For train-tracking, only data of the last matching train sighting per train trip are returned. In car-tracking, only the data of the last matching car sighting per unique equipment id are returned. The sightings filter is applied after the evaluation of the search conditions.
tracking_mode TrackingMode Default "Trains" The tracking mode controls the behavior of site routes and region routes conditions. When train-tracking is used, the route conditions are applied on whole train trips. The train must traverse the route under the same train trip id. In car-tracking, the conditions are applied on the routes of individual rail cars and locomotives. Only car routes traversed under 10 days are supported under car-tracking. The car tracking mode does not support searches for train sightings. The car tracking mode ignores rail cars and locomotives with unknown equipment ids. The tracking mode also modifies the behavior of the 'sightings_filter' (a.k.a. 'results display' in the UI). When 'Last sightings' option is used, the train-tracking results contain only the data of the last matching train sighting of each train trip. For car-tracking, the last matching car sighting of each unique equipment id is returned.
train_trip_status List < TrainTripStatus > Default [] A comma-separated list of train trip states to search for.
locomotive_count List < EncodedIntegerInterval > Default [] A comma-separated list of locomotive count ranges. The search will return only data of train sightings for which the locomotive count falls in one of the specified ranges.
car_count List < EncodedIntegerInterval > Default [] A comma-separated list of rail car count ranges. The search will return only data of train sightings for which the car count falls in one of the specified ranges. Locomotives are not counted. Intermodal stack cars are counted as whole units.
platform_count List < EncodedIntegerInterval > Default [] A comma-separated list of rail car platform count ranges. The search will return only data of train sightings for which the platform count falls in one of the specified ranges. Locomotives are not counted. For intermodal stack cars, the individual platforms are counted separately.
container_count List < EncodedIntegerInterval > Default [] A comma-separated list of shipping container count ranges. The search will return only data of train sightings for which the total count of detected containers fall in one of the specified ranges.
car_type List < CarType > Default [] A comma-separated list of car types. The search will return only rail cars of specified car types (or train sightings containing at least one such car in case of train searches).
direction List < CardinalDirection > Default [] A comma-separated list of directions. The search will return only data of train sightings travelling in one of the specified directions.
container_type List < ContainerType > Default [] A comma-separated list of container types. The search will return only containers of the specified types, or rail cars and train sightings carrying such containers.
hazard_class List < HazardClassCode > Default [] A comma-separated list of hazard class codes. The search will return only cars and container sightings with a hazmat placard falling in one of the specified hazard classes (or train sighting containing at least one such car or container in case of train searches).
hazmat_un List < HazmatUnNumber > Default [] A comma-separated list of hazmat un numbers. The search will return only train, car and container sightings with at least one of the specified placards.
load_status List < LoadStatus > Default [] A comma-separated list of rail car's load states. The search will return only rail car sightings with the specified load states (or train sightings with some such rail cars in case of train searches).
sensor List < SensorId > Default [] A comma-separated list of sensor site ids. The search will return only data of train sightings at the specified sensors. The sensor sites are translated to site route conditions. It means that OR logic is used when combining 'sensor' and 'site_route' conditions.
train_operator List < RailId > Default [] A comma-separated list of train operators to search for. The search will return only trains that are operated by the specified railways.
equipment_owner List < RailId > Default [] A comma-separated list of owners of rail cars and locomotives to search for. The search will return only rail cars and locomotives owned by the specified railways (or train sightings containing such cars or locomotives in case of train searches).
equipment_lessee List < RailId > Default [] A comma-separated list of lessees of rail cars and locomotives to search for. The search will return only rail cars and locomotives being leased to the specified railways (or train sightings containing such cars or locomotives in case of train searches).
rail_line_owner List < RailId > Default [] A comma-separated list of rail line owners to search for. The search will return only train sightings detected at sensors monitoring rail lines owned by the specified railways.
train_trip_id List < TrainProfileId > Default [] A comma-separated list of train trip ids to search for.
train_sighting_id List < TrainSightingId > Default [] A comma-separated list of train sighting ids to search for.
train_set_id List < TrainSetId > Default [] A comma-separated list of train set ids to search for.
train_type List < TrainType > Default [] A comma-separated list of train types. The search will return only data of train sightings of the specified train types.
car_id List < CarIdWildcard > Default [] A comma-separated list of car id wildcards. The search will return only car sightings with car id matching at least one of the specified wildcards (or train sightings having at least one matching car).
container_id List < ContainerIdWildcard > Default [] A comma-separated list of container id wildcards. The search will return only container sightings with container id matching at least one of the specified wildcards (or train and car sightings carrying at least one such container).
container_id_status List < ContainerIdStatus > Default [] A comma-separated list of container id states, allowing to search only for containers with complete or incomplete container ids. A container id is considered incomplete, if it was read only partially, or if the checksum-digit was read but the checksum failed.
site_route List < SiteRouteWildcard > Default [] A comma-separated list of site-route conditions. The search will return only sightings satisfying at least one of the specified conditions.
region_route List < RegionRouteWildcard > Default [] A comma-separated list of region-route conditions. The search will return only sightings satisfying at least one of the specified conditions. The region route values are case-sensitive.
equipment_type_code List < EquipmentTypeCodeWildcard > Default [] A comma-separated list of equipment type code wildcards. The search will return only cars with equipment type code matching at least one of the specified wildcards (or train sightings having such a car). Equipment type codes are assigned to the car sightings only if their equipment car ids are recognized. Cars with unknown car ids will never match.
emission_tier List < EPAEmissionsTier > Default [] A comma-separated list of EPA emissions tiers. The search will return only locomotives with one of the specified emission tiers (or trains having at least one such locomotive in case of train searches).
propelled_by List < LocomotivePropelledBy > Default [] A comma-separated list of locomotive propulsion types. The search will return only locomotives with one of the propulsion types. (or trains having at least one such locomotive in case of train searches).
equipment_list List < EquipmentListId > Default [] A comma-separated list of equipment list ids. The search will return only rail cars and locomotives belonging to at least one of the specified lists. For train searches, train sightings with at least one car in one of the specified lists are returned. The '*' character can be used to look for rolling stock in any of the defined equipment lists.
train_tag List < TrainTag > Default [] A comma-separated list of train tags. The search will return only data of trains assigned one of the specified tags. The train tags are case-sensitive. The '*' character can be used to look for all the tagged trains.
region List < RegionAtPartitionId > Default [] A comma-separated list of full region ids (including the region partition id). The search will return only sightings in one of the specified regions. The region ids are case-sensitive.
stenciled_shipping_spec List < ShippingSpecWildcard > Default [] A comma-separated list of stenciled shipping spec wildcards. The search will return only cars with shipping spec matching at least one of the specified wildcards (or train sightings having such a car). Stenciled shipping specs are assigned to the car sightings only if their equipment car ids are recognized. Cars with unknown car ids will never match.
train_warning List < TrainSightingWarningQuery > Default [] A comma-separated list of train sighting warnings. The search will return only data of train sightings with at least one of the specified warnings.
car_sighting_id List < CarSightingId > Default [] A comma-separated list of car sighting ids to search for.
container_sighting_id List < ContainerSightingId > Default [] A comma-separated list of container sighting ids to search for.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAINS_VIEWER

API usage counters

  • Search
  • Total

List train sightings deleted since the specified last deletion time.

The trains sightings can be deleted when multiple partial sightings are merged together, or if a train sighting was later evaluated as a false positive detection.

The deleted train sightings are sorted by ascending time of the deletion. The response contains only a limited number of records. Further records can be fetched by querying the 'nextRequestLink' provided in the response. The data are complete, when the returned nextRequestLink is null.

This route is expected to be used together with the /api/v3/trains/full_sightings endpoint to patch a local train database with the Railstate data.

An example request to fetch all train sightings deleted since the midnight Jan 1st, 2026 (UTC timezone):

/api/v3/trains/deleted_sightings?deletion_time=2026-01-01T00:00:00.000Z

Query parameters

Name Type Required? Default value Description
deletion_time Instant Default 1970-01-01T00:00:00Z Lower bound for the deletion time.
regions List < RegionAtPartitionId > Optional A comma-separated list of queried region ids. If specified return only data for sensors inside the selected regions. If not specified, the data from all available sensor sites are returned. The region ids are specified in format "{region_id}@{partition_id}" (for example "CA@geo_countries").
sighting_id_secondary_cmp_criterion int Default -1 Secondary ordering criterion used if multiple sightings have the same deletion time. This field is expected to be used only in automatically generated links to get the next data block.
detection_time_to Instant Optional An upper bound for the train detection time.
detection_time_from Instant Optional A lower bound for the train detection time.
response_size int Default 200 The maximum number of train sightings returned in a single response. If the number of matching train sightings is greater than the specified response size, the response will contain a URL link to the API that can be used for fetching more data. Cannot be greater than 1000.
sensors List < SensorId > Optional A comma-separated list of queried sensor site ids. If not specified, return data from all sensors.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAINS_VIEWER

API usage counters

  • Total

UNDER DEVELOPMENT - THE INTERFACE CAN CHANGE

Fetch the selected attributes of rail car sightings matching the specified conditions. If the number of matching results is too large, the response will contain URL fetching the next block of data. The car sightings are ordered by the increasing detection time.

Check the data model documentation to see the mapping of attributes to the returned data elements.

An example of a request that fetches all tank car sightings with UN1202 or UN1203 hazmat placards that crossed the border from the United States to Canada between 2026-06-20 12:00 AM and 2026-06-25 12:00 PM UTC. More precisely:

  • The query returns the first sightings of the tank cars in Canada that are immediately preceded by sightings of the same car id in the United States.

  • The hazmat placard must be detected at the Canadian sighting. The hazmat might be missing in the preceding sighting in US.

  • The car tracking mode is used. That means that the sightings in US and Canada might have different train trip ids.

  • The query will miss border crossings at places with low sensor coverage. The cars must be detected on both sides of the border. Consider defining a custom region partition with border sensors to include data from border crossings seen just by one sensor.

/api/v3/cars/search?tracking_mode=cars&detection_time_from=2026-06-20T00:00:00Z&detection_time_to=2026-06-25T12:00:00Z&car_type=tank%20car&hazmat_un=un1202,un1203&region_route=%2A%3CUS%3E%3CCA%23F%3E%2A@geo_countries~E&limit=500&attributes=train_sighting_id,detection,rail_car,car_hazmats

Query parameters

Name Type Required? Default value Description
attributes List < DataElement > Required A comma-separated list of data attributes that are to be returned. Each attribute corresponds to a group of properties in the API response data model. The documentation of the response model describes the mapping.
detection_time_to Instant Optional An upper bound for the train detection time.
detection_time_from Instant Optional A lower bound for the train detection time.
limit int Default 200 The requested number of records per single API response. The limits are not strictly obeyed. Usually, the response will contain slightly less data than requested. Additional restrictions may be applied depending on the type of the search request.
sightings_filter SearchMode Default "All sightings" The sightings filter (a.k.a. 'Results display' in the UI) allows for applying additional filters for the results. When 'All sightings' are used, all records matching the query are returned. The behavior of the 'Last sightings' option depends on the selected 'tracking mode'. For train-tracking, only data of the last matching train sighting per train trip are returned. In car-tracking, only the data of the last matching car sighting per unique equipment id are returned. The sightings filter is applied after the evaluation of the search conditions.
tracking_mode TrackingMode Default "Trains" The tracking mode controls the behavior of site routes and region routes conditions. When train-tracking is used, the route conditions are applied on whole train trips. The train must traverse the route under the same train trip id. In car-tracking, the conditions are applied on the routes of individual rail cars and locomotives. Only car routes traversed under 10 days are supported under car-tracking. The car tracking mode does not support searches for train sightings. The car tracking mode ignores rail cars and locomotives with unknown equipment ids. The tracking mode also modifies the behavior of the 'sightings_filter' (a.k.a. 'results display' in the UI). When 'Last sightings' option is used, the train-tracking results contain only the data of the last matching train sighting of each train trip. For car-tracking, the last matching car sighting of each unique equipment id is returned.
train_trip_status List < TrainTripStatus > Default [] A comma-separated list of train trip states to search for.
locomotive_count List < EncodedIntegerInterval > Default [] A comma-separated list of locomotive count ranges. The search will return only data of train sightings for which the locomotive count falls in one of the specified ranges.
car_count List < EncodedIntegerInterval > Default [] A comma-separated list of rail car count ranges. The search will return only data of train sightings for which the car count falls in one of the specified ranges. Locomotives are not counted. Intermodal stack cars are counted as whole units.
platform_count List < EncodedIntegerInterval > Default [] A comma-separated list of rail car platform count ranges. The search will return only data of train sightings for which the platform count falls in one of the specified ranges. Locomotives are not counted. For intermodal stack cars, the individual platforms are counted separately.
container_count List < EncodedIntegerInterval > Default [] A comma-separated list of shipping container count ranges. The search will return only data of train sightings for which the total count of detected containers fall in one of the specified ranges.
car_type List < CarType > Default [] A comma-separated list of car types. The search will return only rail cars of specified car types (or train sightings containing at least one such car in case of train searches).
direction List < CardinalDirection > Default [] A comma-separated list of directions. The search will return only data of train sightings travelling in one of the specified directions.
container_type List < ContainerType > Default [] A comma-separated list of container types. The search will return only containers of the specified types, or rail cars and train sightings carrying such containers.
hazard_class List < HazardClassCode > Default [] A comma-separated list of hazard class codes. The search will return only cars and container sightings with a hazmat placard falling in one of the specified hazard classes (or train sighting containing at least one such car or container in case of train searches).
hazmat_un List < HazmatUnNumber > Default [] A comma-separated list of hazmat un numbers. The search will return only train, car and container sightings with at least one of the specified placards.
load_status List < LoadStatus > Default [] A comma-separated list of rail car's load states. The search will return only rail car sightings with the specified load states (or train sightings with some such rail cars in case of train searches).
sensor List < SensorId > Default [] A comma-separated list of sensor site ids. The search will return only data of train sightings at the specified sensors. The sensor sites are translated to site route conditions. It means that OR logic is used when combining 'sensor' and 'site_route' conditions.
train_operator List < RailId > Default [] A comma-separated list of train operators to search for. The search will return only trains that are operated by the specified railways.
equipment_owner List < RailId > Default [] A comma-separated list of owners of rail cars and locomotives to search for. The search will return only rail cars and locomotives owned by the specified railways (or train sightings containing such cars or locomotives in case of train searches).
equipment_lessee List < RailId > Default [] A comma-separated list of lessees of rail cars and locomotives to search for. The search will return only rail cars and locomotives being leased to the specified railways (or train sightings containing such cars or locomotives in case of train searches).
rail_line_owner List < RailId > Default [] A comma-separated list of rail line owners to search for. The search will return only train sightings detected at sensors monitoring rail lines owned by the specified railways.
train_trip_id List < TrainProfileId > Default [] A comma-separated list of train trip ids to search for.
train_sighting_id List < TrainSightingId > Default [] A comma-separated list of train sighting ids to search for.
train_set_id List < TrainSetId > Default [] A comma-separated list of train set ids to search for.
train_type List < TrainType > Default [] A comma-separated list of train types. The search will return only data of train sightings of the specified train types.
car_id List < CarIdWildcard > Default [] A comma-separated list of car id wildcards. The search will return only car sightings with car id matching at least one of the specified wildcards (or train sightings having at least one matching car).
container_id List < ContainerIdWildcard > Default [] A comma-separated list of container id wildcards. The search will return only container sightings with container id matching at least one of the specified wildcards (or train and car sightings carrying at least one such container).
container_id_status List < ContainerIdStatus > Default [] A comma-separated list of container id states, allowing to search only for containers with complete or incomplete container ids. A container id is considered incomplete, if it was read only partially, or if the checksum-digit was read but the checksum failed.
site_route List < SiteRouteWildcard > Default [] A comma-separated list of site-route conditions. The search will return only sightings satisfying at least one of the specified conditions.
region_route List < RegionRouteWildcard > Default [] A comma-separated list of region-route conditions. The search will return only sightings satisfying at least one of the specified conditions. The region route values are case-sensitive.
equipment_type_code List < EquipmentTypeCodeWildcard > Default [] A comma-separated list of equipment type code wildcards. The search will return only cars with equipment type code matching at least one of the specified wildcards (or train sightings having such a car). Equipment type codes are assigned to the car sightings only if their equipment car ids are recognized. Cars with unknown car ids will never match.
emission_tier List < EPAEmissionsTier > Default [] A comma-separated list of EPA emissions tiers. The search will return only locomotives with one of the specified emission tiers (or trains having at least one such locomotive in case of train searches).
propelled_by List < LocomotivePropelledBy > Default [] A comma-separated list of locomotive propulsion types. The search will return only locomotives with one of the propulsion types. (or trains having at least one such locomotive in case of train searches).
equipment_list List < EquipmentListId > Default [] A comma-separated list of equipment list ids. The search will return only rail cars and locomotives belonging to at least one of the specified lists. For train searches, train sightings with at least one car in one of the specified lists are returned. The '*' character can be used to look for rolling stock in any of the defined equipment lists.
train_tag List < TrainTag > Default [] A comma-separated list of train tags. The search will return only data of trains assigned one of the specified tags. The train tags are case-sensitive. The '*' character can be used to look for all the tagged trains.
region List < RegionAtPartitionId > Default [] A comma-separated list of full region ids (including the region partition id). The search will return only sightings in one of the specified regions. The region ids are case-sensitive.
stenciled_shipping_spec List < ShippingSpecWildcard > Default [] A comma-separated list of stenciled shipping spec wildcards. The search will return only cars with shipping spec matching at least one of the specified wildcards (or train sightings having such a car). Stenciled shipping specs are assigned to the car sightings only if their equipment car ids are recognized. Cars with unknown car ids will never match.
train_warning List < TrainSightingWarningQuery > Default [] A comma-separated list of train sighting warnings. The search will return only data of train sightings with at least one of the specified warnings.
car_sighting_id List < CarSightingId > Default [] A comma-separated list of car sighting ids to search for.
container_sighting_id List < ContainerSightingId > Default [] A comma-separated list of container sighting ids to search for.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • TRAIN_CARS_VIEWER

API usage counters

  • Search
  • Total

UNDER DEVELOPMENT - THE INTERFACE CAN CHANGE

Fetch the selected attributes of shipping container sightings matching the specified conditions. If the number of matching results is too large, the response will contain URL fetching the next block of data. The container sightings are ordered by the increasing detection time.

Check the data model documentation to see the mapping of attributes to the returned data elements.

An example of a request that fetches container sightings detected by the 5 specified sensors between 2026-06-20 12:00 AM and 2026-06-25 12:00 PM UTC. The results are de-duplicated by the train trip id. For each train trip, only containers at its last sighting matching the query are returned.

/api/v3/containers/search?sightings_filter=last%20sightings&detection_time_from=2026-06-20T00:00:00Z&detection_time_to=2026-06-25T12:00:00Z&sensor=8,315,24,15,39&limit=500&attributes=train_sighting_id,detection,rail_car,container_params

Query parameters

Name Type Required? Default value Description
attributes List < DataElement > Required A comma-separated list of data attributes that are to be returned. Each attribute corresponds to a group of properties in the API response data model. The documentation of the response model describes the mapping.
detection_time_to Instant Optional An upper bound for the train detection time.
detection_time_from Instant Optional A lower bound for the train detection time.
limit int Default 200 The requested number of records per single API response. The limits are not strictly obeyed. Usually, the response will contain slightly less data than requested. Additional restrictions may be applied depending on the type of the search request.
sightings_filter SearchMode Default "All sightings" The sightings filter (a.k.a. 'Results display' in the UI) allows for applying additional filters for the results. When 'All sightings' are used, all records matching the query are returned. The behavior of the 'Last sightings' option depends on the selected 'tracking mode'. For train-tracking, only data of the last matching train sighting per train trip are returned. In car-tracking, only the data of the last matching car sighting per unique equipment id are returned. The sightings filter is applied after the evaluation of the search conditions.
tracking_mode TrackingMode Default "Trains" The tracking mode controls the behavior of site routes and region routes conditions. When train-tracking is used, the route conditions are applied on whole train trips. The train must traverse the route under the same train trip id. In car-tracking, the conditions are applied on the routes of individual rail cars and locomotives. Only car routes traversed under 10 days are supported under car-tracking. The car tracking mode does not support searches for train sightings. The car tracking mode ignores rail cars and locomotives with unknown equipment ids. The tracking mode also modifies the behavior of the 'sightings_filter' (a.k.a. 'results display' in the UI). When 'Last sightings' option is used, the train-tracking results contain only the data of the last matching train sighting of each train trip. For car-tracking, the last matching car sighting of each unique equipment id is returned.
train_trip_status List < TrainTripStatus > Default [] A comma-separated list of train trip states to search for.
locomotive_count List < EncodedIntegerInterval > Default [] A comma-separated list of locomotive count ranges. The search will return only data of train sightings for which the locomotive count falls in one of the specified ranges.
car_count List < EncodedIntegerInterval > Default [] A comma-separated list of rail car count ranges. The search will return only data of train sightings for which the car count falls in one of the specified ranges. Locomotives are not counted. Intermodal stack cars are counted as whole units.
platform_count List < EncodedIntegerInterval > Default [] A comma-separated list of rail car platform count ranges. The search will return only data of train sightings for which the platform count falls in one of the specified ranges. Locomotives are not counted. For intermodal stack cars, the individual platforms are counted separately.
container_count List < EncodedIntegerInterval > Default [] A comma-separated list of shipping container count ranges. The search will return only data of train sightings for which the total count of detected containers fall in one of the specified ranges.
car_type List < CarType > Default [] A comma-separated list of car types. The search will return only rail cars of specified car types (or train sightings containing at least one such car in case of train searches).
direction List < CardinalDirection > Default [] A comma-separated list of directions. The search will return only data of train sightings travelling in one of the specified directions.
container_type List < ContainerType > Default [] A comma-separated list of container types. The search will return only containers of the specified types, or rail cars and train sightings carrying such containers.
hazard_class List < HazardClassCode > Default [] A comma-separated list of hazard class codes. The search will return only cars and container sightings with a hazmat placard falling in one of the specified hazard classes (or train sighting containing at least one such car or container in case of train searches).
hazmat_un List < HazmatUnNumber > Default [] A comma-separated list of hazmat un numbers. The search will return only train, car and container sightings with at least one of the specified placards.
load_status List < LoadStatus > Default [] A comma-separated list of rail car's load states. The search will return only rail car sightings with the specified load states (or train sightings with some such rail cars in case of train searches).
sensor List < SensorId > Default [] A comma-separated list of sensor site ids. The search will return only data of train sightings at the specified sensors. The sensor sites are translated to site route conditions. It means that OR logic is used when combining 'sensor' and 'site_route' conditions.
train_operator List < RailId > Default [] A comma-separated list of train operators to search for. The search will return only trains that are operated by the specified railways.
equipment_owner List < RailId > Default [] A comma-separated list of owners of rail cars and locomotives to search for. The search will return only rail cars and locomotives owned by the specified railways (or train sightings containing such cars or locomotives in case of train searches).
equipment_lessee List < RailId > Default [] A comma-separated list of lessees of rail cars and locomotives to search for. The search will return only rail cars and locomotives being leased to the specified railways (or train sightings containing such cars or locomotives in case of train searches).
rail_line_owner List < RailId > Default [] A comma-separated list of rail line owners to search for. The search will return only train sightings detected at sensors monitoring rail lines owned by the specified railways.
train_trip_id List < TrainProfileId > Default [] A comma-separated list of train trip ids to search for.
train_sighting_id List < TrainSightingId > Default [] A comma-separated list of train sighting ids to search for.
train_set_id List < TrainSetId > Default [] A comma-separated list of train set ids to search for.
train_type List < TrainType > Default [] A comma-separated list of train types. The search will return only data of train sightings of the specified train types.
car_id List < CarIdWildcard > Default [] A comma-separated list of car id wildcards. The search will return only car sightings with car id matching at least one of the specified wildcards (or train sightings having at least one matching car).
container_id List < ContainerIdWildcard > Default [] A comma-separated list of container id wildcards. The search will return only container sightings with container id matching at least one of the specified wildcards (or train and car sightings carrying at least one such container).
container_id_status List < ContainerIdStatus > Default [] A comma-separated list of container id states, allowing to search only for containers with complete or incomplete container ids. A container id is considered incomplete, if it was read only partially, or if the checksum-digit was read but the checksum failed.
site_route List < SiteRouteWildcard > Default [] A comma-separated list of site-route conditions. The search will return only sightings satisfying at least one of the specified conditions.
region_route List < RegionRouteWildcard > Default [] A comma-separated list of region-route conditions. The search will return only sightings satisfying at least one of the specified conditions. The region route values are case-sensitive.
equipment_type_code List < EquipmentTypeCodeWildcard > Default [] A comma-separated list of equipment type code wildcards. The search will return only cars with equipment type code matching at least one of the specified wildcards (or train sightings having such a car). Equipment type codes are assigned to the car sightings only if their equipment car ids are recognized. Cars with unknown car ids will never match.
emission_tier List < EPAEmissionsTier > Default [] A comma-separated list of EPA emissions tiers. The search will return only locomotives with one of the specified emission tiers (or trains having at least one such locomotive in case of train searches).
propelled_by List < LocomotivePropelledBy > Default [] A comma-separated list of locomotive propulsion types. The search will return only locomotives with one of the propulsion types. (or trains having at least one such locomotive in case of train searches).
equipment_list List < EquipmentListId > Default [] A comma-separated list of equipment list ids. The search will return only rail cars and locomotives belonging to at least one of the specified lists. For train searches, train sightings with at least one car in one of the specified lists are returned. The '*' character can be used to look for rolling stock in any of the defined equipment lists.
train_tag List < TrainTag > Default [] A comma-separated list of train tags. The search will return only data of trains assigned one of the specified tags. The train tags are case-sensitive. The '*' character can be used to look for all the tagged trains.
region List < RegionAtPartitionId > Default [] A comma-separated list of full region ids (including the region partition id). The search will return only sightings in one of the specified regions. The region ids are case-sensitive.
stenciled_shipping_spec List < ShippingSpecWildcard > Default [] A comma-separated list of stenciled shipping spec wildcards. The search will return only cars with shipping spec matching at least one of the specified wildcards (or train sightings having such a car). Stenciled shipping specs are assigned to the car sightings only if their equipment car ids are recognized. Cars with unknown car ids will never match.
train_warning List < TrainSightingWarningQuery > Default [] A comma-separated list of train sighting warnings. The search will return only data of train sightings with at least one of the specified warnings.
car_sighting_id List < CarSightingId > Default [] A comma-separated list of car sighting ids to search for.
container_sighting_id List < ContainerSightingId > Default [] A comma-separated list of container sighting ids to search for.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT
  • CONTAINERS_VIEWER

API usage counters

  • Search
  • Total

Fetch data about the deployed sensors.


Query parameters

Name Type Required? Default value Description
sensors List < SensorId > Optional A comma-separated list of queried sensor site ids. If not specified, return data from all sensors.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT

API usage counters

  • Total

Report time intervals when individual sensors were operating, including the short-term outages. A gap in operating intervals would indicate a sensor outage.

There might be some false positive sensor outages reported. It happens when a sensor operates in the offline mode after losing internet connection. In such cases, the train data are uploaded once the sensor reconnects, but the time period is still tracked as an outage.

By default, the data for the last 30 days are provided. The time-range can be changed using the query parameters.


Query parameters

Name Type Required? Default value Description
end Instant Optional The end of the requested time range for sensors activity data. If not provided, the current time is used.
sensors List < SensorId > Optional A comma-separated list of queried sensor site ids. If not specified, return data from all sensors.
start Instant Optional The start of the requested time range for sensors activity data. If not provided, the UTC midnight 30 days ago is used.
For more information about query parameters and their serialization see Query Parameters Notes.

Responses

Required permissions

  • DATA_EXPORT

API usage counters

  • Total

List information about all available geographical regions. The regions are grouped to region partitions. The region partitions can be modified, or new region partitions can be defined in the Railstate UI.


Responses

Required permissions

  • REGIONS_USER

API usage counters

  • Total

Models

The list of data models used by the documented API routes as request or response bodies. All data models are serialized in JSON format.

Unique string identifier of an equipment list.


Type alias for String.
Name Type Description
sensorId SensorId

Unique identifier of the rail sensor.
active List < TimeInterval >

List of time intervals when the sensor was active.
Name Type Description
sensorId SensorId

Unique identifier of the rail sensor.
name String

Sensor's human-readable name (without region).
lat Double

Latitude in degrees.
lng Double

Longitude in degrees.
railways List < RailId >

List of railroads owning the rail line(s) monitored by this sensor.
operatingRailways List < RailId >

List of railroads operating on the rail line(s) monitored by this sensor.
timezone String Optional

Name of the sensor's local timezone. We use TZ database names listed at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
country String Optional

Country where the sensor is located.
region String Optional

State or province where the sensor is located.
isActive Boolean

Is the sensor active right now?
launchDate Instant Optional

The timestamp when the sensor site started operating for the first time.
retiredDate Instant Optional

The timestamp when the sensor site was retired. Null, if the sensor site is still in use.
siteContext String Optional

The description of rail traffic or operations observed at the sensor site, if noted.
Name Type Description
sensors List < SensorInfo >

List of data about individual sensors.
Name Type Description
sensors List < SensorActivityTimeline >

The history of individual sensors.
queryInterval TimeInterval

The historical time interval covered by this sensor status history instance. The activity of the sensors outside this time interval is not reported.

An identification of a region in a region partition specified in format "{region_id}@{partition_id}" (for example "CA@geo_countries").


Type alias for String.
Name Type Description
fullId RegionAtPartitionId

The unique global identifier of the region.
shortId RegionId

The short identifier of the region. It is valid only within the region partition.
name String

The human readable name of the region.
description String Optional

An optional description of the region.
sensorIds List < SensorId >

The list of sensors belonging to the region. The list includes all sensors within the selected polygons, as well as all the hand-picked sensors outside the polygons.
geometry MapPolygonUnion Optional

The border of the region. It can be formed by multiple polygons. The border is optional. If it is present all sensors within one of the border polygons are assigned inside the region.

Unique identifier of a geographical region within a regions partition. Short region ids should be preferred for more efficient queries.


Type alias for String.
Name Type Description
id RegionsPartitionId

The unique identifier of the regions partition.
name String

The human-readable name of the regions partition.
description String Optional

An optional description of the region partition.
regions List < RegionDescription >

The description of regions of the regions partition.
lastModified Instant

The timestamp of the last modification of the regions partition.
Name Type Description
partitions List < RegionPartitionDescription >

The list of available region partitions.

Unique identifier of a geographical partition to regions.


Type alias for String.
An enumeration type, that can be one of the following string values: ["Last sightings", "All sightings"].
An enumeration type, that can be one of the following string values: ["Trains", "Cars"].
Name Type Description
owner RailId Optional

The owner of the rail car or locomotive.
isLoaded Boolean Optional

The load status of the rail car inferred from sensor imagery. True, if the train car is loaded. False, if the car is empty. Null if the loaded status is unknown, or if it does not make sense to distinguish for the concrete car type (e.g. locomotives).
Name Type Description
containerSightingId ContainerSightingId Optional

Unique integer identifier of a shipping container sighting. Populated only if the container_sighting_id attribute is requested.
containerParameters ShippingContainer Optional

Observed parameters of the shipping container. Populated only if the container_params attribute is requested.
containerPosition ContainerPosition Optional

The position of the container on the stack car platform. Populated only if the container_position attribute is requested.
containerHazmats List < HazMatPlacard > Optional

Information about hazmat placards detected on the container. Populated only if the container_hazmats attribute is requested.
carSightingId CarSightingId Optional

Unique integer identifier of the rail car observation. Populated only if the car_sighting_id attribute is requested.
railCar RailCar Optional

Equipment id and type of the rail car. Populated only if the rail_car attribute is requested.
carPosition Integer Optional

The position of the rail car/intermodal platform in the train consist starting from 1. Populated only if the car_position attribute is requested.
trainSightingId TrainSightingId Optional

Unique integer identifier of the train sighting the car observation is a part of. Populated only if the train_sighting_id attribute is requested.
detection TrainDetection Optional

The time and place of the train detection. Populated only if the detection attribute is requested.
trainSightingParameters TrainSightingParameters Optional

Additional parameters of the train sighting. Populated only if the train_sighting_params attribute is requested.
trainComposition TrainComposition Optional

Information about the composition of the train sighting. Populated only if the train_composition attribute is requested.
sensorLocalTimes SiteLocalTimes Optional

Detection times in sensor local timezone. Populated only if the sensor_local_times attribute is requested.
observedCarParameters CarSightingParameters Optional

Additional parameters of the rail car sighting. Populated only if the car_params attribute is requested.
registeredCarParameters EquipmentParameters Optional

Registered equipment parameters of the rail car or the locomotive. Populated only if the registered_car_params attribute is requested.
carImageUrl String Optional

URL to a car image if available and requested. Populated only if the car_image_url attribute is requested.
lastModified Instant Optional

The timestamp when the train data were last modified. Populated only if the last_modified attribute is requested.
warnings List < TrainSightingWarning > Optional

Warnings about irregularities of the train sighting and potential data issues. Populated only if the train_warnings attribute is requested.
Name Type Description
containerSightingId ContainerSightingId Optional

Unique integer identifier of a shipping container sighting. Populated only if the container_sighting_id attribute is requested.
parameters ShippingContainer Optional

Observed parameters of the shipping container. Populated only if the container_params attribute is requested.
position ContainerPosition Optional

The position of the container on the stack car platform. Populated only if the container_position attribute is requested.
hazmats List < HazMatPlacard > Optional

Information about hazmat placards detected on the container. Populated only if the container_hazmats attribute is requested.
An enumeration type, that can be one of the following string values: ["TRAIN_SIGHTING_ID", "DETECTION", "TRAIN_SIGHTING_PARAMS", "TRAIN_COMPOSITION", "TRAIN_WARNINGS", "SENSOR_LOCAL_TIMES", "CAR_SIGHTING_ID", "RAIL_CAR", "CAR_PARAMS", "REGISTERED_CAR_PARAMS", "CAR_POSITION", "CAR_HAZMATS", "CAR_IMAGE_URL", "CONTAINER_SIGHTING_ID", "CONTAINER_PARAMS", "CONTAINER_POSITION", "CONTAINER_HAZMATS", "LAST_MODIFIED", "TRAIN_DIMENSIONS"].
Name Type Description
carId RailCarId Optional

Car or locomotive identifier read by OCR. Null, if the identifier is unknown.
type CarType

The type of the sighted car or a locomotive.
equipmentLists List < EquipmentListId >

Equipment lists the car is a member of.
Name Type Description
carSightingId CarSightingId Optional

Unique integer identifier of the rail car observation. Populated only if the car_sighting_id attribute is requested.
railCar RailCar Optional

Equipment id and type of the rail car. Populated only if the rail_car attribute is requested.
carPosition Integer Optional

The position of the rail car/intermodal platform in the train consist starting from 1. Populated only if the car_position attribute is requested.
trainSightingId TrainSightingId Optional

Unique integer identifier of the train sighting the car observation is a part of. Populated only if the train_sighting_id attribute is requested.
detection TrainDetection Optional

The time and place of the train detection. Populated only if the detection attribute is requested.
trainSightingParameters TrainSightingParameters Optional

Additional parameters of the train sighting. Populated only if the train_sighting_params attribute is requested.
trainComposition TrainComposition Optional

Information about the composition of the train sighting. Populated only if the train_composition attribute is requested.
sensorLocalTimes SiteLocalTimes Optional

Detection times in sensor local timezone. Populated only if the sensor_local_times attribute is requested.
carParameters CarSightingParameters Optional

Additional parameters of the rail car sighting. Populated only if the car_params attribute is requested.
registeredParameters EquipmentParameters Optional

Registered equipment parameters of the rail car or the locomotive. Populated only if the registered_car_params attribute is requested.
hazmats List < HazMatPlacard > Optional

Information about hazmat placards detected on the rail car. Populated only if the car_hazmats attribute is requested.
containers List < ContainerSightingOnCarModular > Optional

Information about shipping containers loaded on the rail car. Populated only if one of the container attributes is requested.
carImageUrl String Optional

URL to a car image if available and requested. Populated only if the car_image_url attribute is requested.
lastModified Instant Optional

The timestamp when the train data were last modified. Populated only if the last_modified attribute is requested.
warnings List < TrainSightingWarning > Optional

Warnings about irregularities of the train sighting and potential data issues. Populated only if the train_warnings attribute is requested.
Name Type Description
results List < Object >

The results matching the search query. The number of results does not have to match the requested page size. In case of too small page size, the returned list of results might be empty.
nextPageUrl String Optional

The URL to fetch the following block of data. If null, the data are complete.
Name Type Description
containerId String Optional

Equipment id of the container, null if unknown.
incompleteId Boolean

If true, the identification number of the container was not read fully. Either the identification number was read only partially, or the check digit does not match.
type ContainerType Optional

The type of the container (e.g. 'Container 53 Feet', 'Trailer 20 Feet').
typeCode String Optional

4-character ISO identifier of the container type.
Name Type Description
detectionStart ZonedDateTime

The detection time in the time zone of the sensor.
detectionEnd ZonedDateTime Optional

The end detection time in the time zone of the sensor, if it is known. It is the time when the train completely passed by the sensor.
Name Type Description
locomotiveCount Integer

The number of locomotives in the train sighting.
carCount CarCount

Information about car counts of the train sighting.
containerCount Integer

The number of shipping containers of the train sighting.
Name Type Description
trainTripId TrainProfileId Optional

Unique identifier of the train trip.
sensorId SensorId

Identifier of the rail sensor that made the sighting.
detectionTime Instant

UTC timestamp of the train sighting detection.
direction CardinalDirection

The time-table direction of the rail line at the place of the sighting.
trainTag TrainTag Optional

Custom tag assigned to the train trip.
Name Type Description
carSightingId CarSightingId Optional

Unique integer identifier of the rail car observation. Populated only if the car_sighting_id attribute is requested.
railCar RailCar Optional

Equipment id and type of the rail car. Populated only if the rail_car attribute is requested.
carParameters CarSightingParameters Optional

Additional parameters of the rail car sighting. Populated only if the car_params attribute is requested.
registeredParameters EquipmentParameters Optional

Registered equipment parameters of the rail car or the locomotive. Populated only if the registered_car_params attribute is requested.
hazmats List < HazMatPlacard > Optional

Information about hazmat placards detected on the rail car. Populated only if the car_hazmats attribute is requested.
containers List < ContainerSightingOnCarModular > Optional

Information about shipping containers loaded on the rail car. Populated only if one of the container attributes is requested.
carImageUrl String Optional

URL to a car image if available and requested. Populated only if the car_image_url attribute is requested.
Name Type Description
trainSightingId TrainSightingId Optional

Unique integer identifier of the train sighting the car observation is a part of. Populated only if the train_sighting_id attribute is requested.
detection TrainDetection Optional

The time and place of the train detection. Populated only if the detection attribute is requested.
sightingParameters TrainSightingParameters Optional

Additional parameters of the train sighting. Populated only if the train_sighting_params attribute is requested.
trainComposition TrainComposition Optional

Information about the composition of the train sighting. Populated only if the train_composition attribute is requested.
sensorLocalTimes SiteLocalTimes Optional

Detection times in sensor local timezone. Populated only if the sensor_local_times attribute is requested.
cars List < TrainSightingCarModular > Optional

The consist of the train sighting. Populated only if at least one of the car-level or container-level attribute is requested.
estimatedDimensions EquipmentDimensions Optional

The estimated total dimensions (length, weight, capacity, ...) of the train. The data of the cars with unknown dimensions are estimated as the average of the cars of the same car type. Populated only if the train_dimensions attribute is requested.
warnings List < TrainSightingWarning > Optional

Warnings about irregularities of the train sighting and potential data issues. Populated only if the train_warnings attribute is requested.
lastModified Instant Optional

The timestamp when the train data were last modified. Populated only if the last_modified attribute is requested.
Name Type Description
trainSetId TrainSetId Optional

The identifier of a set of train trips, tracking the train beyond a single one-way journey. For (unit) trains with stable train consists all inbound and outbound train trips are expected to have the same train set id. For trains with unstable train consist (e.g. manifest trains) the train set ids might be meaningless. When a train terminates its journey, its train set id is assigned to one of the following train trips that contain a clear majority of the rail cars and locomotives of the original trip. If no clear successor trip is found, then the train set id is not assigned to any following train trip.
trainTripActive Boolean

If true, the train trip is still considered to be active, meaning that there is no known following train trip in the train set, and that this train trip is the last known observation for the majority of its rail cars and locomotives. In other words, the train trip is inactive if there is a known successor train trip, or if the train was split into multiple pieces after its termination (the majority of the rail cars and locomotives were already observed elsewhere).

The flag might be incorrectly set to true for trains with no recognized car and locomotive ids.
trainType TrainType Optional

The type of the train. E.g. 'Coal Unit'.
speed Measurement < SpeedInMilesPerHour >

The speed of the train in miles per hour.
railways RailId Optional

The railway that operates the train at this sighting.
detectionEnd Instant Optional

UTC timestamp of the end of the train sighting detection, if known.
An enumeration type, that can be one of the following string values: ["Empty", "Loaded", "Unknown"].

A string wildcard encoding a condition for a route traversed by a train or a rail car. The wildcard specifies regions including their order where the train or car is to be detected.

The region route wildcard consists of 3 parts:

  • the waypoints part specifying the regions the train or the car must pass through,

  • the region partitions id that defines the regions used in the waypoints part,

  • and finally the matching sites suffix determining which sightings of the train or car that traversed the route are returned by the search.

The waypoint part and the region partition id are separated by the @ character. The region partition id and the matching site suffix are separated by the ~ character.

The waypoints part of the wildcard is formed by a list of waypoints concatenated to a string. There are 3 supported types of waypoints that can appear in the waypoints part.

A detection at a concrete region specified in the format <{region_id}#{extent}> where {region_id} is the string identifier of a region (without the partition id), and {extent} is one of the letters A, F, L specifying how many detections from the region should be matched. The #{extent} part is optional. The default option #A matches all consecutive sightings in the region. The option #F matches just the first sighting of the region and it can be used only for the last region in the route. Finally, the option #L matches just the last sighting in the region, and it can be used only for the first region in the route.

Then there are two special waypoint wildcards:

  • ? standing for exactly one detection of the train or car in an arbitrary region of the region partition.

  • And * standing for an arbitrary number of detections (possibly 0) at arbitrary regions.

The optional matching sites suffix at the end of the site route wildcard is specified by a single letter. Three options are supported F, E and S. F is the default used if no matching sites suffix is set.

  • F stands for 'full'. This matching sites option will return all sighting of the train or car between the first and the last region specified in the route (including both the first and the last region).

  • The matching mode E, standing for 'end', returns just one matching sighting per train or car. It is the last sighting on the route (typically, the last sighting in the last specified region).

  • And finally the matching mode S, standing for 'start', returns just sightings at the first sighting on the route (typically, the first sighting in the first specified region).

The modes E and S are useful for unique counting of trains/cars that traversed the route. The F mode can return each train/car multiple times, sighted by different sensors on the route.

In total, the site route wildcard must match the following regular expression: ^(\*|\?|<[a-zA-Z0-9_/-]+(#[AFL])?>)+@[a-zA-Z0-9_-]+(~[FES])?$.

All the region specified in the region route must belong to the same region partition. The sightings at sensors not belonging to any region of the partition are not considered when matching region routes.

Examples:

  • *<CA/AB>*@geo_states - matches train sightings in Alberta (the train/car might be also detected in other provinces both before and after some sightings in Alberta). The matching sites suffix is missing, so the deafult 'full route' option is used. That means that all sightings in Alberta matches the wildcard.

  • <CA>@geo_countries~E - matches the last sighting of each train trip that did not leave Canada. Since the waypoints part does not have the '*' wildcard and at the end, the condition matches just trains that were sighted in Canada. The route-end matching sites suffix ensures that just the last sighting of each train trip is returned.

  • *<CA/AB#L>*<CA/MB#F>*@geo_states~F - matches trains that traveled from Alberta to Manitoba. More specificaly it matches the last sighting of such trains in Alberta, the first sighting of such trains in Manitoba and all the sightings in between (likely all the Saskatchewan sightings of the train).

  • <CA/ON><US/NY>@geo_states~F - matches all trains that were sighted for the first time in Ontario, that crossed the border to the New York state, and were sighted for the last time in the New York. The trains are not allowed to be sighted in another state or a province in between. All the sightings of the trains match the wildcard - from their first sighting in Ontario, up to their last sighting in New York.

  • *?<CA/AB#F>*@geo_states - matches the first inbound sighting of all trains entering Alberta. The '*?' combination at the start requires that the train must have at least one sighting in a region outside Alberta. The '#F' requirement at the Alberta region ensures that just the first sighting in Alberta matches the route. The train trip might or might not terminate in Alberta.


Type alias for String.

A string wildcard encoding a condition for a route traversed by a train or a rail car. The wildcard specifies sensor sites (possibly with directions) including their order where the train or car is to be detected.

The site route wildcard consists of the waypoints part, specifying the sensor sites the train or the car must pass through, and the matching sites suffix, determining which sightings of the train or car that traversed the route are returned by the search. The waypoint part and the matching site suffix are separated by ~ character.

The waypoints part of the wildcard is formed by a list of waypoints concatenated to a string. There are 3 supported types of waypoints that can appear in the waypoints part.

A detection at a concrete sensor specified in the format #{sensor_id}{dir} where {sensor_id} is the sensor site integer identifier, and {dir} is one of N, W, S, E, or ? setting the direction of the train at the sensor (? stands for an arbitrary direction, N stands for 'Northbound', W for 'Westbound', etc.).

Then there are two special waypoint wildcards:

  • ? standing for exactly one detection of the train or car at an arbitrary sensor site.

  • And * standing for an arbitrary number of detections (possibly 0) at arbitrary sensor sites.

The matching sites suffix at the end of the site route wildcard is specified by a single letter. Three options are supported F, E and S. F is the default used if no matching sites suffix is set. F stands for 'full'. This matching sites option will return all sighting of the train or car between the first and the last sensor specified in the route. The matching mode E, standing for 'end', returns just sightings at the last specified sensor of the route. And finally the matching mode S, standing for 'start', returns just sightings at the first sensor site appearing in the route. The modes E and S are useful for unique counting of trains/cars that traversed the route. The F mode can return each train/car multiple times, sighted by different sensors on the route.

In total, the site route wildcard must match the following regular expression: ^(\*|\?|#[1-9][0-9]*[NWSE?])+(~[FES])?$.

Examples:

  • *#8?* - Trains that were sighted at sensor 8 (there might or might not be other detections of the train both before and after the sighting at sensor 8). The sites matching mode is irrelevant here. All the options return the same results.

  • *#12W*#13N*~E - Trains that passed sensor 12 going west and later sensor 13 travelling north. Only the sightings at the final sensor site 13 are returned (because 'E' matching sites mode is used).

  • #6S#8?*~F - Trains that originated at sensor 6 going south (with no prior detection) and then immediately detected by sensor 8 (with no other detections between 6S and 8.). The trains might continue anywhere beyond the sensor site 8. The search will return sightings both at sensors 6 and 8 because 'F' matching mode is used.

  • #10?*#20??*~F - Trains that originated at sensor 10, then were spotted by sensor 20 (with some potential detections between sensors 10 and 20), and then were detected by at least one more sensor after sensor 20. The search will return sightings at sensor 10, sensor 20, and all sites visited by the trains between sensors 10 and 20. However, the sightings after the sensor site 20 will not be returned because they come after the last concretly specified sensor site of the route.


Type alias for String.

Equipment id wildcard string of rail cars and locomotives. A car id consists of 2-4 letters followed by up to 6 digits. (In Railstate database, some locomotives might lack the letter prefix. In such cases, just the digits are stored.)

The wildcard string supports the following special characters:

  • # standing for any single digit,

  • and * standing for any number of digits (possibly zero). '*' can be used only at the end.

Some example wildcards that can be used:

  • CP1234 requires the exact equipment id match,

  • DTTX* matching all rail car ids starting with 'DTTX' with no constraint on the digits,

  • BNSF1### matching all equipment ids starting with 'BNSF1' followed by exactly 3 arbitrary digits,

  • TTLX####* matching all car ids starting with 'TTLX' followed by at least 4 digits (possibly more).


Type alias for String.
An enumeration type, that can be one of the following string values: ["Complete IDs", "Incomplete IDs"].

Equipment id wildcard string of intermodal shipping containers. A container id consists of 4 letters followed by 4-6 digits (typically 6). Checksum digits of international containers are not included.

The wildcard string supports the following special characters:

  • # standing for any single digit,

  • and * standing for any number of digits (possibly zero). '*' can be used only at the end.

Some example wildcards that can be used:

  • TCLU123456 requires the exact equipment id match,

  • JBHU* matching all containers with letter part 'JBHU' with no constraint on the digits,

  • ANZU1##### matching all equipment ids starting with 'ANZU1' followed by exactly 5 arbitrary digits.


Type alias for String.

A range of non-negative integers encoded to a string in format 'start-end', where 'start' and 'end' are non-negative integers. Both of them are included in the range. 'start' must be less than or equal to 'end'. For example 2-5 encodes the range from 2 to 5 (i.e. 2, 3, 4, and 5).


Type alias for String.

Umler® equipment type code wildcard string matching the 'umet' property in the Umler® database. The equipment type codes are 4 characters long, starting with a letter, that is followed by 3 digits.

The wildcard string supports a special character # that substitutes and arbitrary digit.

Some example wildcards that can be used:

  • C113 requires the exact equipment type code match,

  • B### matching all equipment type codes starting with 'B'.


Type alias for String.

Hazard material class code. It is possible to use top-level class codes such as 4 (flammable solids), or more specialized codes such as 4.2 (spontaneously combustible solids).


Type alias for String.

A hazardous material UN number including the 'UN' prefix (e.g. un1202), or one of the following special constants:

  • empty for empty placard holders,

  • unreadable for cars and containers with a hazmat placard with unknown un numbers,

  • not_detected for cars and containers without any hazmat placard or an empty placard holder,

  • and any to match all cars and containers with a hazmat placard.


Type alias for String.

Wildcard string for the stenciled shipping spec listed in the Umler® database. A shipping spec stencil consists of letters and digits. The precise format description can be found in the documentation of the Umler® database.

Outside of the letters and digits, the wildcard string supports the following characters:

  • # replacing a single arbitrary digit,

  • ? replacing a single arbitrary letter,

  • * replacing an arbitrary long suffix of digits and letters ('*' can be used only at the end of the wildcard).


Type alias for String.
An enumeration type, that can be one of the following string values: ["No warnings", "Any warning", "Partial sighting", "Switch operation", "Unverified detection", "Sensor under evaluation"].
An enumeration type, that can be one of the following string values: ["active", "inactive"].
Name Type Description
cars Integer

Count of train cars, when intermodal platforms are not distinguished. An intermodal car with 5 platforms is counted as 1 car.
platforms Integer

Count of train cars, while counting the intermodal platforms separately. An intermodal car with 5 platforms is counted as 5 cars.
Name Type Description
containerSightingId ContainerSightingId

The unique identifier of the container sighting.
identificationNumber String Optional

The container identifier read by the OCR, null if unknown.
incompleteId Boolean

If true, the identification number of the container was not read fully. Either the identification number was read only partially, or the check digit does not match.
type ContainerType Optional

The type of the container (e.g. 'Container 53 Feet', 'Trailer 20 Feet').
position ContainerPosition Optional

The position of the container on the rail car (e.g. 'Bottom Front').
typeCode String Optional

4-character ISO identifier of the container type.
hazmats List < HazMatPlacard > Optional

Detected hazmat placards attached to the shipping container. If null, the hazmat detection was not performed. If empty list, the hazmat detection was performed but no placards were found.
Name Type Description
deletedRecordId Integer

Unique identifier of the deleted train sighting record.
sightingId TrainSightingId

Unique identifier of the train sighting.
sensorId SensorId Optional

Identifier of the sensor that made the train detection.
detectionTime Instant Optional

UTC timestamp of the train sighting detection.
speedMph Measurement < SpeedInMilesPerHour > Optional

The speed of the train in miles per hour.
deletionTime Instant

UTC timestamp of the train sighting deletion.
Name Type Description
sightings List < DeletedTrainSighting >

List of deleted train sightings ordered by the deletion time.
nextRequestLink String Optional

Link where the next block of data can be fetched. If null, there is no next block. The data are already complete.
An enumeration type, that can be one of the following string values: ["Tier 0", "Tier 0+", "Tier 1", "Tier 1+", "Tier 2", "Tier 2+", "Tier 3", "Tier 4", "Tier 4C", "Awaiting first engine change", "Exempt", "Export only"].
Name Type Description
gallonageCapacity Double Optional

The liquid capacity in gallons. Populated only for tank cars.
cubicFeetCapacity Double Optional

The capacity of the inner space in cubic feet. Populated only for some car types such as box cars, gondolas, and hoppers. Not populated for tank cars.
loadLimitTons Double Optional

The load limit of the equipment in (short) tons. For intermodal cars, it is the load limit of the entire car, not just individual platforms.
tareWeightTons Double Optional

The tare weight of the equipment in (short) tons. For intermodal cars, it is the weight of the entire car, not just individual platforms.
grossWeightTons Double Optional

The gross weight of the equipment in (short) tons. For intermodal cars, it is the weight of the entire car, not just individual platforms.
lengthFeet Double Optional

The (outside) length of the equipment in feet. For intermodal cars, it is the length of the entire car, not just individual platforms.
Name Type Description
typeCode String Optional

The equipment type code used in the Umler database.
lessee RailId Optional

The identifier of the company leasing the equipment registered in Umler. The reporting marks listed in UMLER are translated to railroad identifiers used throughout the Railstate system.
emissionsTier EPAEmissionsTier Optional

The emission tier of the locomotive registered in Umler. The emission tiers are specified by the Environmental Protection Agency.
propelledBy LocomotivePropelledBy Optional

The type of the locomotive engine registered in Umler.
horsepower Integer Optional

The horsepower of the locomotive registered in Umler.
locoModel String Optional

The manufacturer model number of the locomotive registered in Umler.
dimensions EquipmentDimensions

Information about dimensions (length, weight, capacity, ...) of the train car.
stenciledShippingSpec String Optional

The Stenciled shipping spec registered in Umler.
equipmentBuilder String Optional

The original manufacturer of the equipment registered in Umler.
compartmentCount Integer Optional

The number of individual compartments the equipment contains. (Range of values 1 - 9)
outletCount Integer Optional

The number of bottom outlets or washouts on the equipment. (Range of values 0 - 9)
Name Type Description
type CarType

The type of the sighted car or a locomotive.
carId String Optional

Car or locomotive identifier read by OCR. Null, if the identifier is unknown.
hazmats List < HazMatPlacard > Optional

Information about detected hazmat placards attached to the train car. If null, the hazmat detection was not performed. If empty list, the hazmat detection was performed but no placards were found. Hazmat placards attached to containers loaded on this train car are listed in 'hazmats' lists of individual containers.
containers List < ContainerSighting > Optional

Data about shipping containers loaded on the train car. If null, container detection was not performed. If empty list, then no containers were identified.
owner RailId Optional

The owner of the rail car or locomotive.
isLoaded Boolean Optional

The load status of the rail car inferred from sensor imagery. True, if the train car is loaded. False, if the car is empty. Null if the loaded status is unknown, or if it does not make sense to distinguish for the concrete car type (e.g. locomotives).
equipmentParameters EquipmentParameters Optional

Additional parameters of the train car or the locomotive.
carImageUrl String Optional

URL to the image of the train car. The URL has a limited validity. Null, if the car image is not available.
Name Type Description
sightingId TrainSightingId

The unique integer identifier of the single train sighting.
trainId TrainProfileId Optional

The identifier of the (one-way) train trip. 'Train Trip ID' and 'Train Profile ID' are alternative names for this identifier. Train ids can be used to track the train's movement through the rail network.
trainSetId TrainSetId Optional

The identifier of a set of train trips, tracking the train beyond a single one-way journey. For (unit) trains with stable train consists all inbound and outbound train trips are expected to have the same train set id. For trains with unstable train consist (e.g. manifest trains) the train set ids might be meaningless. When a train terminates its journey, its train set id is assigned to one of the following train trips that contain a clear majority of the rail cars and locomotives of the original trip. If no clear successor trip is found, then the train set id is not assigned to any following train trip.
trainTripActive Boolean

If true, the train trip is still considered to be active, meaning that there is no known following train trip in the train set, and that this train trip is the last known observation for the majority of its rail cars and locomotives. In other words, the train trip is inactive if there is a known successor train trip, or if the train was split into multiple pieces after its termination (the majority of the rail cars and locomotives were already observed elsewhere).

The flag might be incorrectly set to true for trains with no recognized car and locomotive ids.
sensorId SensorId

The identifier of the sensor that made the train detection.
detectionTimeUTC Instant

The time of the train detection in UTC.
detectionTimeSensorLocal ZonedDateTime

The detection time in the time zone of the sensor.
detectionEndUTC Instant Optional

The time of the end of the train detection in UTC, if it is known. It is the time when the train completely passed by the sensor.
detectionEndSensorLocal ZonedDateTime Optional

The end detection time in the time zone of the sensor, if it is known. It is the time when the train completely passed by the sensor.
direction CardinalDirection

The direction of the train.
speedMph Measurement < SpeedInMilesPerHour >

The estimated speed of the train in miles per hour as it was passing the sensor. Trains do not have to pass the sensor travelling at a constant speed. Especially for long trains, the travel speed can change as they travel by. Some might even stop completely for a moment.

The provided value is just one of speed measurements of the passing trains. It is not the average speed of the train.
trainType TrainType Optional

The type of the train. E.g. 'Coal Unit'.
trainOperator RailId Optional

The railroad operating the train. (E.g. 'CN')
cars List < FullCarSighting >

The list of cars ordered as they were ordered in the train.
warnings List < LegacyTrainSightingWarning > Optional

[DEPRECATED] Warnings about irregularities of the train sighting.
issues List < TrainSightingWarning >

Warnings about irregularities of the train sighting and potential data issues.
lastModified Instant Optional

The time of the last modification of the train sighting data in UTC.
estimatedDimensions EquipmentDimensions

The estimated total dimensions (length, weight, capacity, ...) of the train. The data of the cars with unknown dimensions are estimated as the average of the cars of the same car type.
Name Type Description
sightings List < FullTrainSighting >

List of train sightings ordered by the last modification time.
nextRequestLink String Optional

API link where the next block of data can be fetched. If null, there is no next block. The data are already complete.
Name Type Description
placardType String Optional

The UN number of the hazmat placard, or 'EMPTY' for detected empty placard holders. If null, the UN number is unknown, but the placard was not empty.
hazmatClass String Optional

The hazard class of the hazmat placard, if applicable.
Name Type Description
code String

Code identifying the warning.
description String Optional

Human-readable description of the sighting warning.
An enumeration type, that can be one of the following string values: ["Diesel-Electric", "Diesel Multiple Unit", "Electric", "Electric Multiple Unit", "MU Control Cab", "Non-MU Control Cab", "Other", "Turbine", "Torque Converter"].

Equipment ID of a rail car or a locomotive. The expected format is 2-4 uppercase letters prefix padded by spaces from the right to 4 characters, and 6-digit suffix padded by zeros from the right. For locomotives the letter prefix might be missing.

Examples:

  • CP 123456,

  • ABCD001234,

  • 1234 - locomotive with missing prefix.


Type alias for String.
Name Type Description
sightingIds List < TrainSightingId >

A list of train sighting ids.
Name Type Description
sightingId TrainSightingId

The unique integer identifier of the single train sighting.
trainId TrainProfileId Optional

The identifier of the (one-way) train trip. 'Train Trip ID' and 'Train Profile ID' are alternative names for this identifier. Train ids can be used to track the train's movement through the rail network.
Name Type Description
sightings List < TrainTripAssignment >

List of assignments of train sightings to train trips.

Unique tag name of a set of trains.


Type alias for String.
Name Type Description
error String

Human-readable description of the error.
Name Type Description
start Instant Optional

The start of the time interval. If null the interval does not have a lower bound.
end Instant Optional

The end of the time interval. If null, the interval does not have an upper bound.
Name Type Description
longitude Double
latitude Double

Coordinates of the vertices of the polygon line.


Type alias for List < Coordinates > .
Name Type Description
border MapPolyLine

The border of the polygon. The inside is not the left side from the border.
Name Type Description
polygons List < MapPolygon >
An enumeration type, that can be one of the following string values: ["Partial sighting", "Switch operation", "Unverified detection", "Sensor under evaluation"].
An enumeration type, that can be one of the following string values: ["Northbound", "Westbound", "Southbound", "Eastbound"].
An enumeration type, that can be one of the following string values: ["Covered Hopper", "Tank Car", "Stack Car", "Box Car", "Equipped Gondola", "Equipped Hopper", "Vehicular Flatcar", "Passenger Car", "Centerbeam Flatcar", "General Service Flatcar", "Hopper - General Service", "Gondola", "Locomotive", "M-O-W", "Refrigerator Car"].
An enumeration type, that can be one of the following string values: ["Bottom", "Top", "Bottom Front", "Bottom Back"].
An enumeration type, that can be one of the following string values: ["Container 20 Feet", "Container 40 Feet", "Container 45 Feet", "Container 48 Feet", "Container 53 Feet", "Container 60 Feet", "Tank Container 20 Feet", "Tank Container 40 Feet", "Trailer 20 Feet", "Trailer 53 Feet", "Flatrack Container 20 Feet Empty", "Flatrack Container 20 Feet Full", "Flatrack Container 40 Feet Empty", "Flatrack Container 40 Feet Full"].
An enumeration type, that can be one of the following string values: ["Manifest", "Coal Unit", "Sulphur Unit", "Potash Unit", "Grain Unit", "Intermodal", "Automotive", "Petroleum Unit", "Light Locomotives", "Passenger", "MOW"].

Identifier of a single observation of a train car or a locomotive.


Type alias for Long.

Identifier of a single observation of a container.


Type alias for Long.

Unique identifier of a railroad.


Type alias for String.

Unique integer identifier of the sensor.


Type alias for Integer.

Unique identifier of a train that can be used to track the train's movement through the rail network.


Type alias for Integer.

Unique identifier of a train set, tracking a train beyond a single journey. For (unit) trains with stable train consists all inbound and outbound train trips are expected to have the same train set id. For trains with unstable train consist (e.g. manifest trains) the train set ids might be meaningless. When a train terminates its journey, its train set id is assigned to one of the following train trips that contains a clear majority of the rail cars and locomotives of the original trip. If there is not clear successor trip found, then the train set id is not assigned to any following train trip.


Type alias for Integer.

Unique identifier of a train sighting.


Type alias for Integer.

The value of the physical quantity in the base units of the quantity.


Type alias for Double.

A signed 32-bit integer.

Examples: 123456879, -9876.

A logical boolean value.

Examples: true, false.

A floating point number.

Examples: -12.35, 1.236e-7.

A signed 32-bit integer.

Examples: 123456879, -9876.

A signed 64-bit integer.

Examples: 123456879, -9876543210987.

A text string.

Examples: "Hello, world!", "", "Nested double quotes must be escaped (\").".

Timestamp passed as a string.

Output: UTC format specified in ISO 8601 a.k.a. "Zulu time" ('yyyy-mm-ddTHH:MM:SS.SSSZ').
Examples: "2022-08-28T13:24:56.768Z".

Input: In addition to the UTC "Zulu" format, it is also allowed to use a time string with a specified time zone offset (optionally even with a timezone name), or a floating point timestamp expressing the number seconds elapsed since the UNIX epoch.
Examples: "2022-08-28T13:24:56.768Z", "2022-08-28T07:24:56.768-06:00", "2022-08-28T07:24:56.768-06:00[America/Regina]", "1661693096.768".

Timestamp bound to a specific timezone passed as a string.

Output: ISO 8601 time string in 'yyyy-mm-ddTHH:MM:SS.SSS+offset[timezone name]' format including the time zone offset and time zone name.
Examples: "2022-08-28T07:24:56.768-06:00[America/Regina]".

Input: It is not necessary to specify the timezone name, the offset is sufficient. Alternatively, it is allowed to use the UTC "Zulu" time format, or floating point timestamp expressing the number seconds elapsed since the UNIX epoch.
Examples: "2022-08-28T07:24:56.768-06:00[America/Regina]", "2022-08-28T07:24:56.768-06:00", "2022-08-28T13:24:56.768Z", "1661693096.768".

A comma-separated list of elements of a specified type.

Examples: ["string 1", "string 2", ""], [147, 42, -32], [{"text": "nested string", "number": 23}, {"text": "another string", "number": 24}], [].

Notes

Query parameters

The Railstate API distinguishes 3 types of query parameters types:

  • Required that must always be specified by the API user.
  • Default that have a default value that would be used if the API user does not provide one.
  • Optional that are purely optional (without a default value).

There are some additional rules for encoding of values of query parameters:

  • Text strings are not enclosed in double quotes.
  • Standalone lists are passed without opening and closing brackets. The list elements are separated by commas without additional spaces.
  • Composite types are passed as strings encoded in the JSON format.
  • All special characters appearing in the query parameter values must be URL-encoded.
  • Unless state otherwise in the parameter documentation, query parameter values are not case-sensitive.