Live train status

Where a train is right now, how late it is, and its times at every station on the route.

GET /v1/trains/{train_number}/live

Scope live:read · Cost 1 request · Plans All plans

Returns one run of a train: its status and position, its delay, when it should reach its last station, and the scheduled, expected and actual times at every station on its route, including the ones it passes without stopping. Answers are at most 10 seconds older than the live feed, and say exactly how old they are.

Authentication

Send your key in one header: X-RailCore-Key, Authorization: Bearer or X-Api-Key. Two headers with different keys answer 401 AMBIGUOUS_API_KEY. This operation requires the live:read scope. Growth, Scale and Enterprise keys must also sign every request with HMAC-SHA256, sending X-RailCore-Timestamp, X-RailCore-Nonce and X-RailCore-Signature. Free and Starter keys send the key alone. See the authentication guide and HMAC signing.

Request parameters

NameInTypeRequiredDescription
train_numberpathstringRequiredTrain number, 4 to 6 uppercase letters or digits.
datequerystring(date)OptionalThe day the train leaves its first station, as YYYY-MM-DD in IST. A train that left late last night is still running under last night's date. Leave it out for the run on its way now (one that has left its first station and is not more than 3 hours past its booked arrival at the last; with two on the way, the one that left most recently), or else the next run to leave. journey_date in the answer says which run it is.
fromquerystringOptionalThe run's first station. Leave it out: RailCore uses the train's own first station. Needed only for a train missing from the train catalog.
toquerystringOptionalThe run's last station. Leave it out: RailCore uses the train's own last station. Needed only for a train missing from the train catalog.
max_agequeryintegerOptionalThe oldest RailCore read of this run, in seconds, you accept. 0 asks for a fresh read of the live feed.

Code examples

Base URL https://ir.railcore.tech/v1. Keep the key in an environment variable and call from a trusted server-side environment.

cURL

RUN_DATE=$(TZ=Asia/Kolkata date +%F)

curl -sS -X GET \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  "https://ir.railcore.tech/v1/trains/12723/live?date=$RUN_DATE"

JavaScript

const runDate = new Intl.DateTimeFormat("en-CA", { timeZone: "Asia/Kolkata" }).format(new Date());

const response = await fetch(`https://ir.railcore.tech/v1/trains/12723/live?date=${runDate}`, {
  method: "GET",
  headers: {
    "X-RailCore-Key": process.env.RAILCORE_KEY,
  },
});

const body = await response.json();
console.log(response.status, body);

Python

import datetime
import os
import requests

run_date = datetime.datetime.now(datetime.timezone(datetime.timedelta(hours=5, minutes=30))).date().isoformat()

response = requests.request(
    "GET",
    f"https://ir.railcore.tech/v1/trains/12723/live?date={run_date}",
    headers={"X-RailCore-Key": os.environ["RAILCORE_KEY"]},
    timeout=20,
)
print(response.status_code, response.json())

Rate limits and cost

This operation counts as 1 request and is available on all plans. Failed requests are free. Per-minute budgets, daily caps and the headers reporting what is left are in rate limits; plans and prices are in requests and billing.

Response fields

