Documentation

Documentation

Get Departures Board

The get_departures_board() method takes between 1 and 5 arguments. These are:

• tiploc (Timing location point) (a string) - like "KNGX"
• filter (a string) - like "STEVNGE"
• date (a string) - like "2024/11/16"
• time (a string) - like "1250" (12:50)
• rows (an integer) - like 15

The filter, time, date and rows arguments are all optional. If left blank, a filter will not be applied, the date and time will be defaulted to the current date and time (UTC) and the rows will default to the number of rows returned by the API. Rows cannot be specified if you're using complex mode.

The time you pass into the function should be an integer of the 24-hour time you need. For example, if you're looking for arrivals at 16:55, the time will be 1655.

The get_departures_board() method returns the departures for the station you specified. The amount of data and how it is formatted returned will depend on the complexity you specified upon initialising the package.

Here is one request you could provide:

get_departures_board(tiploc = "KNGX", filter = "STEVNGE", date = "2024/11/16", time = "1250", rows = 20)

This request will return up to 20 rows of departures for London King's Cross (KNGX) on 16/11/2024 around 12:50, provided they call at Stevenage (STEVNGE).

Tip

In the tiploc and filter fields, station CRS (Computer Reservation System) codes can be provided instead of a TIPLOC (Timing Point Location). However, it is recommended that you use the TIPLOC instead of the CRS.

A list of TIPLOC and CRS codes can be found here. This site is not managed by realtime-trains-py.

Data Extraction

To get departure data out of the objects you'll get returned you'll need to iterate through them. You can only do this if you're using advanced (normal) mode or simple (normal) mode.

Each request you make will return a list of objects, each with the following attributes:

• x.gbtt_departure -- (The departure time of the service according to the timetable)
• x.terminus -- (The terminus of the service)
• x.platform -- (The platform the service will depart from)
• x.realtime_departure -- (The expected departure of the service)
• x.service_uid -- (The Unique ID of the service)

For example, to get the terminus of each service the following code can be implemented:

departures = get_departures_board(tiploc = "KNGX", filter = "STEVNGE")

for service in departures:
    print(service.terminus)

And here's the example output for the above code:

Cambridge
Lincoln Central
Cambridge
Leeds
Cambridge
York
Cambridge
Harrogate
Cambridge
Lincoln Central
Cambridge
Bradford Forster Square
Cambridge
Peterborough
Cambridge
Harrogate

---

Get Arrivals Board

Similar to get_departures_board(), the get_arrivals_board() method takes between 1 and 5 arguments. These are:

• tiploc (Timing location point) (a string) - like "KNGX"
• filter (a string) - like "STEVNGE"
• date (a string) - like "2024/11/16"
• time (a string) - like "1250" (12:50)
• rows (an integer) - like 15

The filter, time, date and rows arguments are all optional. If left blank, a filter will not be applied, the date and time will be defaulted to the current date and time (UTC) and the rows will default to the number of rows returned by the API. Rows cannot be specified if you're using complex mode.

The time you pass into the function should be an integer of the 24-hour time you need. For example, if you're looking for arrivals at 16:55, the time will be 1655.

The get_arrivals_board() method returns the arrivals for the station you specified. The amount of data and how it is formatted returned will depend on the complexity you specified upon initialising the package.

Here is one request you could provide:

get_arrivals_board(tiploc = "KNGX", filter = "STEVNGE", date = "2024/11/16", time = "1250", rows = 20)

This request will return up to 20 rows of arrivals for London King's Cross (KNGX) on 16/11/2024 around 12:50, provided they call at Stevenage (STEVNGE).

Tip

In the tiploc and filter fields, station CRS (Computer Reservation System) codes can be provided instead of a TIPLOC (Timing Point Location). However, it is recommended that you use the TIPLOC instead of the CRS.

A list of TIPLOC and CRS codes can be found here. This site is not managed by realtime-trains-py.

---

Get Station Board

Caution

This method is not a fully working product, so may not return the desired data. This method is only available through accessing other branches on this repository.

