Coach position

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.

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 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.

Request parameters

NameInTypeRequiredDescription
train_numberpathstringRequiredTrain number, 4 to 6 uppercase letters or digits.

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

curl -sS -X GET \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  "https://ir.railcore.tech/v1/trains/12656/coach-position"

JavaScript

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);

Python

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())

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_numberstringTrain number.
train_name / train_typestringThe train's name and category code, such as SF or RAJDHANI, from RailCore's train catalog.
source_station / destination_stationobjectThe train's first and last stations, each as { code, name }, with the name written out in full.
rake_typestringCoach build. TRAINSET for a self-propelled set.
has_locomotivebooleanTrue for a loco-hauled train, whose list starts with the locomotive. False for a self-propelled set, which has no locomotive row.
locomotivesintegerLocomotive rows in the list: 0 for a self-propelled set, 1 for a loco-hauled train, 2 for a push-pull train.
push_pullbooleanTrue 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_basisstringPresent 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_basisstringWhere 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_coachesintegerCoaches in the list, not counting locomotives or power cars.
power_carsintegerPower cars in the list (LPR, EOG), each a row with coach_type POWER_CAR. 0 on a train with none.
total_vehiclesintegerEvery row in the list: locomotives, coaches and power cars.
formationstringThe 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[].sequenceintegerRow number in the list, from 1.
coach_position[].coach_namestringCoach label such as B1. ENG for the locomotive.
coach_position[].class_codestringThe 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_namestringThe class or vehicle in words: Third AC, Sleeper, General (unreserved), Pantry car, Power car, Generator car, Locomotive.
coach_position[].coach_typestringWhat 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_engineintegerPlace 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_locomotivebooleanTrue for a locomotive row, false for a coach.
coach_position[].locomotive_endstringOn a locomotive row only: which end of the rake it is at. A push-pull train has one of each.

Example response

{
  "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"
        }
      ]
    }
  }
}

Errors

StatusCodeDescriptionRetry
404TRAIN_NOT_FOUNDNo train has that number. error.message names it: Train 99999 not found. Check the train number. Not counted.Not retryable
404COACH_POSITION_NOT_FOUNDThe 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
400VALIDATION_ERRORA required field is missing or invalid. error.details[].field names the parameter, such as date or items[2].date.Not 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_UNAVAILABLELive data could not be retrieved. Wait for Retry-After, then retry with backoff. Not counted.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