Compare journeys

Compare up to 5 route queries in one request.

POST /v1/journeys/compare

Scope journeys:read · Cost 1 request per route compared, minimum 1 request · Plans All plans

Runs route searches in parallel and returns per-item results so one failed comparison does not discard successful ones.

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 journeys: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

This operation takes no path or query parameters.

JSON body

FieldTypeDescription
journeysJourneyInput[]Array with 1 to 5 journey objects. Each one counts as 1 request.
journeys[].fromstringBoarding station code.
journeys[].tostringDestination station code.
journeys[].datestring(date)Journey date.
journeys[].quotaQuotaOptional reservation quota.

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

JOURNEY_DATE=$(date -u -d "+7 days" +%F 2>/dev/null || date -u -v+7d +%F)
JOURNEY_DATE_2=$(date -u -d "+8 days" +%F 2>/dev/null || date -u -v+8d +%F)

curl -sS -X POST \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"journeys":[{"from":"BSL","to":"ADI","date":"'"$JOURNEY_DATE"'","quota":"GN"},{"from":"NDLS","to":"BCT","date":"'"$JOURNEY_DATE_2"'","quota":"GN"}]}' \
  "https://ir.railcore.tech/v1/journeys/compare"

JavaScript

const journeyDate = new Date(Date.now() + 7 * 86_400_000).toISOString().slice(0, 10);
const journeyDate2 = new Date(Date.now() + 8 * 86_400_000).toISOString().slice(0, 10);

const response = await fetch("https://ir.railcore.tech/v1/journeys/compare", {
  method: "POST",
  headers: {
    "X-RailCore-Key": process.env.RAILCORE_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "journeys": [
    {
      "from": "BSL",
      "to": "ADI",
      "date": journeyDate,
      "quota": "GN"
    },
    {
      "from": "NDLS",
      "to": "BCT",
      "date": journeyDate2,
      "quota": "GN"
    }
  ]
}),
});

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

Python

import datetime
import os
import requests

journey_date = (datetime.date.today() + datetime.timedelta(days=7)).isoformat()
journey_date_2 = (datetime.date.today() + datetime.timedelta(days=8)).isoformat()

response = requests.request(
    "POST",
    "https://ir.railcore.tech/v1/journeys/compare",
    headers={"X-RailCore-Key": os.environ["RAILCORE_KEY"]},
    json={"journeys": [{"from": "BSL", "to": "ADI", "date": journey_date, "quota": "GN"}, {"from": "NDLS", "to": "BCT", "date": journey_date_2, "quota": "GN"}]},
    timeout=20,
)
print(response.status_code, response.json())

Rate limits and cost

This operation counts as 1 request per route compared, minimum 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
results[]RouteTrains[]One route result for each input, in order, or an inline failure with error and message: NO_TRAINS_FOUND when no train was found for that route. Each result carries matched_by; a comparison matches by city, as trains between stations does by default.
results[].from_station_codestringResolved origin.
results[].to_station_codestringResolved destination.
results[].journey_datestring(date)Requested journey date.
results[].quotaQuotaApplied reservation quota.
results[].matched_bystringstation: every train runs between the two stations you asked for. city: some trains run between other stations of the same two cities; each train's from_station_code and to_station_code say which.
results[].trains[].train_numberstringTrain number.
results[].trains[].train_namestringShort name as printed on reservation charts, for example NAVJEEVAN SF EXP.
results[].trains[].extended_train_namestringThe train's full name from RailCore's train catalog, for example Navjeevan SF Express. The same as train_name for a train the catalog does not list.
results[].trains[].from_station_code / to_station_codestringWhere this train is boarded and left. With match=city they can be other stations of the two cities than the ones you asked for (BDTS and NZM on a search from MMCT to NDLS); with match=station they are always the two you asked for.
results[].trains[].from_station_name / to_station_namestringNames of those two stations.
results[].trains[].departure_time / arrival_timestringScheduled segment times in HH:mm.
results[].trains[].duration_minutesintegerSegment duration.
results[].trains[].distance_kmnumber | nullSegment distance.
results[].trains[].train_typestringNormalized train type.
results[].trains[].classesClassCode[]Offered travel classes.
results[].trains[].running_daysRunningDay[]Weekly running pattern.
results[].trains[].has_pantryboolean | nullPantry availability when known.
results[].trains[].availability_summaryAvailabilityMini[]Compact class-level status, fare, confidence, and update time. last_updated_at is India time with its offset, and can be days old: for a fresh figure call seat availability.

Example response

{
  "success": true,
  "data": {
    "results": [
      {
        "from_station_code": "BSL",
        "to_station_code": "ADI",
        "journey_date": "2026-11-27",
        "quota": "GN",
        "matched_by": "station",
        "trains": [
          {
            "train_number": "12656",
            "from_station_code": "BSL",
            "from_station_name": "Bhusaval Junction",
            "to_station_code": "ADI",
            "to_station_name": "Ahmedabad Junction",
            "train_name": "NAVJEEVAN SF EXP",
            "extended_train_name": "Navjeevan SF Express",
            "departure_time": "10:25",
            "arrival_time": "18:00",
            "duration_minutes": 455,
            "distance_km": 563,
            "train_type": "SF",
            "classes": [
              "SL",
              "3A",
              "2A",
              "1A"
            ],
            "running_days": [
              "MON",
              "TUE",
              "WED",
              "THU",
              "FRI",
              "SAT",
              "SUN"
            ],
            "has_pantry": true,
            "availability_summary": [
              {
                "class_code": "3A",
                "status": "AVAILABLE",
                "text": "AVAILABLE-4",
                "fare": 965,
                "confidence": "high",
                "last_updated_at": "2026-11-20T08:15:46.547+05:30"
              }
            ]
          }
        ]
      }
    ]
  },
  "meta": {
    "api_version": "v1",
    "request_id": "req_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "trace_id": "trc_01J5Z7Y8N2K4M6P8R0T2V4X6Z9",
    "timestamp": "2026-11-20T10:57:05.609Z",
    "freshness": {
      "mode": "live",
      "retrieved_at": "2026-11-20T10:57:05.609Z",
      "sources": [
        {
          "confidence": "high"
        }
      ]
    }
  }
}

Errors

StatusCodeDescriptionRetry
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 Journeys endpoints

All RailCore Indian Railways API endpoints · Quickstart · Rate limits

Last updated