Difference between revisions of "Train Movements"

From Open Rail Data Wiki
Jump to navigation Jump to search
m (Add reference to JSON schema for TRUST messages)
(27 intermediate revisions by 8 users not shown)
Line 1: Line 1:
== Overview ==
+
The Train Movements feed contains data from Network Rail's [http://en.wikipedia.org/wiki/TRUST TRUST] system.  This reports on the progress of trains along their journey.
  
The train movements feed contains messages produced by [[TRUST]]. These messages are one of eight types, all in JSON format:
+
There's a fuller [[TRUST Message Process|description of the process]] available.
  
* 0001 - [[Train Activation]]
+
Because of the way TRUST works not every location will generate a report. If you want fine grain reporting then you would need to look at processing data from the TD feed and reporting based on that, or look at the [[Darwin:Push_Port|Darwin Push Port data]]. Darwin will generally capture more, better quality, and ad-hoc data as its part of the bigger customer information system - TRUST is an internal reporting tool and can be updated in 'slow time' meaning data can change or be late being input. A good example is cancelled services - they may be input to Darwin via another source (Darwin Workstation, Tyrell, CIS) leading to a cancellation, the actual TRUST cancellation may not come through till much later.
* 0002 - [[Train Cancellation]]
 
* 0003 - [[Train Movement]]
 
* 0004 - [[Unidentified Train]]
 
* 0005 - [[Train Reinstatement]]
 
* 0006 - [[Change of Origin]]
 
* 0007 - [[Change of Identity]]
 
* 0008 - [[Change of Location]]
 
  
== Lifecycle ==
+
TRUST data may also be updated/amended 'after the fact' so a delay which is input manually from TRUST DA may overwrite a previous automatic report and that could happen several days later. TRUST should always be historically correct.
  
Before any action can be taken on a train, the schedule must be activatedAn [Activation] message will be received, which will link a schedule to a 10-character train identity.  This identity is referenced in all other message types, and there is no need to calculate it manually.
+
TRUST does not provide predictions, it only reports on events that have happened. TRUST reports in 30 second intervals, and rounds to whole minutes.  - A train reporting 1 minute early or late may only be 31 seconds early or late in reality.
  
A train may be cancelled (either entirely or from a particular calling point onwards) through a [Train Cancellation] message, or start from a location other than the originating location through a [Change of Origin] message.  A train may be reinstated after cancellation through a [Train Reinstatement] message.
+
= Message Topics =
  
One point to note - the [Change of Identity] message type is rarely seen. This is used when a train running under one class (e.g. a Class 4 freight with a train identity starting 4---) must run under a different class for some reason - usually because it must run at a lower speed due to the type of load it is carrying.
+
Train movement messages are available through ActiveMQ TOC-specific topics, as well as an 'all TOCs' topic. You should note that the list of topics you can subscribe too may not match the list of [[TOC Codes]] on this wiki. Where a new operator is added to the system it may not show up in the individual topic lists for a while, however the data is sent to the TRAIN_MVT_ALL_TOC topic by default. Once the individual topic is listed data will then be filtered as per below. If you notice a missing or incorrect operator then please email support.
  
== Data Format ==
+
{| class="wikitable"
 +
!Topic name
 +
!Description
 +
|-
 +
|TRAIN_MVT_''XX''_TOC
 +
|Train movement messages for ''XX'' TOC.  These codes are business codes on the [[TOC Codes]] page
 +
|-
 +
|TRAIN_MVT_ALL_TOC
 +
|All train operating companies
 +
|-
 +
|TRAIN_MVT_FREIGHT
 +
|All non-passenger train operating company movements
 +
|-
 +
|TRAIN_MVT_GENERAL
 +
|Change of Identity messages for freight trains
 +
|}
  
Individual STOMP Packets, can contain between 1 and 32 JSON encoded strings. Each representing a single Train Movement Entry.
+
== Message types ==
  
