Complex Mode

Introduction

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 the other modes, 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 users 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.

Complex mode is not fully validated by the package and returns very vague and sometimes confusing errors. Ensure you read through this documentation before you start using it.

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="c" in your initialising code.

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="c".

---

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 "c", as shown below:

from realtime_trains_py import RealtimeTrainsPy

your_var = RealtimeTrainsPy(
    complexity="c", 
    username="your_username", 
    password="your_password"
)

[!CAUTION] Keep your username and password 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 JSON format within this folder, allowing 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 - we do format the .json for you though! To use the data provided to its full extent, you'll need to create your own program.

The reason we 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, we recommend using advanced or 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.

The same goes for getting departures or arrivals. Using get_arrivals or get_departures will allow you to do this. For example:

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

get_arrivals(tiploc="KNGX", date="2024/11/16")

Running these commands will create two new .json files called PBRO_on_2024.11.16_dep_board_data.json and KNGX_on_2024.11.16_arr_board_data.json respectively. Once they have been created, you can do whatever you wish with them. Bear in mind that you can't have two files with the same name. For example, if you already have a file called PBRO_on_2024.11.16_dep_board_data.json, you can't run get_departures(tiploc = "PBRO", date = "2024/11/16") unless you delete or rename the first file.

Support for more advanced file management may come in the future. This decision is currently not final.

As with get_service, you aren't required to specify a date or time. Check out the more detailed documentation for get_station, get_arrivals, get_departures and get_service here.

Running any command with complex mode will create a new, formatted .json file in the JSONs folder with the response from the API.