The get_station_board() method is a combination of get_departures_board() and get_arrivals_board(), so it similarly takes between 1 and 5 arguments.

• tiploc (Timing location point) (a string) - like "KNGX"
• filter (a string) - like "STEVNGE"
• date (a string) - like "2024/11/16"
• time (a string) - like "1250" (12:50)
• rows (an integer) - like 15

The filter, time, date and rows arguments are all optional. If left blank, a filter will not be applied, the date and time will be defaulted to the current date and time (UTC) and the rows will default to the number of rows returned by the API. Rows cannot be specified if you're using complex mode.

The time you pass into the function should be an integer of the 24-hour time you need. For example, if you're looking for arrivals at 16:55, the time will be 1655.

The get_station_board() method returns the arrivals for the station you specified. The amount of data and how it is formatted returned will depend on the complexity you specified upon initialising the package.

Here is one request you could provide:

get_station_board(tiploc = "KNGX", filter = "STEVNGE", date = "2024/11/16", time = "1250", rows = 20)

This request will return up to 20 rows of arrivals and departures for London King's Cross (KNGX) on 16/11/2024 around 12:50, provided they call or called at Stevenage (STEVNGE).

Tip

In the tiploc and filter fields, station CRS (Computer Reservation System) codes can be provided instead of a TIPLOC (Timing Point Location). However, it is recommended that you use the TIPLOC instead of the CRS.

A list of TIPLOC and CRS codes can be found here. This site is not managed by realtime-trains-py.

---

Get Service

The get_service() method takes 1 or 2 arguments. These are:

• service_uid (a string) - like "G54072"
• date (a string) - like "2024/11/16" (Support for specific times will be added soon)

The date argument is optional. It will be defaulted to the current date (UTC) if left blank.

The get_service() method returns the information for the specified. The amount of data returned will depend on the complexity you specified upon initialising the package.

Here is one request you could provide:

get_service(service_uid = "G54072", date = "2024/11/16")

This request will return the service information for G54072 on 16/11/2024.

---

Errors:

Service UID not Recognised

Service UID not recognised.
Status code: 404

This error means that the Service UID you entered doesn't match any service on the server. The Service UID should be a 6-character string. It should start with one (1) letter (not case-sensitive) followed by five (5) integers. For example G54072 - which is the Service UID for 9J35. The package will return the error shown above if you provide the headcode (9J35 in this case). Due to API limitations, Service UIDs must be provided instead.

Access Blocked

Access blocked: check your credentials.
Status code: 401 | 403

This error means that the credentials you provided when you initialised the package were unable to be verified by the API server. If your credentials are correct and you are unable to access the API, you should contact the API support via the api portal. This error is unlikely to be a problem with realtime-trains-py. If you have recently registered it may take a while for your details to be verified before you can access the API. If this problem persists, visit the api portal for support. You can also report an issue with realtime-trains-py on GitHub so that we can check our systems.

Invalid Date

Date provided did not meet requirements or fall into the valid date range.

This error means that a date you provided was not accepted by the system. Your date should be provided in the form dd/mm/yyyy, and not be more than eight (8) days before the current date or more than 80 days after the current date. For example, on the 9th of January 2025 (09/01/2025), the earliest date that can be requested is the 2nd of January 2025 (02/01/2025) and the latest date is the 30th of March 2025 (30/03/2025)

Tip

Turn on complex mode to bypass this error. Complex mode allows you to access more data.

Warning

Dates requested that are more than two (2) weeks after the current date are unlikely to be representative or accurate of the timetable on that day.

Missing Details

Missing details. Both username and password must be provided. Only one field was provided.

This error means that you didn't pass in a username and a password when you initialised the package. Make sure you read the setup guide before running your code. If this problem persists and you have correctly followed the setup guide, report an issue with realtime-trains-py on GitHub so that we can check our systems.

Complexity not Recognised

Complexity not recognised. Select a valid type.

This error means that you didn't select a valid complexity type when you initialised the package. Make sure you read the setup guide before running your code. If this problem persists and you have correctly followed the setup guide, report an issue with realtime-trains-py on GitHub so that we can check our systems.