Setup

Setting up the realtime-trains-py package

Depending on how you want to run the package, there are a few things that you need to do before you can start using the package. To get help that's specific to your needs, click one of the links below to get directed to the right place.

I've forked, cloned or downloaded this repository onto my device

Forking, cloning or downloading this repository onto your device allows you to edit the code to suit your own personal needs. This also allows you to contribute to the repository by submitting a pull request. This setup option is recommended for users that have a good understanding of python.

I've installed the package using pip

Installing this package using pip is the recommended option, as pip will have the most up-to-date code and be 100% what you see on this repository. This setup option is recommended for users that do not have a good understand of python.

---

Setting up the package locally

Running the realtime-trains-py package locally will require you to implement a few things before you can start.

To start, you need to initialise the package in your file. To do this, you'll need to make a new python file: your_file.py. In this file, you'll need to import realtime_trains_py and assign RealtimeTrainsPy() to a variable of your choosing, like below.

from [tbc] import [tbc]

your_var = RealtimeTrainsPy()

When you initialise RealtimeTrainsPy(), you can provide between zero (0) and three (3) arguments. These are:

• Your complexity

• Your username

• Your password

Don't have a username or password?

Caution

Keep your username and password private.

Warning

If you would like to contribute to this project by submitting a pull request, please ensure that your local copy of the repository is thoroughly reviewed and free of any sensitive or personal information. This includes, but is not limited to, usernames, passwords, API keys, or any other credentials that might compromise your security or the integrity of the repository.

Keep in mind that all pull requests are public and can be viewed by anyone on the internet once submitted. To protect your privacy and maintain the security of your systems, double-check your code and configuration files before making any changes public.
Not all submitted pull requests will be merged onto the main branch

By following these guidelines, you help keep the project secure and maintain a professional standard for collaboration within the community. If you are unsure about the process or need assistance, feel free to check the GitHub documentation on pull requests or reach out to the repository maintainers for guidance.

---

Finally, to start using the package locally, it is recommended that you create a separate folder called tests for your code. You should start any new file you create with:

from src.main.main import RealtimeTrainsPy

your_var = RealtimeTrainsPy()

This will allow you to begin using the package. View our documentation for step-by-step guides on how to do this.

Your final step is the try running the program. If you have followed this setup guide correctly, you shouldn't receive any errors. If you receive an error, re-read the setup guide and report an issue with realtime-trains-py on GitHub so that we can check our systems.

That's all you need to know to set up the package locally on your device. Any other queries you have will likely have answers already on this wiki. If you're still unsure, head to either the discussions or issues page to check for community-created answers.

---

Setting up the package using pip

Running the realtime-trains-py package using pip will require you to implement a few things before you can start.

To start, you need to initialise the package in your file. To do this, you'll need to make a new python file: your_file.py. In this file, you'll need to import realtime_trains_py and assign RealtimeTrainsPy() to a variable of your choosing, like below.

from [tbc] import [tbc]

your_var = RealtimeTrainsPy()

When you initialise RealtimeTrainsPy(), you can provide between zero (0) and three (3) arguments. These are:

• Your complexity

• Your username

• Your password

Don't have a username or password?

Important

Make sure you provide both your username and password together, or you won't be able to access the API.

Caution

Keep your username and password private.

This will allow you to begin using the package. View our documentation for step-by-step guides on how to do this.

Your final step is the try running the program. If you have followed this setup guide correctly, you shouldn't receive any errors. If you receive an error, re-read the setup guide and report an issue with realtime-trains-py on GitHub so that we can check our systems.

That's all you need to know to set up the package using pip. Any other queries you have will likely have answers already on this wiki. If you're still unsure, head to either the discussions or issues page to check for community-created answers.

---

Complexities:

The realtime-trains-py package uses a simple single-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.

Simple Mode

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 within a limited time frame—up to seven (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.

Advanced Mode

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 query train data within a specific timeframe—up to seven (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 simple mode use complexity = "a" in your initialising code.

Complex Mode

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.

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 simple mode use complexity = "a" in your initialising code.

---

I don't have a username or password

To get a username and password, head over to the api portal and select register. Follow the appropriate steps on the site. Once logged in, you'll be directed to the API home page. This page shows you your API auth credentials - these are the details you'll use to access the API. Your username is prefixed with rttapi_ and your password will be a 40 character hex string. Copy these details and paste them into your code.

Caution

Keep your username and password private.