Serving High-Resolution Deck Plans & Cabin Galleries via /v2/assets
Render interactive deck maps, clickable cabin hotspots, and fast-loading vessel galleries without bloating live quote responses.
Decoupling Heavy Media from Transactional Quote Payloads
Ship photography, deck schematics, and dining-venue galleries change rarely compared to cabin availability, yet embedding dozens of media URLs inside every /v2/quotes response inflates JSON size and slows mobile rendering. Routing static media through a dedicated /v2/assets endpoint keeps inventory endpoints lean while letting browsers cache visual assets aggressively.
Each vessel and cabin category carries a deterministic asset version hash. Frontends fetch /v2/assets once per ship visit, cache the asset manifest in CDN or IndexedDB storage, and overlay real-time availability badges from /v2/quotes using cabin numbers as join keys.
- Serve responsive breakpoints (400px, 800px, 1600px) in WebP and AVIF.
- Include descriptive alt_text and category tags (BALCONY, DINING, DECK_MAP).
- Attach explicit width and height attributes to prevent layout shift (CLS).
Interactive Deck Plan Coordinates and SVG Hotspots
Modern cruise booking UX lets travelers inspect exact stateroom locations relative to elevators, theaters, and pool decks. To support interactive deck selectors, /v2/assets provides normalized bounding-box or polygon coordinates keyed by deck_number and cabin_number alongside vector SVG or high-DPI PNG deck blueprints.
When a user selects a cabin category, the frontend joins live available cabin numbers returned by /v2/quotes with the coordinate map from /v2/assets, highlighting available staterooms in green and marking connecting pairs or accessible rooms visually.
Asset Licensing, Attribution, and Fallbacks
Cruise ship renderings and cabin photos are governed by supplier brand guidelines. Including media_license and last_verified metadata in /v2/assets ensures partner portals automatically retire outdated imagery after dry-dock ship refurbishments and fall back cleanly to category-level images when specific stateroom photos are unavailable.
Asset Types & Delivery Specifications in /v2/assets
| Asset Type | Recommended Format | Target Size | Cache-Control Header |
|---|---|---|---|
| Cabin Thumbnails | AVIF / WebP | 25–60 KB | public, max-age=604800, immutable |
| Vessel Hero Images | WebP (1600w) | 110–180 KB | public, max-age=604800, immutable |
| Deck Plan Blueprints | SVG or 2x PNG | 60–220 KB | public, max-age=2592000, immutable |
| Cabin Coordinate Map | Minified JSON | 8–25 KB | public, max-age=86400 |
| 360° Tour Manifest | JSON + Tiles | Lazy-loaded | public, max-age=604800 |
Use content-hashed asset URLs so dry-dock ship updates bust edge caches cleanly.
Worked Illustration: Joining Live Quotes with Deck Coordinates
This worked illustration shows how a frontend renders clickable staterooms on Deck 9 in two fast requests:
- Frontend fetches GET /v2/assets/ships/ship_402/decks/9 (cached at CDN, 14 KB SVG + 12 KB cabin coordinate JSON).
- User clicks Balcony Category BA; client fetches GET /v2/quotes?sailing=S991&category=BA returning 11 available cabin IDs.
- Client filters the Deck 9 coordinate map against the 11 live cabin IDs in < 2 ms in-browser.
- Available cabins highlight on the SVG deck plan with hover tooltips showing bed layout and proximity to lifts.
Worked Illustration Summary: Separating deck geometry from live availability enables instant interactive maps with minimal payload overhead.
Media & Deck Plan Integration Checklist
- Fetch ship galleries and deck maps from /v2/assets independently of /v2/quotes.
- Negotiate WebP/AVIF formats with responsive srcset widths for mobile speed.
- Include explicit image dimensions to eliminate Cumulative Layout Shift.
- Key deck hotspot coordinates by canonical deck_number and cabin_number.
- Highlight accessible, connecting, and obstructed cabins on interactive overlays.
- Implement category-level fallback images when stateroom photos are missing.
Frequently Asked Questions
Why not embed all deck images directly inside /v2/voyages?
Embedding dozens of image URLs and coordinates per sailing bloats search payloads by 10x or more. Separating them into /v2/assets keeps search fast and cacheable.
How are deck plans updated after a cruise ship dry-dock refurbishment?
Each vessel asset manifest carries a revision hash; when a ship undergoes refurbishment, updated URLs and coordinate maps publish under a new hash without stale cache collisions.
Are deck coordinates compatible with mobile touch screens?
Yes. Normalized percentage coordinates (0.0 to 1.0) or SVG viewBox coordinates scale smoothly with pinch-to-zoom and touch targets.
What if a specific cabin lacks its own photograph?
The /v2/assets endpoint maps missing cabin-level photos to the parent cabin category gallery (for example, standard Balcony stateroom imagery).
Primary Standards & Industry References
- W3C Scalable Vector Graphics (SVG) 2 Specification
- W3C Web Performance — Core Web Vitals & Cumulative Layout Shift
- RFC 8288 — Web Linking & Immutable Cache Patterns