Gangwaze Cruise Tools

Search upcoming cruise sailings by destination, region, dates, length (nights "lo:hi"), cruise line, ship, departure port, ports of call, cabin type, budget, family fit and more. Pass the full filter set; omitted fields are unfiltered. Returns the match count, cheapest fare, top lines, the 10 soonest-departing sailings (results are always soonest first; each has an id for compareSailings/getPriceHistory) and a link to the full results on gangwaze.com.

{
  "type": "object",
  "properties": {
    "destination": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "A single top-level region name, exact catalogue value (e.g. \"Caribbean\", \"Europe\", \"Alaska\") — NOT a sub-region like \"Mediterranean\" or \"Eastern Caribbean\" (those go in `regions`). Must be a real catalogue value; the tool returns suggestions if it is not recognised. null means no constraint."
    },
    "departurePorts": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 10,
      "default": [],
      "description": "Departure/embarkation port names, exact catalogue values. OR-ed together. The tool resolves each against the real catalogue and returns suggestions for any name it does not recognise."
    },
    "startDate": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Earliest sail date, as \"YYYY-MM-DD\" (e.g. \"2027-03-01\"). null means no lower bound."
    },
    "endDate": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Latest sail date, as \"YYYY-MM-DD\" (e.g. \"2027-06-30\"). null means no upper bound."
    },
    "regions": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 10,
      "default": [],
      "description": "Sub-region names, exact catalogue values (e.g. \"Eastern Caribbean\", \"Western Mediterranean\"). OR-ed together. The tool resolves each against the real catalogue and returns suggestions for any name it does not recognise — it is not case-sensitive but must be a real region."
    },
    "nights": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Cruise length as a colon-delimited INCLUSIVE range \"lo:hi\", e.g. \"7:7\" for exactly 7 nights, \"5:9\" for 5 to 9 nights. Open-ended ranges are allowed: \"5:\" (5+ nights) or \":9\" (up to 9 nights). Do NOT pass a bare number like \"7\" and do NOT use a hyphen like \"5-9\" — both are invalid and the filter will be rejected. null means no constraint."
    },
    "cruiselines": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 10,
      "default": [],
      "description": "Cruise line names, exact catalogue values (e.g. \"Carnival Cruise Line\", not \"Carnival\"). OR-ed together. The tool resolves each against the real catalogue and returns suggestions for any name it does not recognise."
    },
    "cabin": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 10,
      "default": [],
      "description": "Cabin-type keys, lowercase, from exactly: \"inside\", \"oceanview\", \"balcony\", \"suite\". Multiple values are OR-ed. Do not use any other spelling or capitalization (e.g. not \"Suite\") — unrecognised values are rejected."
    },
    "safety": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Safety score as a colon-delimited INCLUSIVE range \"lo:hi\" over a 0-100 scale, e.g. \"80:100\" for safety score 80 and up. Open-ended ranges are allowed: \"80:\" or \":50\". Do NOT pass a bare number or a hyphenated range. null means no constraint."
    },
    "price": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "INSIDE-CABIN TOTAL price for the whole cruise, per person, in whole US dollars, as a colon-delimited INCLUSIVE range \"lo:hi\", e.g. \"100:900\" for $100 to $900. Open-ended ranges are allowed: \"500:\" or \":1500\". Use this for a total budget (\"under $1,500\"); for a budget stated per day / per night use `pricePerNight` instead. Always the inside-cabin price, never other cabin types. Do NOT pass a bare number or a hyphenated range. null means no constraint."
    },
    "pricePerNight": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "INSIDE-CABIN price PER NIGHT, per person, in whole US dollars, as a colon-delimited INCLUSIVE range \"lo:hi\" — e.g. \":100\" for \"under $100 a day\", \"80:120\" for $80 to $120 a night. Use this whenever the user states a budget per day, per night or per person per day; use `price` for a total. Divide nothing yourself — pass the per-night figure the user said. Do NOT pass a bare number or a hyphenated range. null means no constraint."
    },
    "tripShape": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "round_trip",
            "one_way"
          ]
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Whether the cruise returns to where it started. \"round_trip\" for sailings that end at their departure port — use this when someone does not want to book two flights. \"one_way\" for sailings that end somewhere else, which includes repositioning cruises. Exactly those two strings; null means no constraint. About one in five sailings is one-way."
    },
    "shipYear": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Year the ship was BUILT, as a colon-delimited INCLUSIVE range \"lo:hi\", e.g. \"2015:\" for ships built in 2015 or later — this is how to answer \"a newer ship\". The catalogue spans 1998-2024. Open-ended ranges are allowed: \"2015:\" or \":2005\". Note this is the build year, NOT the sail year — for when the cruise departs use startDate/endDate. Do NOT pass a bare number or a hyphenated range. null means no constraint."
    },
    "shipSize": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Ship size as PASSENGER CAPACITY (number of guests), as a colon-delimited INCLUSIVE range \"lo:hi\". Map words to these bands: \"small ship\" / \"intimate\" / \"boutique\" / \"not a floating city\" -> \":1500\"; \"mid-size\" -> \"1500:3000\"; \"big ship\" / \"mega-ship\" / \"lots to do on board\" -> \"3000:\". A stated number works too: \"under 1,000 passengers\" -> \":1000\". The fleet runs 100 to 7,600 guests. Open-ended ranges are allowed. Do NOT pass a bare number or a hyphenated range. null means no constraint."
    },
    "ports": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 10,
      "default": [],
      "description": "Ports of call, exact catalogue names. OR-ed together. The tool resolves each against the real catalogue and returns suggestions for any name it does not recognise."
    },
    "ships": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 10,
      "default": [],
      "description": "Ship names, exact catalogue values. OR-ed together. The tool resolves each against the real catalogue and returns suggestions for any name it does not recognise."
    },
    "lineType": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "mainstream",
          "premium",
          "luxury",
          "river"
        ]
      },
      "maxItems": 10,
      "default": [],
      "description": "Cruise-line tier, from exactly: \"mainstream\", \"premium\", \"luxury\", \"river\". OR-ed together. Use for \"luxury cruise\", \"something upscale\", \"the big mainstream lines\". A NAMED line (\"Seabourn\") goes in `cruiselines`, never here — this field is for when no line is named. Empty array means no constraint."
    },
    "vibes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "relaxing",
          "adventure",
          "nature",
          "shopping"
        ]
      },
      "maxItems": 10,
      "default": [],
      "description": "Itinerary character, from exactly: \"relaxing\", \"adventure\", \"nature\", \"shopping\". OR-ed together. Map only what the user says (\"a relaxing beach week\" -> [\"relaxing\"]; \"scenery and wildlife\" -> [\"nature\"]); never infer a vibe from a destination. Empty array means no constraint."
    },
    "departureDays": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "mon",
          "tue",
          "wed",
          "thu",
          "fri",
          "sat",
          "sun"
        ]
      },
      "maxItems": 10,
      "default": [],
      "description": "Weekday the cruise departs, from exactly: \"mon\", \"tue\", \"wed\", \"thu\", \"fri\", \"sat\", \"sun\". OR-ed together. \"Weekend getaway\" / \"leave on the weekend\" -> [\"fri\",\"sat\"], and set `nights` to \":4\" unless the user gave a length. A named day (\"sails on a Saturday\") -> that day. A short cruise on its own never implies a weekend. Empty array means no constraint."
    },
    "family": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 120
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Family-suitability of the SHIP as a colon-delimited INCLUSIVE range \"lo:hi\" over a 0-100 score. \"Family\", \"with the kids\", \"teens\", \"multi-generational\" -> \"60:\"; \"adults only\", \"couples retreat\", \"no kids\", \"quiet ship\" -> \":40\". Never quote the score to the user. Do NOT pass a bare number or a hyphenated range. null means no constraint."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Compare 2–3 specific sailings side by side: dates, ports, price and price per night, price verdict against the six-month average, ship age and size, family suitability, rating with review count and CDC inspection score. Takes sailing ids from searchCruises.

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120,
        "description": "A sailing id from searchCruises results, e.g. \"carnival-breeze:2026-09-21:5\""
      },
      "minItems": 2,
      "maxItems": 3
    },
    "cabin": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "inside",
          "oceanview",
          "balcony",
          "suite"
        ]
      },
      "maxItems": 4,
      "description": "Cabin types to price: inside, oceanview, balcony, suite. Omit for all."
    }
  },
  "required": [
    "ids"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Judge one sailing's current fare: six-month price history, average, percent above or below it, a verdict, and whether it is on today's price-drop list. Takes a sailing id from searchCruises.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 120,
      "description": "A sailing id from searchCruises results, e.g. \"carnival-breeze:2026-09-21:5\""
    },
    "cabin": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "inside",
          "oceanview",
          "balcony",
          "suite"
        ]
      },
      "maxItems": 4,
      "description": "Cabin types to price: inside, oceanview, balcony, suite. Omit for all."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The biggest current cruise price drops: cabin type, current and average price, percent dropped, sail date and a booking link.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One specific cabin by ship and room number: deck, side and position, category with size and how many it sleeps, connecting cabin, known issues (obstructed view, noise, long walk) and what cruisers who stayed there said. "No issues recorded" is not a guarantee of none.

