Thetravel APIcrociere.thetravel.it ↗
Search MSC and Costa cruise departures on crociere.thetravel.it. Filter by destination, port, nights, dates, and guest counts. Returns prices, itineraries, and ports.
What is the Thetravel API?
The crociere.thetravel.it API exposes 2 endpoints for querying cruise departures and departure ports listed on the Italian travel site crociere.thetravel.it, which aggregates MSC and Costa cruise sailings. The search_cruises endpoint returns per-itinerary records including total EUR prices for a specified guest party, ship name, departure port, itinerary stops, and night count. The list_sailing_ports endpoint resolves available departure ports for any destination area code.
curl -X GET 'https://api.parse.bot/scraper/aa0826ba-07af-4fd5-82db-7b4c88d29abf/search_cruises?destination=MED' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace crociere-thetravel-it-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: CrociereTheTravel SDK — search Mediterranean cruises and list departure ports."""
from parse_apis.crociere_thetravel_it_api import (
CrociereTheTravel, Destination, CruiseLine, Nights, InputFormatInvalid,
)
client = CrociereTheTravel()
# List departure ports available for the Mediterranean destination.
try:
for port in client.ports.list(destination=Destination.MEDITERRANEO, limit=5):
print(port.port_code, port.name)
except InputFormatInvalid as e:
print(f"Invalid input: {e.message}")
# Search for 7-night Costa cruises departing from the Mediterranean.
cruise = client.cruises.search(
destination=Destination.MEDITERRANEO,
cruise_line=CruiseLine.COSTA,
nights=Nights.N7,
limit=1,
).first()
if cruise is not None:
print(cruise.cruise_code, cruise.ship_name, cruise.departure_port)
print(f" {cruise.nights} nights from €{cruise.price_from} {cruise.currency}")
print(f" Itinerary: {', '.join(cruise.itinerary or [])}")
# Show alternative departure dates for the same itinerary.
for dep in cruise.available_departures:
print(f" Also on {dep.departure_date} from €{dep.price_from}")
# Browse upcoming cruises with a date window, capped at 3 results.
for c in client.cruises.search(
date_from="2027-03-01",
date_to="2027-04-30",
adults=2,
limit=3,
):
print(c.cruise_line, c.ship_name, c.departure_date, f"€{c.price_from}")
print("exercised: ports.list / cruises.search")
Searches cruise departures and returns one record per cruise itinerary with its selected departure date, the 'from' price in EUR for the given guest party (port taxes included, agency discount label shown), ship name, departure port, itinerary stops/countries, nights, and the list of alternative departure dates of the same itinerary with their 'from' prices. The site returns the whole result set in one page; the scraper slices it locally with offset/limit (limit is clamped to 20) and fetches ship/port/itinerary details for each cruise in the returned slice (one extra request per cruise). total is the site's result count for the whole search; has_more tells whether a further offset slice exists. When date_from/date_to are omitted the site uses its default window of today to two months ahead, reported in search_window. Cruises whose detail fragment could not be loaded are listed in details_missing_for with their ship fields null. Ordering follows the site (special offers first).
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of cruises to return in this slice; values above 20 are clamped to 20. |
| adults | integer | Number of adults (18+), at least 1. Prices are the total for the whole party. |
| nights | string | Cruise length filter in nights. Omitted = any length. |
| offset | integer | Zero-based position in the full result list where the returned slice starts. |
| date_to | string | End of the departure date window, ISO date YYYY-MM-DD. Must be supplied together with date_from. |
| infants | integer | Number of infants aged 0-1. |
| juniors | integer | Number of teenagers aged 12-17. |
| children | integer | Number of children aged 2-11. |
| date_from | string | Start of the departure date window, ISO date YYYY-MM-DD. Must be supplied together with date_to. |
| cruise_line | string | Cruise company filter. Omitted = both companies. |
| destination | string | Destination area code. Omitted = all destinations. |
| sailing_port | string | 3-letter departure port code, port_code from list_sailing_ports.ports[*].port_code. Omitted = any port. |
{
"type": "object",
"fields": {
"limit": "integer, limit applied after clamping",
"total": "integer, the site's total number of matching cruises",
"offset": "integer, offset applied",
"cruises": "array of cruise records: cruise_line, cruise_code, departure_date (ISO), price_from (number, EUR total for the party), currency, detail_url, ship_name, departure_port, itinerary (array of stop or country names), nights (integer), discount_label, available_departures (array of {departure_date, price_from, detail_url} for the same itinerary)",
"has_more": "boolean, whether cruises exist beyond offset+limit",
"search_window": "object {date_from, date_to} ISO dates of the departure window the site applied",
"details_missing_for": "array of cruise_code values whose ship/port/itinerary details could not be loaded"
},
"sample": {
"data": {
"limit": 3,
"total": 11,
"offset": 2,
"cruises": [
{
"nights": 7,
"currency": "EUR",
"itinerary": [
"Italia",
"Spagna",
"Francia"
],
"ship_name": "Msc Sinfonia",
"detail_url": "https://crociere.thetravel.it/msc/cruise/Q1EI/SX20270330GOAGOA",
"price_from": 1298,
"cruise_code": "SX20270330GOAGOA",
"cruise_line": "msc",
"departure_date": "2027-03-30",
"departure_port": "Genova (Portofino), Italia",
"discount_label": "Sconto THETRAVEL (-6%)",
"available_departures": [
{
"detail_url": "https://crociere.thetravel.it/msc/cruise/Q1EI/SX20270330GOAGOA",
"price_from": 1298,
"departure_date": "2027-03-30"
}
]
}
],
"has_more": true,
"search_window": {
"date_to": "2027-04-30",
"date_from": "2027-03-01"
},
"details_missing_for": []
},
"status": "success"
}
}About the Thetravel API
What the API covers
The API covers MSC and Costa cruise sailings listed on crociere.thetravel.it. Each record returned by search_cruises corresponds to a specific cruise itinerary with a selected departure date, and includes: cruise_line, cruise_code, departure_date (ISO format), price_from (total EUR for the full guest party, port taxes included), currency, ship name, departure port, itinerary stops and countries, and number of nights. Prices reflect the agency discount label shown on the site.
Filtering and pagination
search_cruises accepts filters for nights (cruise duration), date_from/date_to (ISO date window, both required when used), and guest composition broken down as adults (18+, minimum 1), children (2–11), juniors (12–17), and infants (0–1). Results are paginated via offset and limit, with limit clamped to a maximum of 20. The response includes total (site-level match count), has_more (boolean), and a search_window object reflecting the date range the site applied. If detail data could not be loaded for any cruise code, those codes are listed in details_missing_for.
Departure ports
list_sailing_ports takes a destination area code and returns an array of {port_code, name} pairs, where name is the Italian display label and port_code is a three-letter code accepted by search_cruises as a sailing_port filter. If the destination has no ports listed on the site, an empty ports array is returned alongside the echoed destination code.
The Thetravel API is a managed, monitored endpoint for crociere.thetravel.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when crociere.thetravel.it changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official crociere.thetravel.it API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a cruise price tracker comparing MSC vs Costa sailings for a given destination and date range.
- Populate a departure-port selector UI using
list_sailing_portsfor a given destination area code. - Alert users when a sailing matches a target night count and EUR price threshold using
search_cruiseswithnightsandprice_from. - Aggregate cruise itinerary stop data across destinations to map coverage for Mediterranean or Caribbean routes.
- Calculate per-person price by dividing
price_fromagainst total guest count (adults + children + juniors + infants) for comparison displays. - Paginate through all available sailings for a departure port using
offsetandhas_moreto build a complete inventory snapshot.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does crociere.thetravel.it offer an official developer API?+
What does `details_missing_for` mean in the `search_cruises` response?+
details_missing_for is an array of cruise_code values for which ship name, departure port, or itinerary detail data could not be retrieved during that request. The cruise still appears in the cruises array with its price and date, but those detail fields may be null or incomplete for the listed codes.Are cruise lines other than MSC and Costa covered?+
Can I filter by a specific departure port in `search_cruises`?+
sailing_port value (a three-letter port code) to search_cruises. Use list_sailing_ports with the relevant destination code first to obtain valid port codes and their Italian display names for that destination area.Does the API return cabin categories, availability counts, or individual sailing schedules beyond a single departure date per record?+
search_cruises represents one itinerary at one selected departure date with a single price_from figure. Cabin-level breakdown, availability counts, and multi-date sailing calendars are not exposed. You can fork the API on Parse and revise it to add an endpoint targeting those details if the source site surfaces them.