Railtime API Documentation
Getting started
The Railtime API is largely self-explanatory, and with this documentation support, you will be up and running in no time. Use the menu to navigate to the functionality you want to use and implement, and we will provide you with the right documentation to help you on your way.
Base url:
The baseurl for all requests:https://railtime.io
API versions available:
1.0
To get started, you must obtain an API key, which is required to use railtime.io. When you register we will give you an API key that must accompany each API call you make. There are a variety of headers that must be set, depending on the request.
GET DELETE
X-Railtime-Api-Secret: [YOUR-API-KEY] X-Railtime-Version: [API-VERSION]
POST
Content-Type: application/json; charset=utf-8 X-Railtime-Api-Secret: [YOUR-API-KEY] X-Railtime-Version: [API-VERSION]
Search endpoints
Railtime provides a seamless way to search for railway stations and retrieve comprehensive information about them. Our API features multiple endpoints, allowing you to access data based on your specific requirements and available inputs.
Returns
200
This endpoint returns a list of up to 20 railway stations that match the search criteria by name, with a score op 40 or higher. The score indicates the degree of match based on the structure of the station names.
Request
The name of the station to search
Example: 'berlin'
#response
HTTP/2.0 200 OK
[
{
"score": 100,
"station": {
"uicCode": "8033452",
"sncfuicCode": "80334524",
"sncfCode": "DEHBF",
"dbCode": "8011160",
"obbCode": "8011160",
"renfeCode": "",
"atocCode": "",
"amtrakCode": null,
"name": "Berlin Hbf",
"countryCode": "DE",
"geoData": {
"latitude": "52.525589",
"longitude": "13.369548"
},
"isMainStation": true,
"isAirport": false
}
},
...
]
Returns
200 404
These endpoints provide an overview of a single railway station, selectively enriched with food, drinks, and travel-related points of interest (POIs) within the vicinity, sourced from OpenStreetMap.
Request
[station name]
The fully qualified station name of the requested railway station
Example: 'berlin hbf'
[uiccode]
The uiccode of the requested railway station
Example: '8033452'
#response
HTTP/2.0 200 OK
{
"station": {
"uicCode": "8033452",
"sncfuicCode": "80334524",
"sncfCode": "DEHBF",
"dbCode": "8011160",
"obbCode": "8011160",
"renfeCode": "",
"atocCode": "",
"amtrack": null,
"name": "Berlin Hbf",
"geoData": {
"countryCode": "DE",
"latitude": "52.525589",
"longitude": "13.369548"
},
"isAirport": false
},
"nearby": [
{
"name": "Burger King",
"type": "fast_food",
"category": "Food & drinks",
"geoData": {
"countryCode": "DE",
"latitude": "52.525589",
"longitude": "13.369548"
}
},
...
]
}
Subscription endpoints
To receive real-time information about a direct train connection, you can subscribe by providing the departure station, date, and time, as well as the arrival station, date, and time. Each change detected by Railtime will be sent to the endpoint that is provided in the subscription.
Active monitoring of a direct train connection will begin 12 hours before the scheduled departure date and time.
Note: This service only supports existing train routes with direct connections and does not support trips with stopovers. If your trip includes stopovers, you need to subscribe seperately for each direct connection.
Returns
202 400
Request
CodeQualifier
At this moment we only support UICCodes
string, example: 'UICCode'
DepartureCode
ArrivalCode
UICCode of the station
string, example: '8400530'
ScheduledDepartureDateTime
ScheduledArrivalDateTime
The scheduled local departure or arrival date and time according the original
timetable
datetime(yyyy-MM-dd'T'HH:mm z), example: '2024-02-09T15:35:00+01:00'
ReplyAddress
The endpoint on your side where we deliver the changes. This endpoint must
accept POST requests in json format and should be able to receive the POST change model
Note: We do not support any authentication at this time
string, example: 'https://your-endpoint.io'
ExternalIdentifier optional
A free format identifier for you to provide. This identifier will be included in the changes payload
string, example: 'RTM-AMS Demo Trip'
Response
POST change model; delivered to your API
TimeStamp
When the change has been send out
datetime(yyyy-MM-dd'T'HH:mm z), example: '2024-02-09T15:35:00+01:00'
ChangeTypes
Current changes that can be expected (when available):
STATUS, DEPARTURETIME,
DEPARTUREPLATFORM, ARRIVALTIME, ARRIVALPLATFORM, TRAINNUMBER
string[], example: '[ "STATUS", "TRAINNUMBER" ]'
DepartureUICCode
ArrivalUICCode
UICCode of the station
string, example: '8400530'
Scheduled
The scheduled scheme of the direct train connection, based on the original timetable
Compare model
Actual
The actual scheme of the direct train connection
Compare model
Appendix
An attachment with common data that could be of value for the update. At this point we only support railway stations
Custom model
Sources
The sources that are used to detect the differences in the data
string[], example: '[ "NS", "DB" ]'
External
A set of properties that can be provided upon subscription
Currently this will only hold the 'Identifier' property.
#request
{
"CodeQualifier": "UICCode",
"DepartureCode": "8400530",
"ScheduledDepartureDateTime": "2024-02-09T15:35:00+01:00",
"ArrivalCode": "8400058",
"ScheduledArrivalDateTime": "2024-02-09T16:15:00+01:00",
"ReplyAddress": "https://your-endpoint.io",
"ExternalIdentifier": "RTM-AMS Demo Trip",
}
#response
HTTP/2.0 202 Accepted
"8400530|8400058|202402090915"
#POST change model; delivered to your API
{
"Key": "8400530|8400058|202402090915",
"TimeStamp": "2024-02-09T13:58:25.3598011+01:00",
"ChangeTypes": [
"STATUS",
"TRAINNUMBER",
"DEPARTUREPLATFORM",
"ARRIVALPLATFORM"
],
"DepartureUICCode": "8400530",
"ArrivalUICCode": "8400058",
"Scheduled": {
"DepartureDateTime": "2024-02-09T15:35:00+01:00",
"DeparturePlatform": null,
"ArrivalDateTime": "2024-02-09T16:15:00+01:00",
"ArrivalPlatform": null,
"TripDetails": {
"Status": "SCHEDULED",
"TrainNumber": null,
"DurationInMinutes": 40
}
},
"Actual": {
"DepartureDateTime": "2024-02-09T15:35:00+01:00",
"DeparturePlatform": "13",
"ArrivalDateTime": "2024-02-09T16:15:00+01:00",
"ArrivalPlatform": "11",
"TripDetails": {
"Status": "ONTIME",
"TrainNumber": "9126",
"DurationInMinutes": 40
}
},
"Appendix": {
"Stations": [
{
"Name": "Rotterdam Centraal",
"References": {
"UICCode": "8400530",
"SNCFUICCode": "84005306",
"SNCFCode": "NLRTA",
"DBCode": "8400530",
"OBBCode": "8400530",
"RenfeCode": "8400530"
},
"Location": {
"CountryCode": "NL",
"Latitude": "51.925068244603146",
"Longitude": "4.468839168548584"
},
"Miscellaneous": {
"IsMainStation": true,
"IsAirport": false
}
},
{
"Name": "Amsterdam-Centraal",
"References": {
"UICCode": "8400058",
"SNCFUICCode": "84000588",
"SNCFCode": "NLAMA",
"DBCode": "8400058",
"OBBCode": "8400058",
"RenfeCode": "8400058"
},
"Location": {
"CountryCode": "NL",
"Latitude": "52.37919",
"Longitude": "4.899426"
},
"Miscellaneous": {
"IsMainStation": true,
"IsAirport": false
}
}
]
},
"Sources": [
"NS"
],
"External": {
"Identifier": "RTM-AMS Demo Trip"
}
}
Returns
202 404
Request
The key that is given upon subscribe
Example: '8400530|8400058|202402090915'
#response
HTTP/2.0 202 Accepted
Release notes
2025-03-13
- Railtime API: Added a new validation rule to ensure that the DepartureCode and ArrivalCode are distinct.
2024-08-01
- Railtime API: match endpoint: Optimized search algorithm.
- Railtime API: match endpoint: Eliminated duplicate stations in resultset.
2024-07-18
- Railtime API: Fixed bug when providing a + sign in the search and match endpoints.
- Railtime API: Added the subscription key to the changes payload, found by name Key.
- Railtime API: Added support for the ExternalIdentifier property to the subscription request payload.
This key is flexible and can be chosen by you. It has multiple use cases, such as providing a key for grouping different
legs of a train trip when you need to subscribe for each segment separately.
2024-06-15
- Railtime API: Improved handling of errors related to incorrect date and time formats. Now, instead of just returning an HTTP 400 status code with an empty response, the system also provides a validation message that explains the issue.
- Documentation: Added release notes page.