Each JSON packet can contain any number of the following columns (depending on available data and message type).
+
The feed contains eight message types, all in JSON format:
Each packet consists of a Header and a Body.
 
  
- All Timestamp columns are in Milliseconds
+
{| class="wikitable"
 +
!Type
 +
!Description
 +
|-
 +
|0001
 +
|[[Train Activation]]
 +
|-
 +
|0002
 +
|[[Train Cancellation]]
 +
|-
 +
|0003
 +
|[[Train Movement]]
 +
|-
 +
|0004
 +
|Unidentified Train (not used in production)
 +
|-
 +
|0005
 +
|[[Train Reinstatement]]
 +
|-
 +
|0006
 +
|[[Change of Origin]]
 +
|-
 +
|0007
 +
|[[Change of Identity]]
 +
|-
 +
|0008
 +
|[[Change of Location]]
 +
|}
  
Header Entries
+
== Format ==
* msg_type as above
+
 
* source_dev_id
+
Each message is represented as a JSON hash with two keys - 'header' and 'body'.  Zero or more of these messages is sent out in a JSON list, either every five seconds or when there are 32 messages to be sent.  It is perfectly legitimate to receive an empty array.
* user_id - for when a message is not added Automatically this represents who initiated the message
+
 
* original_data_source - known values
+
All timestamp values are in milliseconds since the UNIX epoch. But it appears that in certain fields this is incorrect during British Summer Time (UK DST) and is <i>actually one hour in the future.</i> You will need to subtract one hour in order for the times to be valid.  This is known to affect the following fields:
** SDR
 
** SMART
 
** TOPS
 
** TRUST DA
 
** TSIA
 
* msg_queue_timestamp,
 
* source_system_id, normally TRUST
 
  
Body Entries
 
* train_id
 
* event_type, is the Train Arriving or Departing, blank for Activation/other messages that are not 0003
 
** ARRIVAL
 
** DEPARTURE
 
 
* gbtt_timestamp
 
* gbtt_timestamp
* original_loc_stanox
+
* planned_timestamp
* planned_timestamp, the timestamp the event is supposed to occur
+
* actual_timestamp
* timestamp_variation, number of minutes between actual time and reporting time, (always positive, refer to variation_status for early/late)
+
* canx_timestamp
* original_loc_timestamp,
+
* dep_timestamp
* current_train_id, used when the the msg_type is 0007, used to link between the old and new train_id
+
* orig_loc_timestamp
* delay_monitoring_point
+
 
* next_report_run_time
+
== Weekly Planned Outage ==
* reporting_stanox, the place reporting the update, but STANOX code,
+
 
* actual_timestamp, the timestamp the event occurred
+
Each week there is a short planned outage in the TRUST feeds, which normally takes place in the early hours of Sunday morning (when very few trains are running).  Usually the outage occurs at some point between 0200 and 0215 and lasts for approximately 5 minutes.  Any missed messages during the outage period are sent by the feed once it resumes.
* correction_ind
+
 
