openapi: 3.1.0
info:
  title: JodoYatra Route API
  version: 0.1.0
  description: >
    Multi-modal (train + bus) journey planning for India. Read-only. Every leg carries `source`
    (SCHEDULED | ESTIMATED | LIVE); ESTIMATED data must be shown as estimated. Times are IST (+05:30).
    Request types mirror packages/shared/src/types.ts in the JodoYatra repository.
  contact: { email: partners@jodoyatra.in }
servers:
  - url: https://api.jodoyatra.in
paths:
  /v1/places/suggest:
    get:
      summary: Place autocomplete
      parameters:
        - { name: q, in: query, required: true, schema: { type: string, minLength: 2 } }
        - { name: limit, in: query, schema: { type: integer, maximum: 10 } }
      responses: { '200': { description: SuggestResponse } }
  /v1/search:
    get:
      summary: Itineraries from A to B on a date
      parameters:
        - { name: from, in: query, required: true, schema: { type: string } }
        - { name: to, in: query, required: true, schema: { type: string } }
        - { name: date, in: query, required: true, schema: { type: string, format: date } }
        - { name: bufferMins, in: query, schema: { type: integer, minimum: 60, maximum: 480, default: 180 } }
        - { name: maxTransfers, in: query, schema: { type: integer, enum: [0, 1, 2], default: 2 } }
        - { name: modes, in: query, schema: { type: string, example: 'train,bus' } }
        - { name: sort, in: query, schema: { type: string, enum: [best, fastest, cheapest, fewest_changes, safest, earliest] } }
      responses: { '200': { description: SearchResponse } }
  /v1/alternatives:
    get:
      summary: Other dates, change hubs and nearby stations (same parameters as /v1/search)
      responses: { '200': { description: AlternativesResponse } }
  /v1/routes/{from}/{to}/summary:
    get:
      summary: Everything between two cities on a typical day
      parameters:
        - { name: from, in: path, required: true, schema: { type: string } }
        - { name: to, in: path, required: true, schema: { type: string } }
      responses: { '200': { description: RouteSummary } }
