Fantasize Search Cruises API

openapi: 3.2.0
info:
  title: Fantasize cruise finder Search Cruises API
  version: 1.0.0
  description: Every sailing of 23 cruise lines, priced every night, with whether each fare is low, typical or high against its own usual price, and a link to book it. Free, no key. Also an MCP server at https://fantasize.net/mcp.
servers:
- url: https://fantasize.net
tags:
- name: Search Cruises
paths:
  /api/v1/search_cruises:
    get:
      operationId: search_cruises
      summary: Find and rank cruises with today's prices
      description: Accepts the request in plain words (q) or as fields. Searches every sailing Fantasize tracks (23 cruise lines, ~30,000 sailings, priced every night) by region, dates, departure port, ports visited, line, length, cabin and budget. Returns up to 25 sailings with the price per person (taxes and port fees in), per night and for a cabin of two, every cabin grade's price, whether the fare is low, typical or high against that sailing's usual price, the ports of call, and book_url - a link the person opens to book that exact sailing. Default ranking is best_value (furthest below its usual price).
      parameters:
      - name: q
        in: query
        required: false
        description: The person's request in plain words, e.g. "alaska in july from seattle, balcony, under $3000 for two". Read by fixed rules; the answer says how it was understood and which words were not. Any other argument given overrides what q says.
        schema:
          type: string
      - name: region
        in: query
        required: false
        description: 'Where the cruise goes: a region (caribbean, bahamas, alaska, mexico, mediterranean, northern-europe, european-rivers, asia, repositioning, more) or a named place it calls at (greek-islands, norwegian-fjords, canada-new-england, canary-islands, british-isles, baltic, iceland, adriatic, japan, hawaii, panama-canal, bermuda, galapagos, tahiti, arctic, antarctica, danube, rhine, douro), or any port, island, country or state we sail to ("Santorini", "Maui", "Greece", "Juneau"). cruise_options lists the regions and named places with counts.'
        schema:
          type: string
      - name: month
        in: query
        required: false
        description: Departure month, YYYY-MM
        schema:
          type: string
      - name: depart_from
        in: query
        required: false
        description: Earliest departure date, YYYY-MM-DD
        schema:
          type: string
      - name: depart_to
        in: query
        required: false
        description: Latest departure date, YYYY-MM-DD
        schema:
          type: string
      - name: from_port
        in: query
        required: false
        description: 'Departure port, e.g. "Seattle" or "Barcelona"; several comma-separated: "Miami,Fort Lauderdale"'
        schema:
          type: string
      - name: calls_at
        in: query
        required: false
        description: A port the ship must visit, e.g. "Juneau", "Santorini", "Cozumel"
        schema:
          type: string
      - name: line
        in: query
        required: false
        description: Cruise line, e.g. "Royal Caribbean", "NCL", "Princess", "Viking"
        schema:
          type: string
      - name: ship
        in: query
        required: false
        description: Ship name or part of it
        schema:
          type: string
      - name: tier
        in: query
        required: false
        description: 'luxury includes ultra-luxury; ultra-luxury is the top of the market only: Regent, Silversea, Seabourn, Explora Journeys (all-suite, all-inclusive)'
        schema:
          type: string
          enum:
          - contemporary
          - premium
          - luxury
          - ultra-luxury
          - river
      - name: nights_min
        in: query
        required: false
        schema:
          type: integer
      - name: nights_max
        in: query
        required: false
        schema:
          type: integer
      - name: cabin
        in: query
        required: false
        description: Cabin grade to price. Omit to quote balcony where sold, else the next grade.
        schema:
          type: string
          enum:
          - inside
          - oceanview
          - balcony
          - suite
      - name: max_price_per_person
        in: query
        required: false
        description: Budget per person for the whole cruise, USD
        schema:
          type: number
      - name: max_price_per_night
        in: query
        required: false
        description: Budget per person per night, USD
        schema:
          type: number
      - name: only_below_usual
        in: query
        required: false
        description: Only fares measurably below their usual price
        schema:
          type: boolean
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - best_value
          - lowest_price
          - lowest_per_night
          - soonest
          default: best_value
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
      responses:
        '200':
          description: JSON answer; every result carries book_url
        '400':
          description: A value we could not read; the message says which
        '429':
          description: Rate limited
      tags:
      - Search Cruises