FieldTypeDescription
train_number / train_namestringThe train and its published name.
journey_datestring(date)The day the run left, or leaves, its first station: the date you asked for, or, without date, the run RailCore picked.
source_station_code / destination_station_codestringFirst and last station of this run.
train_type / train_type_labelstringThe train's category code, such as SF or RAJDHANI, and its readable label, such as superfast: the live feed's, else RailCore's train catalog's. Left out only for a train the catalog does not have.
travel_classesstring[]Classes the train carries, such as 3A and SL: the live feed's, else the train catalog's.
scheduled_duration_minutesintegerTimetabled time from first to last station.
started_at / start_datestringWhen the train actually left its first station, and that date as the live feed gives it. started_at is left out before it leaves.
statusstringWhere the run stands. CANCELLED means the whole run is cancelled; a train cancelled for only part of its route stays RUNNING or AT_STATION and the part is in cancellation.
status_textstringA ready-to-show line, for example Running 22 minutes late.
current_station_code / current_station_namestringThe station the train is at, or the last one it passed. Names are written as the RailCore site writes them (New Delhi, Mumbai Central), not the upper-case booking names.
previous_station_code / next_station_codestringThe booked halts behind and ahead of the train.
previous_station_namestringThe name of the halt behind the train, written as the RailCore site writes it. Left out when the live feed names none.
approaching_station_code / approaching_station_namestringThe next station on the line ahead, even one the train will pass without stopping.
distance_from_current_station_km / distance_to_approaching_station_kmnumberHow far the train is past the current station and short of the approaching one. Left out when the position is not precise enough.
latitude / longitudenumberThe train's last reported position.
position_anchor_station_codestringThe station the live feed measured the position from. It can trail current_station_code by a station or two.
progress_percentnumberShare of the route covered, from 0 to 100.
distance_covered_km / total_distance_kmnumberDistance covered so far, and the length of the route.
speed_kmphnumberRailCore's own estimate, not a locomotive reading: the speed where the train was last reported, from its coaches and type, the timetable and how it has run, never above what the train may run at and lower as it leaves a halt or nears the next. The estimate is rounded to 5 km/h and the figure moves within 5 km/h of it every 2 seconds, the same for every caller at the same moment, so a train that keeps running reads like a moving one. 0 while it stands at a station, before it starts and after it ends. Left out only when speed_basis is unavailable.
speed_basisstringHow speed_kmph was worked out: estimated while the train runs, stationary for 0, unavailable when the report is over 15 minutes old or does not place the train on its route.
delay_minutesintegerHow late the train is at the last station it reached. Negative when early.
eta_destination_atstringExpected arrival at the last station; the actual time once the run is complete. Left out for a cancelled run.
rescheduled_minutesintegerHow far the railway moved the run's start, in minutes. 0 when the start was not moved.
cancellationobjectWhether the run is cancelled. Always an object: read its status.
cancellation.statusstringNOT_CANCELLED when nothing is cancelled, PARTIALLY_CANCELLED when a section does not run, CANCELLED for the whole run.
cancellation.fully_cancelled / messageboolean / stringTrue only when the whole run is cancelled, and the same in words, for example No cancellation reported for this run.
cancellation.from_station_code / to_station_codestringThe section that does not run, on a part cancellation. Left out when nothing is cancelled.
official_noticeobjectWhat the railway's own running status says differs from the timetable: reason and message, new first or last station, new departure or arrival time, and whether the train is diverted. Present only when the railway reports a difference.
next_stopobjectThe next station the train halts at, with the same fields as a stations[] entry. Left out once there is none.
stations[]object[]Every station on the route in order, including the ones the train passes without stopping.
stations[].sequence / station_code / station_nameinteger / stringPosition on the route, from 1, and the station. The name is written as the RailCore site writes it (New Delhi), not the upper-case booking name.
stations[].notesobjectAt the first and last stations only, in place of the time the train does not have there: notes.arrival at the ORIGIN (Starts at Hyderabad Deccan: departs only, no arrival), notes.departure at the DESTINATION (Ends at New Delhi: arrives only, no departure).
stations[].stop_typestringWhat the station is to this run. ORIGIN is where the run starts, so it has no arrival fields; DESTINATION is where it ends, so it has no departure fields. PASSING is a station the train runs through: it has booked times and a worked-out time, but no platform.
stations[].scheduled_arrival / scheduled_departurestringTimetabled times. At a passing station, the booked time the train runs through. The ORIGIN has no scheduled_arrival and the DESTINATION no scheduled_departure.
stations[].eta / etdstringWhen the train reaches and leaves the station: the expected times while it is ahead, the actual times once the train has been there. Every station has both except the ORIGIN, which has no eta, and the DESTINATION, which has no etd; timing_basis says where they come from.
stations[].timing_basisstringWhere eta and etd come from. reported: the train was reported at the station. predicted: the live feed's forecast. estimated: RailCore worked at least one of the two out from the delay at the timed stations either side, because the feed times halts only and not always both ends of one. scheduled: nothing on the run is timed yet, so the booked time stands. cancelled: the run is cancelled, and the station has no eta, etd or delay.
stations[].actual_arrival / actual_departurestringReported arrival and departure. Each is present once the train has been reported arriving or leaving there; never actual_arrival at the ORIGIN or actual_departure at the DESTINATION.
stations[].delay_arrival_minutes / delay_departure_minutesintegerMinutes late arriving and leaving: eta and etd against the booked times. Negative when early. Left out with eta at the ORIGIN and with etd at the DESTINATION.
stations[].platform_numberstringExpected platform. Platforms can change at short notice. Left out where none is named, and at a station the train runs through.
stations[].halt_minutes / day / distance_kminteger | numberBooked halt in minutes, day of the run (1 is the day it starts), and distance from the first station in km.
stations[].is_stopping / is_divertedbooleanWhether the train halts here, and whether the station is on a diversion rather than the booked route.
stations[].has_arrived / has_departed / travelledbooleanWhether the train has reached, left and covered this station.
stations[].latitude / longitude / last_reported_atnumber | stringThe station's position, and when the train was last reported there (present once it has been).
last_reported_atstringWhen the live feed last reported this train. Left out before the run has been reported.
freshnessobjectHow fresh this answer is, in the fields below.
confidencestringHow far to trust the answer, from its age and source. A finished run whose arrival at its last station was reported is high. The X-RailCore-Confidence header says the same.
freshness.state / age_secondsstring / integerThe report's age in seconds, and the state that age puts it in.
freshness.retrieved_at / last_reported_atstringWhen RailCore read the live feed, and the report time it got back.
freshness.railcore_cachestringbypassed when this request read the live feed; reused when RailCore answered from its own read of the same run made within max_age seconds, at freshness.retrieved_at.
freshness.upstream_served_from_cachebooleanTrue when the live feed said it answered from its own cache. Present only when the feed says; it is usually left out.

