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

# find-destination

> Discover travel destinations accessible from your departure airports

Surface inspiration when a user knows where they want to leave from but not where they want to go. Typical prompts include "cheap beach getaways from New York" or "weekend trips out of London under €200". Results come back ranked by lowest available fare so the user can compare options before committing to a route.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/find_destination
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.1.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.
servers: []
security: []
paths:
  /v1/find_destination:
    post:
      tags:
        - Discovery
      summary: Discover travel destinations accessible from your departure airports
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindDestinationRequest'
      responses:
        '200':
          description: Matching destinations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindDestinationResponse'
        '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
        '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: Upstream service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_ERROR
                  message: Upstream travel provider returned an error. Please retry.
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    FindDestinationRequest:
      type: object
      properties:
        origins:
          type: array
          items:
            type: string
          minItems: 1
          example:
            - NYC
        destinations:
          type: array
          items:
            type: string
          example:
            - PAR
        origin_type:
          type: string
          enum:
            - city
            - airport
          default: city
        destination_type:
          type: string
          enum:
            - city
            - airport
          default: city
        departure_dates:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example:
            - '2026-07-15'
        departure_date_ranges:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        return_dates:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example:
            - '2026-07-22'
        return_date_ranges:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        stay_days:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          example: 7
        stay_days_range:
          type: object
          properties:
            min:
              type: integer
            max:
              type: integer
          required:
            - min
            - max
        trip_type:
          type: string
          enum:
            - oneway
            - roundtrip
          example: roundtrip
        cabin_class:
          type: string
          enum:
            - economy
            - premium_economy
            - business
            - first
          example: economy
        direct_only:
          type: boolean
          example: false
        adults:
          type: integer
          minimum: 0
          example: 1
        children:
          type: integer
          minimum: 0
        infants_in_lap:
          type: integer
          minimum: 0
        infants_in_seat:
          type: integer
          minimum: 0
        youth:
          type: integer
          minimum: 0
        student:
          type: integer
          minimum: 0
        ages:
          type: array
          items:
            type: integer
            minimum: 0
        residency_country:
          type: string
          minLength: 2
          maxLength: 2
        max_total:
          type: number
          minimum: 0
          exclusiveMinimum: true
          example: 800
        currency:
          type: string
          example: USD
        locale:
          type: string
          example: en-US
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        offset:
          type: integer
          minimum: 0
          default: 0
        sort_by:
          type: string
          enum:
            - lowest
            - recommendation
          default: lowest
        intent:
          $ref: '#/components/schemas/IntentInput'
        flights_per_destination:
          type: integer
          minimum: 1
          maximum: 10
          default: 1
      required:
        - origins
        - trip_type
      example:
        origins:
          - NYC
        trip_type: roundtrip
        departure_date_ranges:
          - start: '2026-09-01'
            end: '2026-09-30'
        stay_days: 7
        cabin_class: economy
        adults: 1
        max_total: 800
        currency: USD
        flights_per_destination: 1
    FindDestinationResponse:
      type: object
      properties:
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/DestinationSuggestion'
        total:
          type: number
          example: 12
        next_page_token:
          type: string
          example: eyJvZmZzZXQiOjIwfQ==
      required:
        - destinations
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    DateRange:
      type: object
      properties:
        start:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        end:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      required:
        - start
        - end
      example:
        start: '2026-06-01'
        end: '2026-06-30'
    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
    DestinationSuggestion:
      type: object
      properties:
        city_name:
          type: string
          example: Paris
        iata_code:
          type: string
          example: PAR
        image_url:
          type: string
          example: https://images.gojinko.com/destinations/par.jpg
        location:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
          required:
            - latitude
            - longitude
          example:
            latitude: 48.8566
            longitude: 2.3522
        lowest_fare:
          $ref: '#/components/schemas/Itinerary'
        flights:
          type: array
          items:
            $ref: '#/components/schemas/Itinerary'
      required:
        - flights
    Itinerary:
      type: object
      properties:
        id:
          type: string
          example: itin_9f3b2a17
        origin:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          required:
            - code
          example:
            code: JFK
            name: New York John F. Kennedy
        destination:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          required:
            - code
          example:
            code: CDG
            name: Paris Charles de Gaulle
        total:
          $ref: '#/components/schemas/Amount'
        cabin_class:
          type: string
          example: economy
      required:
        - id
        - origin
        - destination
    Amount:
      type: object
      properties:
        value:
          type: number
          example: 412.5
        currency:
          type: string
          example: USD
        decimal_places:
          type: integer
          example: 2
      required:
        - value
        - currency
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````