* event_source,
+
== Examples and source code ==
** AUTOMATIC
+
* [https://github.com/openraildata/network-rail-json-schema JSON schema for TRUST messages]
** MANUAL
+
 
* train_file_address
+
{{Navtable-DataFeeds}}
* platform, the platform the train is using, (not always populated)
+
 
* division_code
+
[[Category:Train Movement Data]]
* train_terminated, has the train completed this run meaning the end of the train running under its current train_id, it then deactivates
 
* offroute_ind, is the train running off schedule
 
* variation_status, qualifier for timestamp_variation
 
** EARLY
 
** LATE
 
** OFF ROUTE
 
** ON TIME
 
* train_service_code, the schedule reference index
 
* toc_id
 
* loc_stanox, the Stanox/location of the train
 
* auto_expected
 
* direction_ind,
 
** UP
 
** DOWN
 
* route
 
* planned_event_type, the kind of event that was expected
 
** ARRIVAL, the train arrived somewhere
 
** DEPARTURE, the train left somewhere
 
** DESTINATION, the train has reached the end of the line, All Change
 
* next_report_stanox, STANOX of the next expecte reporting location
 
* line_ind
 

Revision as of 00:41, 29 June 2022

The Train Movements feed contains data from Network Rail's TRUST system. This reports on the progress of trains along their journey.

There's a fuller description of the process available.

Because of the way TRUST works not every location will generate a report. If you want fine grain reporting then you would need to look at processing data from the TD feed and reporting based on that, or look at the Darwin Push Port data. Darwin will generally capture more, better quality, and ad-hoc data as its part of the bigger customer information system - TRUST is an internal reporting tool and can be updated in 'slow time' meaning data can change or be late being input. A good example is cancelled services - they may be input to Darwin via another source (Darwin Workstation, Tyrell, CIS) leading to a cancellation, the actual TRUST cancellation may not come through till much later.

TRUST data may also be updated/amended 'after the fact' so a delay which is input manually from TRUST DA may overwrite a previous automatic report and that could happen several days later. TRUST should always be historically correct.

TRUST does not provide predictions, it only reports on events that have happened. TRUST reports in 30 second intervals, and rounds to whole minutes. - A train reporting 1 minute early or late may only be 31 seconds early or late in reality.

Message Topics

Train movement messages are available through ActiveMQ TOC-specific topics, as well as an 'all TOCs' topic. You should note that the list of topics you can subscribe too may not match the list of TOC Codes on this wiki. Where a new operator is added to the system it may not show up in the individual topic lists for a while, however the data is sent to the TRAIN_MVT_ALL_TOC topic by default. Once the individual topic is listed data will then be filtered as per below. If you notice a missing or incorrect operator then please email support.

Topic name Description
TRAIN_MVT_XX_TOC Train movement messages for XX TOC. These codes are business codes on the TOC Codes page
TRAIN_MVT_ALL_TOC All train operating companies
TRAIN_MVT_FREIGHT All non-passenger train operating company movements
TRAIN_MVT_GENERAL Change of Identity messages for freight trains

Message types

The feed contains eight message types, all in JSON format:

Type Description
0001 Train Activation
0002 Train Cancellation
0003 Train Movement
0004 Unidentified Train (not used in production)
0005 Train Reinstatement
0006 Change of Origin
0007 Change of Identity
0008 Change of Location

Format

Each message is represented as a JSON hash with two keys - 'header' and 'body'. Zero or more of these messages is sent out in a JSON list, either every five seconds or when there are 32 messages to be sent. It is perfectly legitimate to receive an empty array.

All timestamp values are in milliseconds since the UNIX epoch. But it appears that in certain fields this is incorrect during British Summer Time (UK DST) and is actually one hour in the future. You will need to subtract one hour in order for the times to be valid. This is known to affect the following fields:

  • gbtt_timestamp
  • planned_timestamp
  • actual_timestamp
  • canx_timestamp
  • dep_timestamp
  • orig_loc_timestamp

Weekly Planned Outage

Each week there is a short planned outage in the TRUST feeds, which normally takes place in the early hours of Sunday morning (when very few trains are running). Usually the outage occurs at some point between 0200 and 0215 and lasts for approximately 5 minutes. Any missed messages during the outage period are sent by the feed once it resumes.

Examples and source code


Network Rail Open Data Feeds
Data Feeds About the Feeds Account States Durable Subscriptions Example Code ( PHP / C# / Java / Ruby / Node.js) • Advanced UsesFAQ Release Notes
RTPPM RTPPM Feed
Train Movements Train Movements Feed Train Activation Train Cancellation Train Movement Train Reinstatement Change of Origin Change of Identity Change of Location TSPEED Field Planned Cancellations Cancellation Codes
TD TD Feed C-Class Messages S-Class Messages Train Describers TD Berths
VSTP VSTP Feed
TSR TSR Feed Route Codes
SCHEDULE SCHEDULE Feed Schedule and Location Records Association Records CIF Codes How Scheduling Works Allowances
Reference Data Reference Data Feed TOC Codes CIF Codes Delay Attribution Codes Identifying Locations (STANOX, TIPLOC, NLC and 3-Alpha Codes) STANOX Geographical Areas Train Planning data