Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"groupId"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Free-text cruise search; use suggest_cruise_terms to resolve precise entity names."
},
"page": {
"type": "integer",
"maximum": 1000000,
"minimum": 1,
"description": "One-based result page; default 1."
},
"ship": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Source-native ship ID from items[].ship.id, not a suggestion term ID. Prefer terms for names."
},
"sort": {
"enum": [
"price",
"departure",
"duration",
"relevance"
],
"type": "string"
},
"view": {
"enum": [
"groups",
"sailings"
],
"type": "string",
"description": "Default groups combines departures for each ship itinerary; sailings returns one row per unique dated sailing. Event-specific fares remain available within each sailing."
},
"terms": {
"type": "array",
"items": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Complete suggestion item ID including ship:, port:, destination:, or line: prefix."
},
"maxItems": 10,
"description": "Stable term IDs from suggest_cruise_terms; prefer these for entity-name filtering."
},
"dateTo": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Inclusive latest departure date (YYYY-MM-DD)."
},
"source": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Source ID: carnival or royal_caribbean."
},
"amenity": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Exact captured amenity name from get_sailing ship.amenities[].name."
},
"groupId": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Public ship-itinerary group ID from search_cruises items[].groupId; this is not a sailing ID. Older event-specific group IDs remain supported."
},
"dateFrom": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Inclusive earliest departure date (YYYY-MM-DD)."
},
"pageSize": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Items per page, 1–50; default 3."
},
"returnBy": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
"description": "Inclusive latest disembarkation date, YYYY-MM-DD; excludes unknown return dates. This deadline never expands with dateFlexDays."
},
"nightsMax": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Maximum nights, inclusive. Prefer nightsMin/nightsMax for cruise trip lengths; legacy durationMin/durationMax are days-only."
},
"nightsMin": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Minimum nights. Uses advertised nights, otherwise calendar nights between captured departure and return dates. Unknown durations cannot match."
},
"roundtrip": {
"type": "boolean"
},
"cabinClass": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Normalized cabin class: inside, oceanview, balcony, suite, or other, as captured on the offer."
},
"destination": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Shared destination suggestion ID or destination label. Umbrella destinations such as Caribbean include mapped subregions across cruise lines. Specific regions remain strict; generic Caribbean does not imply Eastern Caribbean. Prefer suggest_cruise_terms to resolve names."
},
"durationMax": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Maximum normalized duration in days, not advertised nights."
},
"durationMin": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Minimum normalized duration in days, not advertised nights."
},
"visitedPort": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Visited port selection: shared port suggestion ID or source-native items[].visitedPorts[].id. Reviewed equivalent ports match across cruise lines; source still restricts the line."
},
"dateFlexDays": {
"type": "integer",
"maximum": 30,
"minimum": 0,
"description": "Optional departure flexibility, 0–30 days before dateFrom and after dateTo. Requires both dates when positive. Exact matches stay in items; outside-window options are separate dateAlternatives. All other filters remain strict. Use only when the user permits flexible dates."
},
"departurePort": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Departure port selection: shared port suggestion ID or source-native items[].departurePort.id. Reviewed equivalent ports match across cruise lines; source still restricts the line. Different embarkation ports remain distinct."
},
"priceMaxCents": {
"type": "integer",
"maximum": 999999999,
"minimum": 0,
"description": "Maximum captured USD cents per person for two guests; 50000 means USD 500/person. Not a party total."
},
"departureTerms": {
"type": "array",
"items": {
"type": "string",
"pattern": "^port:[a-f0-9]{24}$"
},
"maxItems": 10,
"minItems": 1,
"description": "Port IDs from suggest_cruise_terms, matching departure only (OR within this list). General terms ports also match visited ports. Other filters still apply."
},
"includeUnavailable": {
"type": "boolean"
}
},
"additionalProperties": false
}