Complex Mode

Complex Mode

Introduction

Summary

• Grants full, unrestricted access to all available API data
• No restrictions on the data you can query
• Data is returned in raw JSON format without any additional formatting
• Best suited for advanced users familiar with .json files and looking for complete control over the data
• Use complexity="complex"

Complex mode offers complete and unrestricted access to all data available through the API, making it the ultimate choice for users who need full control over the information they retrieve. Unlike simple mode, complex mode imposes no restrictions on the type or range of data you can access, giving you the freedom to explore every aspect of the API's capabilities.

One key difference in complex mode is that the data is provided in its raw form as a new JSON file. This means no additional formatting or processing is applied to make the data human-readable. While this offers maximum flexibility and detail, it requires you to be familiar with JSON files and how to handle or process them effectively.

This mode is highly recommended for advanced users such as developers, data analysts, or railway enthusiasts with experience working with raw data structures. It’s the perfect option for building custom tools, integrating with advanced systems, or performing in-depth analysis where formatted data might be too restrictive.

Ensure you read through all documentation before you start using complex mode.

For those who appreciate the full complexity of the railway data ecosystem and are comfortable navigating JSON files, Complex Mode delivers the ultimate "nerdy train stuff" experience. Just be prepared to handle the raw data and craft your workflows to extract the insights you need!

To use complex mode, use complexity="complex" in your initialising code.

---

Using Complex Mode

Complex mode offers you complete unrestricted access to the Realtime Trains API. However, it is not recommended for anyone with a limited understanding of Python and json files. Before you start using this mode, it is recommended that you understand how to use them, otherwise you may not reap all the benefits complex mode offers you.

Firstly, start by creating a new python file, with a name of your choice.

To initialise complex mode, you need to assign your complexity as "complex", as shown below:

from realtime_trains_py import RealtimeTrainsPy

rtt = RealtimeTrainsPy(
    request_token="<YOUR_REQUEST_TOKEN>"
    complexity="complex"
)

Caution

Keep your request token private.

Once you've done this, you can run your file to make sure you don't run into any errors. If you run into any errors, check out the errors page to find a solution to them.

When you run complex mode for the first time, you'll see a new folder appear called realtime_trains_py_data. Don't worry though - this is intentional. The package saves all your API requests in this folder, giving you easy access to your data.

If you prefer, you can create this folder manually before running your file. The folder will be generated in the same directory where your code is executed. For example, if you're working in a project folder using VS Code, the folder will appear in your Explorer panel within that directory.

If your code is error-free, the next step is to start running commands. You don't need to assign any variables to your commands with complex mode as all the data you request will automatically get added to a new .json file. realtime-trains-py does not handle any data for you - it does, however, format the .json for you. To use the data provided to its full extent, you'll need to create your own program.

The reason realtime-trains-py don't handle this data for you is to allow you to get unrestricted access to everything the Realtime Trains API has to offer you. For easier access to the data, use simple mode.

The line of code below will create a new .json file called G54071_on_2024-11-16_service_data.json.

get_service(service_uid="G54071", date="2024-11-16")

If you don't specify a date, the date today will be used. For example, if you run:

get_service(service_uid="G54071")

On 22/11/2024, you'll get the service data for G54071 on 22/11/2024 and your file will be called G54071_on_2024-11-22_service_data.json.

The same goes for using get_departures. For example:

get_departures(tiploc="PBRO", date="2024-11-16")

Before running the command, make sure there isn't already a file with the same name in the destination directory. Running the command creates a new .json file named PBRO_on_2024-11-16_board_data.json. Because duplicate filenames are not allowed, the command will fail with a file write error if a file with that name already exists.

For example, if PBRO_on_2024-11-16_board_data.json is already present, you won't be able to run:

get_departures(tiploc="PBRO", date="2024-11-16")

until you either delete the existing file or rename it.

This behaviour is intentional. Since realtime-trains-py can't determine whether you want to keep or overwrite an existing file, it prevents accidental data loss by refusing to overwrite files automatically.

More advanced file management options may be added in a future release.

Check out the more detailed documentation here.

Running get_service or get_departures with complex mode will create a new, formatted .json file in the realtime_trains_py_data folder with the response from the API.

get_live and watch_service are meant to represent real life station boards, so your complexity choice is ignored. It doesn't format differently for each complexity.