Get the rake from the front: the locomotive, then every coach, with the train's name, formation and class counts.
GET /v1/trains/{train_number}/coach-position
Scope schedule:read · Cost 1 request · Plans All plans
Returns the train's rake in order from the front, with the train's name, its first and last stations, the number of coaches, the formation written out, the coaches counted by class, and the stations where the rake reverses. A loco-hauled train's list always starts with the locomotive, and its coaches count from 2; every coach follows with its label, its class in code and in words, what kind of vehicle it is, and its place. A self-propelled set (Vande Bharat, MEMU, DEMU, EMU) has no separate locomotive, so its list starts with the first coach at position 1. A push-pull train (an Amrit Bharat Express, for one) has a locomotive at each end: its list ends with a second locomotive row, and push_pull is true. Power cars (LPR, EOG) are listed in their places, so positions run without a gap.
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 schedule: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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
train_number | path | string | Required | Train number, 4 to 6 uppercase letters or digits. |
Base URL https://ir.railcore.tech/v1. Keep the key in an environment variable and call from a trusted server-side environment.
curl -sS -X GET \
-H "X-RailCore-Key: $RAILCORE_KEY" \
"https://ir.railcore.tech/v1/trains/12656/coach-position"
const response = await fetch("https://ir.railcore.tech/v1/trains/12656/coach-position", {
method: "GET",
headers: {
"X-RailCore-Key": process.env.RAILCORE_KEY,
},
});
const body = await response.json();
console.log(response.status, body);
import os
import requests
response = requests.request(
"GET",
"https://ir.railcore.tech/v1/trains/12656/coach-position",
headers={"X-RailCore-Key": os.environ["RAILCORE_KEY"]},
timeout=20,
)
print(response.status_code, response.json())
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.
| Field | Type | Description |
|---|---|---|
train_number | string | Train number. |
train_name / train_type | string | The train's name and category code, such as SF or RAJDHANI, from RailCore's train catalog. |
source_station / destination_station | object | The train's first and last stations, each as { code, name }, with the name written out in full. |
rake_type | string | Coach build. TRAINSET for a self-propelled set. |
has_locomotive | boolean | True for a loco-hauled train, whose list starts with the locomotive. False for a self-propelled set, which has no locomotive row. |
locomotives | integer | Locomotive rows in the list: 0 for a self-propelled set, 1 for a loco-hauled train, 2 for a push-pull train. |
push_pull | boolean | True for a push-pull train: a locomotive at each end of the rake, so the list starts and ends with a locomotive row. Indian Railways publishes no list of such trains; RailCore marks one on evidence and says which in push_pull_basis. A train that is not marked may still be worked push-pull. |
push_pull_basis | string | Present when push_pull is true: what the mark rests on. train_design: the train is an Amrit Bharat Express, built as a push-pull rake. railway_announcement: the railway announced push-pull working for this train. rake_composition: the train's coach composition lists a locomotive at each end. |
composition_basis | string | Where the coach list comes from. primary: RailCore's main coach-composition source. secondary: the main source publishes no composition for this train, so the list is a second source's; it can lag a recent change to the rake, and the answer's confidence is medium. |
total_coaches | integer | Coaches in the list, not counting locomotives or power cars. |
power_cars | integer | Power cars in the list (LPR, EOG), each a row with coach_type POWER_CAR. 0 on a train with none. |
total_vehicles | integer | Every row in the list: locomotives, coaches and power cars. |
formation | string | The rake written out from the front, for example ENG-SLRD-GEN-S5-S4-PC-B1-A1-H1-GEN. |
class_summary[] | object[] | The rake counted by class, in rake order: class_code, class_name, coach_type and coaches (how many). On a loco-hauled train the first entry is the locomotive (class_code LOCO, coaches 1; 2 on a push-pull train). Power cars are counted too, so the counts add up to total_vehicles. |
reversal_stations[] | object[] | Stations where the engine changes ends, so the coach order runs the other way from there on: station_code and station_name. Empty when RailCore knows of none. |
coach_position[].sequence | integer | Row number in the list, from 1. |
coach_position[].coach_name | string | Coach label such as B1. ENG for the locomotive. |
coach_position[].class_code | string | The coach's class (a ClassCode value such as 3A, SL or GS), LOCO for the locomotive, or the vehicle's own code where it has no travel class (LPR or EOG for a power car, VP for a parcel van). |
coach_position[].class_name | string | The class or vehicle in words: Third AC, Sleeper, General (unreserved), Pantry car, Power car, Generator car, Locomotive. |
coach_position[].coach_type | string | What the vehicle is for. RESERVED is a coach whose seats or berths are booked in a class; UNRESERVED is a general coach. |
coach_position[].position_from_engine | integer | Place in the rake counted from the front. The locomotive is 1, the vehicle behind it 2. Every vehicle is listed, power cars included, so the numbers run without a gap. |
coach_position[].is_locomotive | boolean | True for a locomotive row, false for a coach. |
coach_position[].locomotive_end | string | On a locomotive row only: which end of the rake it is at. A push-pull train has one of each. |
{
"success": true,
"data": {
"train_number": "12656",
"train_name": "Navjeevan SF Express",
"train_type": "SF",
"source_station": {
"code": "MAS",
"name": "MGR Chennai Central"
},
"destination_station": {
"code": "ADI",
"name": "Ahmedabad Junction"
},
"rake_type": "LHB",
"has_locomotive": true,
"locomotives": 1,
"push_pull": false,
"composition_basis": "primary",
"total_coaches": 21,
"power_cars": 0,
"total_vehicles": 22,
"formation": "ENG-SLRD-GEN-GEN-S5-S4-S3-PC-S2-S1-M3-M2-M1-B4-B3-B2-B1-A2-A1-H1-GEN-GEN",
"class_summary": [
{
"class_code": "LOCO",
"class_name": "Locomotive",
"coach_type": "LOCOMOTIVE",
"coaches": 1
},
{
"class_code": "SLR",
"class_name": "Luggage, brake & Divyangjan van",
"coach_type": "LUGGAGE_BRAKE",
"coaches": 1
},
{
"class_code": "GS",
"class_name": "General (unreserved)",
"coach_type": "UNRESERVED",
"coaches": 4
},
{
"class_code": "SL",
"class_name": "Sleeper",
"coach_type": "RESERVED",
"coaches": 5
},
{
"class_code": "PC",
"class_name": "Pantry car",
"coach_type": "PANTRY",
"coaches": 1
},
{
"class_code": "3E",
"class_name": "AC Economy",
"coach_type": "RESERVED",
"coaches": 3
},
{
"class_code": "3A",
"class_name": "Third AC",
"coach_type": "RESERVED",
"coaches": 4
},
{
"class_code": "2A",
"class_name": "Second AC",
"coach_type": "RESERVED",
"coaches": 2
},
{
"class_code": "1A",
"class_name": "First AC",
"coach_type": "RESERVED",
"coaches": 1
}
],
"reversal_stations": [],
"coach_position": [
{
"sequence": 1,
"coach_name": "ENG",
"class_code": "LOCO",
"class_name": "Locomotive",
"coach_type": "LOCOMOTIVE",
"position_from_engine": 1,
"is_locomotive": true,
"locomotive_end": "FRONT"
},
{
"sequence": 2,
"coach_name": "SLRD",
"class_code": "SLR",
"class_name": "Luggage, brake & Divyangjan van",
"coach_type": "LUGGAGE_BRAKE",
"position_from_engine": 2,
"is_locomotive": false
},
{
"sequence": 3,
"coach_name": "GEN",
"class_code": "GS",
"class_name": "General (unreserved)",
"coach_type": "UNRESERVED",
"position_from_engine": 3,
"is_locomotive": false
},
{
"sequence": 4,
"coach_name": "GEN",
"class_code": "GS",
"class_name": "General (unreserved)",
"coach_type": "UNRESERVED",
"position_from_engine": 4,
"is_locomotive": false
},
{
"sequence": 5,
"coach_name": "S5",
"class_code": "SL",
"class_name": "Sleeper",
"coach_type": "RESERVED",
"position_from_engine": 5,
"is_locomotive": false
}
]
},
"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"
}
]
}
}
}
| Status | Code | Description | Retry |
|---|---|---|---|
| 404 | TRAIN_NOT_FOUND | No train has that number. error.message names it: Train 99999 not found. Check the train number. Not counted. | Not retryable |
| 404 | COACH_POSITION_NOT_FOUND | The train exists, but no source RailCore reads publishes its coach composition. error.message names it: No coach composition is published for train 12345. Not counted. | Not retryable |
| 400 | VALIDATION_ERROR | A required field is missing or invalid. error.details[].field names the parameter, such as date or items[2].date. | Not retryable |
| 401 | MISSING_API_KEY | No key in X-RailCore-Key, Authorization: Bearer or X-Api-Key, or the key is too short. | Not retryable |
| 401 | INVALID_API_KEY | The key is unknown or revoked. A disabled or expired key answers API_KEY_DISABLED or API_KEY_EXPIRED. | Not retryable |
| 401 | AMBIGUOUS_API_KEY | More than one key header was sent, with different keys. Send the key in one header. | Not retryable |
| 401 | SIGNATURE_INVALID | HMAC 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 |
| 403 | SCOPE_MISSING | The key lacks this operation's scope. | Not retryable |
| 403 | PLAN_ENDPOINT_DISABLED | The account's plan does not include this endpoint. | Not retryable |
| 402 | CREDITS_EXHAUSTED | The month's requests are used up, or too few are left for this request. Nothing is fetched. | Not retryable |
| 429 | RATE_LIMITED | The 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 |
| 410 | API_VERSION_SUNSET | This API version has reached its announced sunset date. Migrate to a supported major version. | Not retryable |
| 503 | UPSTREAM_UNAVAILABLE | Live data could not be retrieved. Wait for Retry-After, then retry with backoff. Not counted. | Retryable |
| 503 | UPSTREAM_TIMEOUT | The live-data request ran past its deadline. Wait for Retry-After, then retry with backoff. Not counted. | Retryable |
| 503 | METERING_UNAVAILABLE | The request could not be counted, so no data was returned. Retry with backoff. | Retryable |
All RailCore Indian Railways API endpoints · Quickstart · Rate limits
Last updated