CruiseAPI
Home › Technical Guides › Itinerary Search
Itinerary Search

Designing High-Speed Cruise Itinerary Search with /v2/voyages

Implement sub-second itinerary discovery across global ports, sailing durations, and vessel classes using clean query parameters.

Structuring Faceted Parameters for Maritime Discovery

Cruise shoppers rarely search by a single departure date alone; they combine broad regions, embarkation ports, duration bands, cruise line tiers, and passenger counts. Designing /v2/voyages with composable query filters—such as region, embark_port, min_nights, max_nights, and departure_window—lets frontends render faceted sidebars directly from API metadata.

Standardizing port filters on five-character UN/LOCODE identifiers (for example, USMIA for Miami or ESBCN for Barcelona) eliminates ambiguity between city names, terminal aliases, and multi-port metro areas across international itineraries.

  • Support array filters for cruise_line_id, vessel_class, and destination_region.
  • Return facet counts alongside paginated sailing cards for instant UI updates.
  • Normalize round-trip versus open-jaw repositioning flags in itinerary summaries.

Cursor Pagination and Deterministic Sorting

Large global cruise catalogs routinely span more than 15,000 active future departures across 18 to 24 months. Offset-based pagination degrades as datasets shift during live inventory refreshes, causing duplicate or skipped sailings as users scroll through search results.

Keyset or cursor-based pagination anchored on departure timestamp, lead-in fare, and canonical sailing ID keeps page transitions deterministic. Returning lightweight summary cards in /v2/voyages while deferring full deck-by-deck pricing to /v2/quotes keeps payload sizes compact.

Caching Static Schedules vs. Lead-In Pricing

Port-of-call sequences, sea days, and arrival/departure times change infrequently once a season is published, whereas lead-in cabin prices fluctuate daily. Splitting itinerary geometry from volatile pricing enables aggressive edge caching of route definitions while refreshing lead-in fares via short-TTL stale-while-revalidate headers.

Whenever a booking closes a cabin category, asynchronous inventory invalidation events can purge only the affected sailing ID from edge cache rather than flushing an entire region.

Recommended /v2/voyages Query & Payload Design

Parameter / FieldFormatPurposeCache Impact
embark_portUN/LOCODE (e.g., USMIA)Exact embarkation harbor filterHigh cache hit rate
departure_from / toYYYY-MM-DD (ISO 8601)Bounded sailing date windowNormalize to week/month
nightsRange (e.g., 7..10)Duration filteringPredictable cache keys
currencyISO 4217 (e.g., USD, EUR)Lead-in fare display currencyVary key by currency
cursorOpaque base64 tokenStable forward/back pagingConsistent result order

Canonicalizing query parameter order before cache lookup maximizes CDN hit ratios.

Worked Illustration: Payload Reduction on /v2/voyages

This worked illustration compares an unoptimized full-graph response against a lean discovery payload for 25 sailings:

  1. Baseline payload embedding full port descriptions, 12 cabin categories, and 15 image URLs per sailing measures ~480 KB uncompressed JSON.
  2. Move port prose and full gallery arrays to /v2/assets and limit /v2/voyages to summary fields plus lead-in prices per meta-category.
  3. Compressed Brotli response drops to ~18 KB—a 96% wire-size reduction across mobile networks.
  4. Client hydrates the search grid in under 150 ms and fetches /v2/quotes only when the user selects a specific sailing.

Worked Illustration Summary: Separating summary discovery from deep cabin quotes cuts bandwidth by over 90% and improves Core Web Vitals.

Itinerary Search Implementation Checklist

  • Map all embarkation and port-of-call filters to canonical UN/LOCODE identifiers.
  • Canonicalize query parameter ordering and strip empty filters at the CDN edge.
  • Use cursor pagination instead of deep SQL/search offsets for multi-page browsing.
  • Return lead-in prices by meta-category (Interior, Oceanview, Balcony, Suite).
  • Include port arrival and departure local timestamps in ISO 8601 format.
  • Track zero-result query combinations to catch unmapped seasonal routes.

Frequently Asked Questions

Should /v2/voyages return every available cabin number on search?

No. Returning full stateroom inventories during broad discovery inflates payloads and triggers unnecessary supplier lookups. Return lead-in meta-category fares on /v2/voyages and query /v2/quotes once a user selects a sailing.

How are sea days represented in itinerary arrays?

Each day object typically carries a day_number, port_code (null or AT_SEA indicator), arrival_time, and departure_time so UI timelines render cleanly.

Why normalize ports to UN/LOCODE?

Different cruise lines label the same port differently (for example, Civitavecchia vs. Rome). UN/LOCODE provides an authoritative international port code for deduplication and search.

What is the best TTL for /v2/voyages responses?

A 5 to 15 minute stale-while-revalidate edge TTL works well for browsing, paired with live fare verification on /v2/quotes before checkout.

Primary Standards & Industry References

  • UNECE UN/LOCODE — United Nations Code for Trade and Transport Locations
  • RFC 9111 — HTTP Caching (IETF)
  • OpenTravel Alliance Cruise Sailing Availability Messages

Related Technical Guides