Documentation - realtime-trains-lang/realtime-trains-py GitHub Wiki

Documentation

Contents

Get Departures

Get Arrivals

Get Station

Get Service

Get Live

Get Departures

The get_departures method takes between 1 and 5 arguments. These are:

  • tiploc (Timing point location code) (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 and the rows will default to the number of rows returned by the API. rows will be ignored if you're using complex mode.

The time you pass into the function should be a string 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 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(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) code. However, it is recommended that you use the TIPLOC codes 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(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

Similar to get_departures, the get_arrivals method takes between 1 and 5 arguments. These are:

  • tiploc (Timing point location code) (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 and the rows will default to the number of rows returned by the API. rows will be ignored if you're using complex mode.

The time you pass into the function should be a string 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 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(tiploc="STEVNGE", filter="KNGX", date="2024/11/16", time="1250", rows=20)

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

[!TIP]

In the tiploc and filter fields, station CRS (Computer Reservation System) codes can be provided instead of a TIPLOC (Timing Point Location) code. However, it is recommended that you use the TIPLOC codes 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 arrival 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_arrival -- (The arrival time of the service according to the timetable)
  • x.terminus -- (The terminus of the service)
  • x.origin -- (The origin of the service)
  • x.platform -- (The platform the service will depart from)
  • x.realtime_arrival -- (The expected arrival 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:

arrivals = get_arrivals(tiploc="STEVNGE", filter="KNGX")

for service in arrivals:
    print(service.terminus)

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

London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross

Get Station

The get_station method is a combination of get_departures and get_arrivals, so similarly takes between 1 and 5 arguments.

  • tiploc (Timing point location code) (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 and the rows will default to the number of rows returned by the API. rows will be ignored if you're using complex mode.

Rows

Rows is the maximum number of rows to return. The API may return twice the number of rows requested, so if you want 10 rows, you should set rows to 5. This is because the API returns both departures and arrivals.

If you set rows to 10, the API will return up to 10 departures and 10 arrivals. These are then sorted and combined into a single list, so you may not actually receive 20 rows of data.

TIme

The time you pass into the function should be a string 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 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(tiploc="STEVNGE", filter="KNGX", date="2024/11/16", time="1250", rows=20)

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

[!TIP]

In the tiploc and filter fields, station CRS (Computer Reservation System) codes can be provided instead of a TIPLOC (Timing Point Location) code. However, it is recommended that you use the TIPLOC codes 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 and arrival 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_arrival -- (The arrival time of the service according to the timetable)
  • x.gbtt_departure -- (The arrival time of the service according to the timetable)
  • x.terminus -- (The terminus of the service)
  • x.origin -- (The origin of the service)
  • x.platform -- (The platform the service will depart from)
  • x.realtime_arrival -- (The expected arrival of the service)
  • 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:

station = get_station(tiploc="STEVNGE", filter="KNGX")

for service in station:
    print(service.terminus)

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

London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross
London Kings Cross

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 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.

Data Extraction

To get service 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.train_id -- (The ID of the train)
  • x.service_uid -- (The Unique ID of the service)
  • x.operator -- (The operator of the service)
  • x.origin -- (The origin of the service)
  • x.destination -- (The destination of the service)
  • x.calling_points -- (A list of calling point objects. Should iterate through these too.)
    • x.stop_name -- (The name of this stop)
    • x.booked_arrival -- (The arrival time of the service according to the timetable)
    • x.realtime_arrival -- (The expected arrival of the service)
    • x.platform -- (The platform the service will depart from)
    • x.line -- (The line the train will be taking) [Only available for advanced mode]
    • x.booked_departure -- (The departure time of the service according to the timetable)
    • x.realtime_departure -- (The expected departure of the service)
  • x.start_time -- (The start time of the service according to the timetable)
  • x.end_time -- (The end time of the service according to the timetable) [Only available for advanced mode]
  • x.power -- (The power type of the service) [Only available for advanced mode]
  • x.train_class -- (The train class of the service) [Only available for advanced mode]

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

service_details = get_service(service_uid="W23502")

print(service_details.service_uid)
for service in service_details.calling_points:
    print(f"{service.stop_name}: {service.booked_arrival}")

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

W23502
Cambridge: 
Foxton: 07:05
Shepreth: 07:08
Meldreth: 07:11
Royston: 07:16
Ashwell & Morden: 07:21
Baldock: 07:26
Letchworth: 07:29
Hitchin: 07:33
Stevenage: 07:39
Knebworth: 07:43
Welwyn North: 07:46
Welwyn Garden City: 07:50
Hatfield: 07:55
Potters Bar: 08:00
Alexandra Palace: 08:09
Finsbury Park: 08:14
London Kings Cross: 08:22

Get Live

[!IMPORTANT]

I'm a new BETA only feature! Report any bugs by opening an issue.

The get_live method takes 1 argument. This are:

  • tiploc (Timing point location code) (a string) - like "KNGX"

The tiploc argument is mandatory.

The get_live method displays a live departure board for the specified tiploc. The board will update every 60 seconds to prevent API overuse. This method does not change based on your selected complexity; it is meant to replicate a real life station departure board.

This method will run infinitely until there is a connection or you cancel the board by pressing Ctrl + C.

Here is one request you could provide:

get_live(tiploc="ELYY")

This request will return the live departure board for Ely.

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

Ely Live:
16:54 Stansted Airport 2 On time
Calling at: Cambridge, Stansted Airport
16:56 Kings Lynn 1 On time
17:00 Peterborough 1 On time
     16:52:30