Difference between revisions of "SCHEDULE"

From Open Rail Data Wiki
Jump to navigation Jump to search
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The SCHEDULE feed is an extract of train schedules from Network Rail's ITPS (Integrated Train Planning System), available in JSON and CIF format.  
+
The SCHEDULE feed is an extract of train schedules from Network Rail's ITPS (Integrated Train Planning System), available in [[JSON File Format|JSON]] and [[CIF File Format|CIF]] format.
  
It is recommend that, if you are just starting out with the service, you use the JSON files.  The CIF data is more suited to advanced users of the service and requires additional parsing compared to the JSON data.
+
'''Note:''' If you are just starting out with the service use the JSON files.  The CIF data is more suited to advanced users of the service and requires additional parsing compared to the JSON data.
  
= Types of file =
+
= Overview =
  
== JSON format ==
+
The schedule data consists of Train Schedules, Train Associations and details of Timing Point Location codes.
  
The schedule files in JSON format are available for all operators, or for individual operators.
+
A description of the scheduling process is available on the [[HowSchedulingWorks | how scheduling works]] page.  This describes how multiple schedules can be used to describe a specific train service.
  
Two types of file are available:
+
= Usage =
  
* A full extract is produced each day, which can be used to initialise your schedule database
+
Trains are sets of schedules identified by a common ''UID''. A schedule for a specific train service can be uniquely identified by ''UID'', ''Start Date'' and ''STP Indicator''.
* An update extract is produced each day, which can be applied to the previous update extract to bring your database up-to-date
 
  
These files are generated
+
== Types of file ==
  
== CIF format ==
+
There are two types of files:
 +
* A full extract, a snapshot of schedule database valid on that day, which can be used to initialise your schedule database
 +
* An update extract is produced each night, which can be applied to the previous update extract to bring your database up-to-date
  
The schedule files in CIF format are only available for all operators.  A 'full' extract is available each Friday, and an 'update' extract is available daily.
+
Update extracts will specify how the schedule database has changed. It is important that the update files are processed in sequential order. Amendments may be received for schedules that are currently valid, i.e. the schedule has started running but has not finished yet. Changes will replace any previous version of a train schedule. Deletions will not be raised for schedules that have become historic.
 +
 
 +
The following formats are available from SCHEDULE Feed:
 +
 
 +
{| class="wikitable"
 +
! Format
 +
! Type
 +
! Rate
 +
! Details
 +
|-
 +
|rowspan="2"|[[JSON File Format]]
 +
|Full Extract
 +
|Daily
 +
|rowspan="2"|The schedules in JSON format are available for all operators, or for individual operators.
 +
|-
 +
|Update Extract
 +
|Daily
 +
|-
 +
|rowspan="2"|[[CIF File Format]]
 +
|Full Extract
 +
|Weekly
 +
|rowspan="2"|The schedules in CIF format are only available for all operators.  A 'full' extract is available each Friday, and an 'update' extract is available daily.
 +
|-
 +
|Update Extract
 +
|Daily
 +
|-
 +
|}
  
Two types of file are available:
+
The JSON data files are generated overnight and will be available from around 0600.  The CIF files are go through a different process and will be available from around 0100.
  
* A full extract is produced each Friday, which can be used to initialise your schedule database
+
'''Note:''' Late-notice train schedules, which are not available through the SCHEDULE feed, are published via the real-time [[VSTP]] feed.
* An update extract is produced each day, including Friday, which can be applied to the previous update extract to bring your database up-to-date
 