{
  "type": "object",
  "properties": {
    "ship": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Ship name, e.g. \"Allure of the Seas\""
    },
    "cabin": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16,
      "pattern": "\\d",
      "description": "Cabin number, e.g. \"9318\" or \"D126\""
    }
  },
  "required": [
    "ship",
    "cabin"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A ship's cabins grouped by type (inside, ocean view, balcony, suite): categories, cabin counts, size range, how many they sleep, and the line's guarantee categories.

{
  "type": "object",
  "properties": {
    "ship": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Ship name, e.g. \"Voyager of the Seas\""
    }
  },
  "required": [
    "ship"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One ship: year built and refurbished, size, guests and crew, cabin counts, rating and attribute scores, family suitability, CDC inspection score, venues and editorial.

{
  "type": "object",
  "properties": {
    "ship": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Ship name, e.g. \"Carnival Breeze\""
    }
  },
  "required": [
    "ship"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One cruise line: who it is best and not for, descriptions by traveler type, ratings with review counts, attribute ratings, tier (mainstream, premium, luxury, river) and fleet size.

{
  "type": "object",
  "properties": {
    "line": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Cruise line name, e.g. \"Carnival\" or \"Seabourn\""
    }
  },
  "required": [
    "line"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A cruise line's dress code: overall style, daytime and evening rules, formal nights and how often, jeans/shorts/swimwear rules, venue rules and theme nights.

{
  "type": "object",
  "properties": {
    "line": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Cruise line name, e.g. \"Royal Caribbean\""
    }
  },
  "required": [
    "line"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Guide to a cruise port: what it is like, where it is, things to do, beaches, shopping, terminals, safety score, wifi and car rental.

{
  "type": "object",
  "properties": {
    "port": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Port name, e.g. \"Cozumel\""
    }
  },
  "required": [
    "port"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Bookable shore excursions and resort day passes in a cruise port, with price, duration, rating and a link.

{
  "type": "object",
  "properties": {
    "port": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Port name or slug, e.g. \"Cozumel\""
    }
  },
  "required": [
    "port"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Month-by-month average temperature and rainfall for a cruise port, region or destination, with the warmest and driest months. A place with very different sub-regions returns a list to choose from.

{
  "type": "object",
  "properties": {
    "place": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "A port, region or destination, e.g. \"Alaska\""
    }
  },
  "required": [
    "place"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Beverage-package details by cruise line: package names, maximum drink value, daily limits and gratuity.

{
  "type": "object",
  "properties": {
    "cruiseline": {
      "type": "string",
      "maxLength": 120,
      "description": "Cruise line name; omit for all lines"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}