> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ground-search

> Search live rail, coach and ferry inventory

Search ground-transport connections (rail / coach / ferry). Station and city codes are ISO-country + city, `GBLON` for London, not the IATA `LON`. Each `connections[].id` is a trip item token: pass it verbatim to `POST /v1/trip` as `trip_item_token` to add the journey to a cart, then check out as normal.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/ground_search
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.5.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.


    ### Per-end-user attribution


    On booking calls you may send an optional `X-End-User-Id` request header to
    attribute the booking to one of your own end users (for per-end-user
    attribution and rate-limiting). The value is an **opaque, tenant-scoped**
    identifier that you choose — not a Jinko account id. Omit it to book as the
    tenant. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected.
servers: []
security: []
paths:
  /v1/ground_search:
    post:
      tags:
        - Ground
      summary: Search live rail, coach and ferry inventory
      description: >-
        Search ground-transport connections (rail / coach / ferry). Station and
        city codes are ISO-country + city — `GBLON` for London, not the IATA
        `LON`. Each `connections[].id` is a trip item token: pass it verbatim to
        `POST /v1/trip` as `trip_item_token` to add the journey to a cart, then
        check out as normal.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroundSearchRequest'
      responses:
        '200':
          description: Matching ground connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroundSearchResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: Malformed JSON in request body.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: AUTH_REQUIRED
                  message: Invalid or expired API key.
                  doc_url: https://docs.gojinko.com/api-reference/authentication
        '402':
          description: Payment required — organization balance exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: PAYMENT_REQUIRED
                  message: >-
                    Insufficient balance — this call costs $0.0150 and your
                    organization has $0.0000 available. Top up at
                    https://dashboard.gojinko.com/developers/billing/topup
                  doc_url: https://docs.gojinko.com/concepts/errors
        '409':
          description: The operation conflicts with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: CONFLICT
                  message: an exchange is already in progress for this booking
                  doc_url: https://docs.gojinko.com/concepts/errors
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: >-
                    origins: origins is required; trip_type: trip_type is
                    required
                  doc_url: https://docs.gojinko.com/concepts/errors
        '429':
          description: Rate limit or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Rate limit or quota exceeded.
                  doc_url: https://docs.gojinko.com/concepts/errors
        '502':
          description: The travel provider rejected the request, or an upstream call failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_REJECTED
                  message: >-
                    sabre-rest BargainFinderMaxRQ failed with status 400: 27131
                    - Number of connection locations exceeds maximum allowed
                  doc_url: https://docs.gojinko.com/concepts/errors
        '503':
          description: No travel provider can serve the request right now
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying, forwarded verbatim from the
                upstream service. Absent when the upstream named no interval.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_UNAVAILABLE
                  message: >-
                    All flight providers are temporarily unable to serve this
                    search. Please retry later. Provider reasons: sabre-rest:
                    provider temporarily closed; travelfusion: quota exhausted
                  doc_url: https://docs.gojinko.com/concepts/errors
        '504':
          description: The travel provider did not answer in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_TIMEOUT
                  message: sabre-rest BargainFinderMaxRQ timed out after 30s
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    GroundSearchRequest:
      type: object
      properties:
        departure_stations:
          type: array
          items:
            type: string
          description: Distribusion station codes.
          example:
            - GBLONLPB
        departure_city:
          type: string
          description: ISO-country + city code (GBLON = London), NOT IATA.
          example: GBLON
        arrival_stations:
          type: array
          items:
            type: string
          example:
            - GBLONLHB
        arrival_city:
          type: string
          example: GBLON
        departure_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-08-28'
        return_date:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Round trip. Each leg is priced separately.
        passengers:
          type: array
          items:
            $ref: '#/components/schemas/GroundPassengerGroup'
          description: Defaults to one adult when omitted.
        carrier_codes:
          type: array
          items:
            type: string
          description: Restrict to specific carriers.
          example:
            - HEXR
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: GBP
        locale:
          type: string
          example: en
        intent:
          $ref: '#/components/schemas/IntentInput'
      required:
        - departure_date
      description: >-
        Supply a departure selector (`departure_stations` OR `departure_city`)
        AND an arrival selector (`arrival_stations` OR `arrival_city`). These
        either/or rules are enforced at runtime but cannot be expressed in JSON
        Schema, so they do not appear in `required`.
    GroundSearchResponse:
      type: object
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/GroundConnection'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - AUTH_REQUIRED
                - PAYMENT_REQUIRED
                - RATE_LIMITED
                - BAD_REQUEST
                - FORBIDDEN
                - NOT_FOUND
                - CONFLICT
                - PRICE_CHANGED
                - QUOTE_EXPIRED
                - TRIP_EXPIRED
                - TRIP_STATE_CONFLICT
                - OFFER_EXPIRED
                - OFFER_UNAVAILABLE
                - MISSING_CUSTOMER_DETAILS
                - CURRENCY_UNSUPPORTED
                - UPSTREAM_REJECTED
                - UPSTREAM_UNAVAILABLE
                - UPSTREAM_TIMEOUT
                - UPSTREAM_ERROR
                - INTERNAL
              description: >-
                What went wrong, as a stable machine-readable code. This is a
                closed set — branch on it rather than on `message`, which is
                prose and may change. Codes are only ever ADDED, in a minor
                version, so treat an unknown one as its HTTP status.
              example: BAD_REQUEST
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    GroundPassengerGroup:
      type: object
      properties:
        pax:
          type: integer
          minimum: 1
          description: Number of travelers in this group.
          example: 1
        max_age:
          type: integer
          minimum: 0
          description: >-
            Upper age bound for the group. 0-15 prices as a child; omit for an
            adult.
      required:
        - pax
    IntentInput:
      type: object
      properties:
        user_intent:
          type: string
          nullable: true
          description: >-
            The user's natural-language intent: the Alpic PII-stripped
            paraphrase when available, else a best-effort fallback to the
            client-provided NL query.
          example: find a cheap flight to Tokyo
    GroundConnection:
      type: object
      properties:
        id:
          type: string
          description: >-
            The trip item token. Pass verbatim to POST /v1/trip as
            trip_item_token to add this journey to a cart.
          example: HEXR-GBLONLPB-GBLONLHB-2026-08-28T04:34-2026-08-28T04:59
        departure_station:
          $ref: '#/components/schemas/GroundStation'
        arrival_station:
          $ref: '#/components/schemas/GroundStation'
        departure_time:
          type: string
        arrival_time:
          type: string
        duration_minutes:
          type: number
        transport_mode:
          type: string
          description: train / bus / ferry, when the carrier reports it.
        marketing_carrier:
          $ref: '#/components/schemas/GroundCarrier'
        operating_carrier:
          $ref: '#/components/schemas/GroundCarrier'
        fares:
          type: array
          items:
            $ref: '#/components/schemas/GroundFare'
        from_amount:
          allOf:
            - $ref: '#/components/schemas/GroundAmount'
            - description: Cheapest fare, for "from X" display.
      required:
        - id
    GroundStation:
      type: object
      properties:
        code:
          type: string
        name:
          type: string
        city_name:
          type: string
        country_code:
          type: string
    GroundCarrier:
      type: object
      properties:
        code:
          type: string
          example: HEXR
        trade_name:
          type: string
          example: Heathrow Express
        legal_name:
          type: string
        logo_url:
          type: string
        transport_mode:
          type: string
        website:
          type: string
    GroundFare:
      type: object
      properties:
        fare_class:
          type: string
        fare_name:
          type: string
        total_price:
          $ref: '#/components/schemas/GroundAmount'
        refundable:
          type: boolean
          nullable: true
        exchangeable:
          type: boolean
          nullable: true
        conditions:
          type: array
          items:
            type: string
    GroundAmount:
      type: object
      properties:
        value:
          type: number
          description: Minor units (e.g. pence).
        currency:
          type: string
        decimal_places:
          type: integer
      required:
        - value
        - currency
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````