The [http://www.atoc.org/about-atoc/rail-settlement-plan/data-feeds/types-of-data CIF User Specification] is available from ATOC's website, which details the format of the CIF file and the fields within.
 
  
= Downloading =
+
== Downloading ==
  
The schedule data is compressed using gzip and is downloaded from Amazon S3 via a private URL which is valid for a few minutes after generation.  Authentication will be required either by logging in through the Data Feeds website, or by sending your username and password as part of the HTTP request.  On successful authentication, you will receive a 403 redirect to the location of the schedule files.  Requests are of the format:
+
The schedule data is compressed using gzip and is downloaded from Amazon S3 via a private URL which is valid for a few minutes after generation.  Authentication will be required either by logging in through the Data Feeds website, or by sending your username and password as part of the HTTP request.  On successful authentication, you will receive a HTTP 302 (Moved Temporarily) redirect to the location of the schedule file.  Requests are of the format:
  
 
   https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=type&day=day
 
   https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=type&day=day
Line 36: Line 61:
 
   https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=CIF_ALL_FULL_DAILY&day=toc-full
 
   https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=CIF_ALL_FULL_DAILY&day=toc-full
  
would download a full schedule file for all TOCs.
+
would download a full schedule file in JSON format for all TOCs. And if the CIF format is what you are after, add a trailing .CIF.gz to get the CIF format.
  
 
Values for ''type'' and ''day'' can be one of the following:
 
Values for ''type'' and ''day'' can be one of the following:
Line 89: Line 114:
 
A list of [[TOC Codes]] is available.  Note that the TOC code used in the URL is not the ATOC code as seen in schedule files, but the business code as used in Network Rail systems.
 
A list of [[TOC Codes]] is available.  Note that the TOC code used in the URL is not the ATOC code as seen in schedule files, but the business code as used in Network Rail systems.
  
The JSON data files are generated overnight and will be available from around 0600.  The CIF files are go through a different process and will be available from around 0100.
+
=== Downloading via curl ===
 
 
== Downloading via curl ==
 
  
 
The schedule file can be downloaded from the command line using the ''curl'' utility (included with linux, versions available for other operating systems) with the following syntax:
 
The schedule file can be downloaded from the command line using the ''curl'' utility (included with linux, versions available for other operating systems) with the following syntax:
Line 99: Line 122:
 
(Thanks to [[User:Jules Self|Jules Self]] for figuring this syntax out.)
 
(Thanks to [[User:Jules Self|Jules Self]] for figuring this syntax out.)
  
= JSON File Format =
+
=== Downloading via C# ===
 
 
The schedule data in JSON format has a single JSON record per line.  The file can be parsed line-by-line to extract the data required.  Each schedule file contains:
 
 
 
* A header row
 
* Zero or more TIPLOC records
 
* Zero or more association records
 
* Zero or more schedule records
 
* and an end-of-file (EOF) record.
 
 
 
Each association and schedule record has an action - either 'create' or 'delete'.  These are used in update files to add or remove records from the master schedule.  Deletions will not be raised for schedules that have become historic.  In full files, there will be no 'delete' records.  Update files must be applied sequentially to a full file.
 
 
 
== Record Types ==
 
  
Schedule data contains three types of records:
+
Below is sample code written in C# that will download files.
  
* [[Tiploc_Records | Tiploc records]] - containing details of timing point locations in the schedules
+
There is also a last modified check method that can be used to see if a new file has been uploaded using the file header - without downloading the full file. This is useful if you quickly want to check every hour if a file is new compared to any you may have.
* [[Association_Records | Association records]] - defining associations between services
 
* [[Schedule_Records | Schedule records]] - containing details of the schedules themselves
 
  
= CIF File Format =
+
[https://github.com/Legolash2o/OpenRailDataScheduleDownload C# Sample]
  
The CIF file contains a sequence of records.  Each record is 80 character long.  The first two bytes of a record identifies the type of a record.
+
== Validity ==
 
 
== Record Types ==
 
 
 
* '''HD''' - Header record
 
* '''TI''' - TIPLOC Insert record
 
* '''TA''' - TIPLOC Amend record
 
* '''TD''' - TIPLOC Delete record
 
* '''AA''' - Association record
 
* '''BS''' - Basic schedule record
 
* '''BX''' - Basic schedule extra details record
 
* '''LO''' - Origin location record
 
* '''LI''' - Intermediate location record
 
* '''CR''' - Change en Route
 
* '''LT''' - Terminating location record
 
* '''ZT''' - Trailer record (End of File)
 
 
 
= Validity =
 
  
 
Associations and schedule validities are between a start date and an end date, and on particular days of the week.  They each have a Short Term Planning (STP) indicator field as follows:
 
Associations and schedule validities are between a start date and an end date, and on particular days of the week.  They each have a Short Term Planning (STP) indicator field as follows:
  
 
* '''C''' - Planned cancellation: the schedule does not apply on this date, and the train will not run.  Typically seen on public holidays when an alternate schedule applies, or on Christmas Day.
 
* '''C''' - Planned cancellation: the schedule does not apply on this date, and the train will not run.  Typically seen on public holidays when an alternate schedule applies, or on Christmas Day.
* '''N''' - STP schedule: similar to a permanent schedule, but planned through the Short Term Planning process
+
* '''N''' - STP schedule: similar to a permanent schedule, but planned through the Short Term Planning process and not capable of being overlaid
 
* '''O''' - Overlay schedule: an alteration to a permanent schedule
 
* '''O''' - Overlay schedule: an alteration to a permanent schedule
 
* '''P''' - Permanent schedule: a schedule planned through the Long Term Planning process
 
* '''P''' - Permanent schedule: a schedule planned through the Long Term Planning process
  
For any date a permanent schedule ('P') is valid, it may be overridden by an overlay ('O') or a planned cancellation ('C'). However, if any two schedules appear to be valid for a particular day, the schedule with the lowest alphabetical STP indicator wins.
+
Permanent ('P') schedules can be overlaid by another schedule with the same UID - either a Variation ('O') or Cancellation Variation ('C'). For any particular day, of all the schedules for that UID valid on that day, the 'C' or 'O' schedule is the one which applies.  Conveniently, it also means that the lowest alphabetical STP indicator wins - 'C' and 'O' are both lower in the alphabet than 'P'.
  
= Scheduling Process =
+
This process allows a different schedule to be valid on particular days, or the service to not be valid on that day.  For example, a schedule may be valid Monday - Friday each day of the year, but have a Cancellation Variation on Christmas Day and Boxing Day only.
  
A description of the scheduling process is available on the [[HowSchedulingWorks | how scheduling works]] pageThis describes how multiple schedules can be used to describe a specific train service.
+
Cancellation variations are usually within the validity period of the base (permanent) schedule, however it is possible to have a cancellation variation which has a 'valid from' date which is within one version of a schedule and a 'valid to' date within another version of a schedule.  In this case, the variation applies to bothAn example of this is schedule C33552 at the start of 2015, where a cancellation variation applied to two separate permanent schedules.
  
 
{{Navtable-DataFeeds}}
 
{{Navtable-DataFeeds}}
  
 
[[Category:Schedule Data]]
 
[[Category:Schedule Data]]

Revision as of 10:03, 16 May 2020

The SCHEDULE feed is an extract of train schedules from Network Rail's ITPS (Integrated Train Planning System), available in JSON and CIF format.

Note: If you are just starting out with the service use the JSON files. The CIF data is more suited to advanced users of the service and requires additional parsing compared to the JSON data.

Overview

The schedule data consists of Train Schedules, Train Associations and details of Timing Point Location codes.

A description of the scheduling process is available on the how scheduling works page. This describes how multiple schedules can be used to describe a specific train service.

Usage

Trains are sets of schedules identified by a common UID. A schedule for a specific train service can be uniquely identified by UID, Start Date and STP Indicator.

Types of file

There are two types of files:

  • A full extract, a snapshot of schedule database valid on that day, which can be used to initialise your schedule database
  • An update extract is produced each night, which can be applied to the previous update extract to bring your database up-to-date

Update extracts will specify how the schedule database has changed. It is important that the update files are processed in sequential order. Amendments may be received for schedules that are currently valid, i.e. the schedule has started running but has not finished yet. Changes will replace any previous version of a train schedule. Deletions will not be raised for schedules that have become historic.

The following formats are available from SCHEDULE Feed:

Format Type Rate Details
JSON File Format Full Extract Daily The schedules in JSON format are available for all operators, or for individual operators.
Update Extract Daily
CIF File Format Full Extract Weekly The schedules in CIF format are only available for all operators. A 'full' extract is available each Friday, and an 'update' extract is available daily.
Update Extract Daily

The JSON data files are generated overnight and will be available from around 0600. The CIF files are go through a different process and will be available from around 0100.

Note: Late-notice train schedules, which are not available through the SCHEDULE feed, are published via the real-time VSTP feed.

Downloading

The schedule data is compressed using gzip and is downloaded from Amazon S3 via a private URL which is valid for a few minutes after generation. Authentication will be required either by logging in through the Data Feeds website, or by sending your username and password as part of the HTTP request. On successful authentication, you will receive a HTTP 302 (Moved Temporarily) redirect to the location of the schedule file. Requests are of the format:

 https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=type&day=day

where type determines the TOCs contained in the schedule extract and whether the file is a full schedule or an update file, and day determines which day's update file is downloaded. For example:

 https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=CIF_ALL_FULL_DAILY&day=toc-full

would download a full schedule file in JSON format for all TOCs. And if the CIF format is what you are after, add a trailing .CIF.gz to get the CIF format.

Values for type and day can be one of the following:

type day Description Example URL (JSON format) Example URL (CIF format)
CIF_ALL_FULL_DAILY toc-full Daily all-TOC snapshot Daily Weekly
CIF_ALL_UPDATE_DAILY toc-update-DAY Daily all-TOC update Mon, Tue, Wed, Thu, Fri, Sat, Sun Mon, Tue, Wed, Thu, Fri, Sat, Sun
CIF_XX_TOC_FULL_DAILY toc-full Daily snapshot for TOC XX Daily Not available
CIF_XX_TOC_UPDATE_DAILY toc-update-DAY Daily update for TOC XX Mon, Tue, Wed, Thu, Fri, Sat, Sun Not available
CIF_FREIGHT_FULL_DAILY toc-full Daily FREIGHT snapshot Daily Not available
CIF_FREIGHT_UPDATE_DAILY toc-update-DAY Daily update for FREIGHT Mon, Tue, Wed, Thu, Fri, Sat, Sun Not available

DAY should be replaced with the shortened version of the name of the previous day. For example, on Monday, Sunday's ('sun') update should be requested.

A list of TOC Codes is available. Note that the TOC code used in the URL is not the ATOC code as seen in schedule files, but the business code as used in Network Rail systems.

Downloading via curl

The schedule file can be downloaded from the command line using the curl utility (included with linux, versions available for other operating systems) with the following syntax:

 curl -L -u username:password -o file.gz 'https://datafeeds.networkrail.co.uk/ntrod/CifFileAuthenticate?type=CIF_ALL_FULL_DAILY&day=toc-full'

(Thanks to Jules Self for figuring this syntax out.)

Downloading via C#

Below is sample code written in C# that will download files.

There is also a last modified check method that can be used to see if a new file has been uploaded using the file header - without downloading the full file. This is useful if you quickly want to check every hour if a file is new compared to any you may have.

C# Sample

Validity

Associations and schedule validities are between a start date and an end date, and on particular days of the week. They each have a Short Term Planning (STP) indicator field as follows:

  • C - Planned cancellation: the schedule does not apply on this date, and the train will not run. Typically seen on public holidays when an alternate schedule applies, or on Christmas Day.
  • N - STP schedule: similar to a permanent schedule, but planned through the Short Term Planning process and not capable of being overlaid
  • O - Overlay schedule: an alteration to a permanent schedule
  • P - Permanent schedule: a schedule planned through the Long Term Planning process

Permanent ('P') schedules can be overlaid by another schedule with the same UID - either a Variation ('O') or Cancellation Variation ('C'). For any particular day, of all the schedules for that UID valid on that day, the 'C' or 'O' schedule is the one which applies. Conveniently, it also means that the lowest alphabetical STP indicator wins - 'C' and 'O' are both lower in the alphabet than 'P'.

This process allows a different schedule to be valid on particular days, or the service to not be valid on that day. For example, a schedule may be valid Monday - Friday each day of the year, but have a Cancellation Variation on Christmas Day and Boxing Day only.

Cancellation variations are usually within the validity period of the base (permanent) schedule, however it is possible to have a cancellation variation which has a 'valid from' date which is within one version of a schedule and a 'valid to' date within another version of a schedule. In this case, the variation applies to both. An example of this is schedule C33552 at the start of 2015, where a cancellation variation applied to two separate permanent schedules.


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