Example response

{
  "success": true,
  "data": {
    "train_number": "12723",
    "train_name": "Telangana Express",
    "journey_date": "2026-11-20",
    "train_type": "SF",
    "train_type_label": "superfast",
    "travel_classes": [
      "1A",
      "2A",
      "3A",
      "SL",
      "GS"
    ],
    "source_station_code": "HYB",
    "destination_station_code": "NDLS",
    "start_date": "2026-11-20",
    "started_at": "2026-11-20T06:43:14+05:30",
    "scheduled_duration_minutes": 1560,
    "status": "RUNNING",
    "status_text": "Running 23 minutes late",
    "cancellation": {
      "status": "NOT_CANCELLED",
      "fully_cancelled": false,
      "message": "No cancellation reported for this run"
    },
    "current_station_code": "MKDI",
    "current_station_name": "Makudi",
    "previous_station_code": "SKZR",
    "previous_station_name": "Sirpur Kaghaznagar",
    "next_station_code": "BPQ",
    "approaching_station_code": "WIRR",
    "approaching_station_name": "Wirur",
    "position_anchor_station_code": "MKDI",
    "distance_from_current_station_km": 1.4,
    "distance_to_approaching_station_km": 11.5,
    "latitude": 19.551,
    "longitude": 79.476,
    "progress_percent": 20.04,
    "distance_covered_km": 335.7,
    "total_distance_km": 1675,
    "speed_kmph": 107,
    "speed_basis": "estimated",
    "delay_minutes": 23,
    "eta_destination_at": "2026-11-21T08:07:00+05:30",
    "rescheduled_minutes": 0,
    "last_reported_at": "2026-11-20T11:34:11+05:30",
    "confidence": "high",
    "next_stop": {
      "sequence": 65,
      "station_code": "BPQ",
      "station_name": "Balharshah",
      "stop_type": "HALT",
      "scheduled_arrival": "2026-11-20T11:55:00+05:30",
      "scheduled_departure": "2026-11-20T12:00:00+05:30",
      "eta": "2026-11-20T12:01:00+05:30",
      "etd": "2026-11-20T12:06:00+05:30",
      "delay_arrival_minutes": 6,
      "delay_departure_minutes": 6,
      "platform_number": "4",
      "halt_minutes": 5,
      "day": 1,
      "distance_km": 375,
      "is_stopping": true,
      "is_diverted": false,
      "has_arrived": false,
      "has_departed": false,
      "travelled": false,
      "latitude": 19.849,
      "longitude": 79.349,
      "timing_basis": "predicted"
    },
    "stations": [
      {
        "sequence": 1,
        "station_code": "HYB",
        "station_name": "Hyderabad Deccan",
        "stop_type": "ORIGIN",
        "notes": {
          "arrival": "Starts at Hyderabad Deccan: departs only, no arrival"
        },
        "scheduled_departure": "2026-11-20T06:00:00+05:30",
        "etd": "2026-11-20T06:43:14+05:30",
        "actual_departure": "2026-11-20T06:43:14+05:30",
        "delay_departure_minutes": 43,
        "platform_number": "5",
        "halt_minutes": 0,
        "day": 1,
        "distance_km": 0,
        "is_stopping": true,
        "is_diverted": false,
        "has_arrived": true,
        "has_departed": true,
        "travelled": true,
        "latitude": 17.393,
        "longitude": 78.467,
        "last_reported_at": "2026-11-20T06:43:14+05:30",
        "timing_basis": "reported"
      },
      {
        "sequence": 2,
        "station_code": "LKPL",
        "station_name": "Lakdi Ka Pul",
        "stop_type": "PASSING",
        "scheduled_arrival": "2026-11-20T06:03:00+05:30",
        "scheduled_departure": "2026-11-20T06:03:00+05:30",
        "eta": "2026-11-20T06:46:10+05:30",
        "etd": "2026-11-20T06:46:10+05:30",
        "delay_arrival_minutes": 43,
        "delay_departure_minutes": 43,
        "halt_minutes": 0,
        "day": 1,
        "distance_km": 1.4,
        "is_stopping": false,
        "is_diverted": false,
        "has_arrived": true,
        "has_departed": true,
        "travelled": true,
        "latitude": 17.404,
        "longitude": 78.464,
        "timing_basis": "estimated"
      },
      {
        "sequence": 56,
        "station_code": "SKZR",
        "station_name": "Sirpur Kaghaznagar",
        "stop_type": "HALT",
        "scheduled_arrival": "2026-11-20T10:39:00+05:30",
        "scheduled_departure": "2026-11-20T10:40:00+05:30",
        "eta": "2026-11-20T11:13:18+05:30",
        "etd": "2026-11-20T11:17:07+05:30",
        "actual_arrival": "2026-11-20T11:13:18+05:30",
        "actual_departure": "2026-11-20T11:17:07+05:30",
        "delay_arrival_minutes": 34,
        "delay_departure_minutes": 37,
        "platform_number": "1",
        "halt_minutes": 1,
        "day": 1,
        "distance_km": 305,
        "is_stopping": true,
        "is_diverted": false,
        "has_arrived": true,
        "has_departed": true,
        "travelled": true,
        "latitude": 19.346,
        "longitude": 79.489,
        "last_reported_at": "2026-11-20T11:17:07+05:30",
        "timing_basis": "reported"
      },
      {
        "sequence": 65,
        "station_code": "BPQ",
        "station_name": "Balharshah",
        "stop_type": "HALT",
        "scheduled_arrival": "2026-11-20T11:55:00+05:30",
        "scheduled_departure": "2026-11-20T12:00:00+05:30",
        "eta": "2026-11-20T12:01:00+05:30",
        "etd": "2026-11-20T12:06:00+05:30",
        "delay_arrival_minutes": 6,
        "delay_departure_minutes": 6,
        "platform_number": "4",
        "halt_minutes": 5,
        "day": 1,
        "distance_km": 375,
        "is_stopping": true,
        "is_diverted": false,
        "has_arrived": false,
        "has_departed": false,
        "travelled": false,
        "latitude": 19.849,
        "longitude": 79.349,
        "timing_basis": "predicted"
      },
      {
        "sequence": 150,
        "station_code": "NDLS",
        "station_name": "New Delhi",
        "stop_type": "DESTINATION",
        "notes": {
          "departure": "Ends at New Delhi: arrives only, no departure"
        },
        "scheduled_arrival": "2026-11-21T07:45:00+05:30",
        "eta": "2026-11-21T08:07:00+05:30",
        "delay_arrival_minutes": 22,
        "halt_minutes": 0,
        "day": 2,
        "distance_km": 1675,
        "is_stopping": true,
        "is_diverted": false,
        "has_arrived": false,
        "has_departed": false,
        "travelled": false,
        "latitude": 28.643,
        "longitude": 77.219,
        "timing_basis": "predicted"
      }
    ],
    "freshness": {
      "state": "fresh",
      "age_seconds": 13,
      "retrieved_at": "2026-11-20T11:34:24+05:30",
      "last_reported_at": "2026-11-20T11:34:11+05:30",
      "railcore_cache": "bypassed"
    }
  },
  "meta": {
    "api_version": "v1",
    "request_id": "req_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "trace_id": "trc_01J5Z7Y8N2K4M6P8R0T2V4X6Z9",
    "timestamp": "2026-11-20T10:57:05.605Z",
    "freshness": {
      "mode": "live",
      "retrieved_at": "2026-11-20T10:57:05.605Z",
      "sources": [
        {
          "confidence": "high"
        }
      ]
    }
  }
}

