Search cruises
search_cruisesRead-onlyIdempotent
Search cruises sold to the UK market by destination, departure port, cruise line, ship, months or dates, length, budget, no-fly (UK departures) and ocean or river. Names or slugs both work, and anything we can't match comes back in not_understood. query takes free text ("a week in the fjords from Southampton next June"); structured fields win where both are given. Returns up to 20 cruises a page, with prices in pounds (each with its basis and the date it was checked), month counts and Cruisify links. The cursor holds only the page number, so for the next page call again with the same fields (applied_filters, without query) and next_cursor as cursor, up to 10 pages.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ocean or river cruises only | |
| sort | No | departure (default), price, price_per_night, nights (shortest first) or newest | |
| query | No | Free text, read into the fields above: "a week in the fjords from Southampton next June". Structured fields win where both are given. Leave it out when paging. | |
| ships | No | Ship names or slugs | |
| cursor | No | next_cursor from the previous page. It holds only the page number, so send it with that page's applied_filters | |
| months | No | Departure months, YYYY-MM | |
| no_fly | No | true: only cruises leaving from a UK port | |
| date_to | No | Latest departure date, YYYY-MM-DD | |
| date_from | No | Earliest departure date, YYYY-MM-DD | |
| nights_max | No | Longest length, in nights | |
| nights_min | No | Shortest length, in nights | |
| round_trip | No | true: round trips only; false: one-way only | |
| cruise_lines | No | Cruise line names, slugs or short names: "P&O", "fred-olsen" | |
| destinations | No | Destination names or slugs: "Caribbean", "norwegian-fjords" (list_destinations has them all) | |
| max_price_gbp | No | Highest price per person, in pounds | |
| departure_ports | No | Departure port names or slugs: "Southampton" (list_departure_ports has them all) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | This page's number, 20 cruises to a page | |
| total | Yes | How many cruises match | |
| results | Yes | This page's cruises | |
| by_month | Yes | Matching cruises per departure month (YYYY-MM), counted without any months or dates asked for | |
| freshness | Yes | fresh: up to date; stale: some dates or prices may be out of date; cache_only: from the cruises we already held | |
| search_url | Yes | This search on Cruisify | |
| landing_url | No | The Cruisify page for this search, when there is one | |
| next_cursor | No | The cursor for the next page, with applied_filters; absent on the last page we give (page 10 at most) | |
| not_understood | Yes | What was asked for but left out of the search, and why | |
| applied_filters | Yes | The search as it ran, in search_cruises' own fields. Send it back, with next_cursor as cursor, for the next page |