Complexities:

The realtime-trains-py package uses a simple single-character and triple-character system to specify the complexity level for processing and returning the data you request. This system allows you to choose how detailed or raw you want the data to be, based on your needs and expertise. Each complexity level is tailored to a specific use case and is explained in detail below.

Please read through this documentation to understand the differences between the levels and select the one that best fits your requirements.

[!TIP] Complexity selections aren't case-sensitive. We use lowercase in our examples.

Simple Mode

Summary

• Provides easy-to-read data.
• Ideal for users who prefer straightforward and clear information without delving into technical details.
• Recommended for beginners or casual users who want essential train data presented in an accessible format.
• Complexity defaults to simple if left blank.

Simple Mode offers a streamlined way to access key data from the API, making it perfect for those who want straightforward, easy-to-read information without diving into complex technical details.

With Simple Mode, you can access train data from any date. It is recommended that you only request data up to 7 days before the current date and 80 days after the current date. This ensures you have a manageable amount of data to work with, focusing only on what’s relevant for recent and near-future train schedules.

One of the key features of Simple Mode is its user-friendly formatting. Any data retrieved through this mode is automatically organized and displayed in a clear, readable format. This removes the need for additional processing or interpretation, making it accessible to users of all technical skill levels.

We recommend Simple Mode for users who are looking for a clean and straightforward experience, without delving into the intricate, technical details of train operations, such as headcodes, working timetable schedule data, or engineering-specific information. Whether you're tracking trains for personal use, casual research, or planning purposes, this mode provides all the essential information without overwhelming you with the "nerdy train stuff."

Simple Mode is ideal for beginners, casual users, or anyone who values simplicity and ease of use over technical depth.

To use simple mode, you can use complexity="s" in your initialising code. However you don't have to do this as complexity defaults to simple if left blank.

[!TIP] Simple mode also comes with the addition of "prettier" and "normal" formatting options. You can use complexity="s.p" or complexity="s.n" respectively. The default mode when using complexity="s" is prettier.

This feature only changes your formatting settings and makes things easier for you to read. Learn more.

Advanced Mode

Summary

• Offers more detailed data compared to Simple Mode.
• Provides richer insights into train schedules and operations for users who want more technical depth.
• Great for railway enthusiasts and developers interested in exploring the "nerdy train stuff."
• Use complexity="a".

Advanced Mode unlocks access to the majority of the data offered by the API, providing a more comprehensive view of the information available. Like Simple Mode, Advanced Mode allows you to access train data from any date. It is recommended that you only request data up to 7 days before the current date and 80 days after the current date. However, the key difference lies in the level of detail and breadth of data provided.

In this mode, you gain insights into more intricate aspects of train operations, including headcodes, working timetable schedule data, or engineering-specific information along with other technical data. While the data is still formatted for readability, it retains a higher level of granularity compared to Simple Mode, making it suitable for users who enjoy exploring the finer points of railway systems.

We recommend Advanced Mode for users who are comfortable with—or curious about—the "nerdy train stuff." This mode is perfect for railway enthusiasts, developers working on custom applications, or analysts looking to dive deeper into operational details.

Advanced Mode delivers a more immersive experience by providing richer, more detailed information. Whether you're building a project, conducting research, or just have a passion for railways, Advanced Mode gives you the tools to explore train data at a deeper level.

To use advanced mode use complexity="a" in your initialising code.

[!TIP] Like Simple mode, Advanced mode also comes with the addition of "prettier" and "normal" formatting options. You can use complexity="a.p" or complexity="a.n" respectively. The default mode when using complexity="a" is prettier.

This feature only changes your formatting settings and makes things easier for you to read.

Complex Mode

Summary

• Grants full, unrestricted access to all available API data.
• No time 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".

Read the documentation.

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.

Like 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 the separate documentation for complex mode before you start using it.

Complex mode also ignores some data provided in the queries. For example, the rows field will be ignored.

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 own workflows to extract the insights you need!

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