Errors

StatusCodeDescriptionRetry
400VALIDATION_ERRORdate is not a real date, a station code is malformed, or the train is missing from the train catalog and from and to were not passed. error.details[].field names the parameter.Not retryable
404NOT_FOUNDThe train has no run on that date, for example a weekly train on a day it does not run.Not retryable
503UPSTREAM_UNAVAILABLEThe live feed could not answer for this run. Wait for Retry-After, then retry with backoff.Retryable
401MISSING_API_KEYNo key in X-RailCore-Key, Authorization: Bearer or X-Api-Key, or the key is too short.Not retryable
401INVALID_API_KEYThe key is unknown or revoked. A disabled or expired key answers API_KEY_DISABLED or API_KEY_EXPIRED.Not retryable
401AMBIGUOUS_API_KEYMore than one key header was sent, with different keys. Send the key in one header.Not retryable
401SIGNATURE_INVALIDHMAC signature missing or not verified. Growth, Scale and Enterprise keys must sign every request; a key with no signing secret must be rotated.Not retryable
403SCOPE_MISSINGThe key lacks this operation's scope.Not retryable
403PLAN_ENDPOINT_DISABLEDThe account's plan does not include this endpoint.Not retryable
402CREDITS_EXHAUSTEDThe month's requests are used up, or too few are left for this request. Nothing is fetched.Not retryable
429RATE_LIMITEDThe account's per-minute budget, or a Free account's daily budget, is used up. Every key on the account shares it. Honor Retry-After.Retryable
410API_VERSION_SUNSETThis API version has reached its announced sunset date. Migrate to a supported major version.Not retryable
503UPSTREAM_TIMEOUTThe live-data request ran past its deadline. Wait for Retry-After, then retry with backoff. Not counted.Retryable
503METERING_UNAVAILABLEThe request could not be counted, so no data was returned. Retry with backoff.Retryable

Implementation notes

Related Trains endpoints

All RailCore Indian Railways API endpoints · Quickstart · Rate limits

Last updated