# api.private-yacht.com — Public REST API for Yacht Charter Data

HTML guide and searchable forms for browsing tools: https://private-yacht.com/agent-guide.php
HTML results on the main domain: https://private-yacht.com/agent-results.php?action=search plus the documented query parameters. Use action=detail with yacht_id, or action=quote with quote parameters. The HTML detail pages provide GET forms for child ages, exact extras and payment selection. Follow complete returned links instead of inventing yacht paths; the same validation, cache, rate limits and calculations apply.

> Free, public, read-only JSON API providing real-time yacht charter data for Thailand (Phuket, Krabi, Koh Samui, Pattaya). No authentication required. Operated by Deep Blue Co., Ltd. — Thailand's leading independent yacht charter agency since 2002.

## Remote MCP for compatible agents

- Endpoint: https://api.private-yacht.com/mcp
- Transport: Streamable HTTP, stateless JSON responses, no SSE stream, no login required for public read-only data.
- Tools: search_yachts, get_yacht_details and calculate_quote. All use the same service functions and public data as the REST API.
- search_yachts requires date and adults. Optional region, children, trip_type, destination, budget, pagination, yacht_id and flex_days follow /search semantics.
- get_yacht_details requires yacht_id. Published inclusions are product facts, not a reason to ask staff for confirmation. Preserve all conditions and consult coverage limitations.
- Connect with an MCP-capable server-side client. POST JSON-RPC with Accept: application/json, text/event-stream; negotiate initialize, then send notifications/initialized. Use the negotiated MCP-Protocol-Version header thereafter.
- Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26. No sessions, bookings, payments, emails or operator inquiries are created.
- Agents that cannot use MCP can call the public REST API below. Discovery does not automatically install or enable an MCP connection.

## API Endpoints

- Base URL: https://api.private-yacht.com
- OpenAPI Spec: https://api.private-yacht.com/openapi.yaml

### GET /search
Equipment search: features=water_slide,floating_pool,private_chef,aircon (comma-separated; aliases such as slider and Rutsche work). Use feature_mode=preferred to receive matching yachts in offers and alternatives in alternative_yachts. Explain every difference, for example “without water slide”. Use feature_mode=required for “only with”; conditional/on-request items do not count as confirmed matches. Listed paid add-ons count as options, but their charges are not included in the comparison price.
Maintained equipment rule: an absent equipment listing means not available. Preserve explicit surcharge, on-request and full-day conditions. Do not ask staff to confirm an unlisted feature.
Yacht type is a mandatory filter: yacht_type=catamaran includes power_catamaran and sailing_catamaran. Also supported: motor_yacht, superyacht, sailing_monohull, sailing_yacht (both sailing types), speedboat, luxury_speedboat and large_group_boat. Alternatives still satisfy type, capacity, region and other hard constraints. Each result returns yacht_type.
Main matches and feature alternatives paginate separately using next_offset and alternative_next_offset with the same offset/limit inputs.
Start here to compare yachts. Required: date=YYYY-MM-DD and adults. Optional: children, region (all/phuket/krabi/samui/pattaya), trip_type (fullday/halfday/overnight; overnight requires charter_days=2..7), destination (exact name), max_price_thb, limit (1–30), offset.
Optional yacht_id restricts the search to one yacht. flex_days=1 checks the previous and next day only if no matching fresh availability exists on the requested date. It defaults to 1 for yacht_id requests and 0 for general fleet searches; use flex_days=0 to disable.
Alternative dates appear separately in alternative_dates, with independently calculated prices and fresh availability only. Preserve the customer's requested date; ask for agreement before switching. Failed alternative checks are marked check_failed, never treated as free. Past/same-day dates are skipped. Pagination applies independently to each date.
Returns matching yachts with up to three tour options, comparison prices and details_url. Follow next_offset for more results.
Show only “available” or “availability on request” to the customer. A separate reason explains missing calendar coverage or stale data. Available is not a reservation.
Day-tour prices are QuickQuote comparisons; day searches with children require calculate_quote. Overnight comparisons use the website calculator for the entire tour and adult/child surcharges. All comparison prices exclude selected extras, payment fees and separate park cash; use calculate_quote for the configured total.

### GET /yachts
List published yachts, including yachts whose availability is on request, with name, brand, length, max passengers, regions, cover image, and trip count.
Optional filter: `?region=Phi Phi`

### GET /yachts/{id}
Full yacht detail including trips, gallery, piers, published facts, flat-fee and per-person add-ons, source_url and availability_mode. Read guide_languages for published yacht-specific guide languages (not company-office languages and not a promise that every crew member speaks each language). Answer listed languages without staff reconfirmation; do not promise unlisted ones. Read coverage for omissions. Answer explicit inclusions directly; preserve conditions and applies_to. Do not ask staff to reconfirm an unconditional published inclusion. Prices are not complete configured quotes.

### GET /availability
Calendar-cache availability for every published yacht, evaluated with the same rules as search and quote. No live provider fetch is made by this endpoint.
Params: `?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD`. Defaults: tomorrow through start_date + 89 days. Maximum 90 inclusive dates; both endpoints must fall from tomorrow through tomorrow + 365 days. Invalid/reversed/long ranges return 400.
Every date appears in exactly one of available, booked, or on_request. Missing, stale or incomplete calendar evidence is on_request, never a booked date or a free boat. Active local bookings remain blocking. partial is an empty legacy array. An absent date alone proves nothing.
checked_at per yacht is the oldest observed mapped calendar update in the range, not proof of complete coverage; freshness is checked separately for each date. generated is response creation time only. Available does not reserve a boat. Uses bounded 20-second response cache and shared request/concurrency limits (429/503 with Retry-After).

### GET /pricing
Seasonal pricing per yacht for a specific date. Prices vary by season (peak, regular, low).
Param: `?date=YYYY-MM-DD` (default: today)
Returns cheapest trip per type (fullday, halfday, overnight) with public website customer price incl. applicable VAT. Both price and price_display are customer prices, never operator net prices.
Cover images and enabled gallery images use the same public image paths as the normal yacht pages.
Unverified legacy base/minimum price fields in yacht, trip and destination metadata are null. Use search or quote for the selected date and group.

### GET /destinations
All trip destinations with yacht count and minimum price per destination.

## Data Format
- JSON responses, all prices in Thai Baht (THB)
- Images served from private-yacht.com CDN
- Yacht names include brand and length, e.g. "Bahia (Azimut 52ft)"
- 144+ yachts, 90+ destinations

## About the Operator
- Company: Deep Blue Co., Ltd.
- Website: https://private-yacht.com
- License: TAT Register No. 34/03030
- Contact: info@private-yacht.com | +66 80 524 9091

## Request limits and freshness
Search results may be reused for up to 20 seconds; yacht details for up to 120 seconds. Calendar checked_at remains the source timestamp. Neither a fresh nor a cached result reserves a yacht.
REST search/detail and MCP tool calls share limits: sustained 30 calls per minute per client IP (burst 10), sustained 120 per minute globally (burst 20), and up to four active computations with 60-second lease recovery. Cached responses also count toward rate limits. Honor HTTP 429/503 Retry-After and do not immediately repeat the request. These limits protect the shared website server.

Aircon uses the same maintained field as the website: Full, Cabins (cabins only), Optional, or absent (without Aircon). Preserve scope and optional status; do not promise every area is air-conditioned or assume an optional price. Synonyms include AC, A/C and Klimaanlage. get_yacht_details includes aircon status and scope.

## Configured quote — GET /quote or MCP calculate_quote
Required: yacht_id, trip_id, date, adults, payment_method. Optional: children, food, transfer, addons[], addons_pp[], drinks[]. Use exact option names from get_yacht_details, never send prices. In REST encode lists as addons[]=name&addons[]=other (similarly addons_pp[] and drinks[]).
Payment methods: cash_thb, bank_transfer_thb, wise_thb, revolut_thb, credit_card, paypal_stripe, wechat, alipay. Settlement is THB; read returned payment conditions including payer, currency and onsite limitations. This is informational pricing, not a payment operation.
The yacht-mode website PHP PriceCalculator supplies boat prices. Children, guest price steps, selected options and final rounding follow yacht-mode pycalc.js. Quote totals are for the selected configuration; unselected extras are excluded. No automatic 10% online-booking discount is applied.
Read price.payable_to_charter_thb separately from park_cash. Non-included park fees are cash paid at the park, highest per day tour (multi-day totals require the final itinerary), never added to boat/agency payment or payment fee. The operator estimates child park fees at 50% of the listed adult fee. For day trips use the highest listed fee, never sum fees. For multi-day cruises the final itinerary is required to calculate total admission fees; several parks or islands may charge separately. Missing adult fees remain unknown. Park age policy: under 3 free; ages 3 through 13 pay 50%; ages 14 and over pay the adult fee. Supply child_ages to calculate park totals independently of yacht child-age thresholds. Without ages, park totals for parties with children remain unknown. Fees may change without prior notice; the amount charged at the park applies. Park fees are estimates and may change without prior notice. The amount charged at the park applies. Included transfers and park fees have zero additional cost. Transfer prices use the selected tour region/pier and ceil((adults+children)/10) vans.
For multi-day trips the calendar is checked for each charter day. Availability is not a reservation; blocked dates reject the quote. On-request remains on-request. Read selected_option_conditions for package duration and meal scope. No booking, inquiry or payment is created.
Quotes use the shared bounded cache (20 seconds) and rate limits; respect Retry-After on429/503. Invalid selections return400 on REST or an MCP tool error. A final configured quote is not an all-in promise covering unknown park fees or unselected extras.

## Three-calendar-month availability policy
Agents may describe a date as available only through today plus three calendar months, inclusive, using Asia/Bangkok time (month-end dates clamp to the last day of the target month). Current calendar evidence is still required within that window. Later dates are on_request even when the calendar looks free. Known blocked dates remain blocked at any distance. Search, alternative dates, range feed and quote apply the same rule. availability_policy.available_through gives the current cutoff. outside_three_month_window is a policy reason, not a broken or missing calendar. Prices/options can still be calculated beyond the cutoff, subject to date confirmation. Overnight quotes check every day; crossing the cutoff makes the overall availability on_request. Availability never reserves a yacht.

## Published payment and cancellation terms

Yacht details include terms.sections from the current public CMS terms and cancellation policy, with source URLs and modification timestamps. Read yacht_specific_conditions together with yacht_payment_setting: special text can differ from the standard setting. Preserve scope and exceptions; do not silently select a conflicting deadline. Cancellation percentages are fees, not refund percentages. Use the main boat category and the actual booked day/overnight trip. Separate charter, third-party services and processing fees, including section 13 exceptions. Current website terms do not replace conditions already accepted for an existing booking. No payment, hold, confirmation or refund is executed.

## Exclusive private charter and price basis

This catalogue offers the entire yacht exclusively for the customer group, with captain and crew. Search, details and quotes expose charter_product (private_charter, exclusive_use, captain_included, crew_included, shared_tour=false). Compare like-for-like exclusive crewed charters; do not treat these as per-person join-in tickets. Search price.basis and quote price_basis include the base-price guest allowance and requested adult/child counts. That allowance is not maximum capacity. A calculated comparison amount already covers the requested adults under QuickQuote rules; when children are requested, use calculate_quote. A configured quote covers the selected group and extras. Never multiply a returned group total by the guest count; retain extra-guest charges, optional extras, payment fees and separate park cash as returned. Charter type alone confirms neither availability nor booking.

## Child pricing without unnecessary reconfirmation

Read child_pricing in yacht details and quotes. The published age is a strictly-under threshold for this yacht; send child_ages with actual ages, and adults excluding every guest in that list. children may be omitted or must match the list length. The server classifies yacht and park guests separately. Base guest allowance, extra-passenger rates and block billing are separate from maximum capacity. Selected menus have the same listed per-person price for adults and children; no separate child menu discount. Selected drinks add-ons charge the adult count only. Children still count towards capacity and transfer van quantity. Park child fees are separately estimated at 50% of the listed adult fee, using actual child_ages and the separate park age policy. Park age policy: under 3 free; ages 3 through 13 pay 50%; ages 14 and over pay the adult fee. Supply child_ages to calculate park totals independently of yacht child-age thresholds. Without ages, park totals for parties with children remain unknown. Fees may change without prior notice; the amount charged at the park applies. Unknown adult fees remain null. Park fees are estimates and may change without prior notice. The amount charged at the park applies. Search leaves comparison prices null for groups with children: use calculate_quote rather than requesting manual price confirmation. Preserve source conditions and read quote line_items for actual charges.

## Optional air conditioning prices

Yacht details aircon.priced_options and search requested_features.aircon.priced_options link paid air conditioning to the exact calculator option. Each supplies listed_amount, THB, billing basis, quote_parameter (addons or addons_pp) and quote_value (exact option name). Pass that value in the corresponding array only when requested. These costs are not included in search comparison prices. Preserve usage_duration_hours when stated, such as Air conditioner 12hrs; per-day billing does not promise 24-hour use. A missing price is not zero; multiple_options requires choosing a specific option. Full and cabin-only inclusions remain governed by the maintained yacht setting.

## Yachts currently not offered

An active catalogue exclusion applies to every requested date, independently of the three-month calendar horizon. Such yachts are omitted from search, alternative yachts/dates, yacht listings, seasonal prices, destination summaries and availability ranges. A direct details call returns offer_status=not_offered and eligible_for_recommendation=false, without prices or add-ons; do not recommend this yacht or infer future availability from old cached listings or missing calendar dates. calculate_quote rejects it. Use search_yachts for other yachts. Active exclusions change the server result-cache scope so an old cached offer is not reused after blocking or unblocking. Previously downloaded third-party copies cannot be recalled.

## Concrete next step: draft inquiry

Search offers, yacht details and configured quotes include inquiry.url and inquiry.message for the existing website WhatsApp contact. This prepares a draft only: sent=false and booking_confirmed=false. Never send it without the customer wanting to proceed. Date-specific searches carry yacht, primary tour, date and adult/child counts, with no complete quote implied; use calculate_quote after configuring extras/payment to get the corresponding full message and itemized amount. Selected-configuration messages keep park cash separate and show child park fees at 50% of known adult fees, or unspecified when the adult fee is missing, with the change-without-notice disclaimer. For on_request, the message asks for date availability; published inclusions do not need reconfirmation. Review scope and message before presenting the link. message_in_url=false means open the link and paste the full supplied message; nothing is truncated. website_url leads to the existing calculator but does not restore the selection. No booking, hold, payment, response-time guarantee or sent inquiry is created. Not-offered yachts have no contact draft.

Draft messages end with Request code: PY-AI- followed by a random reference. inquiry.request_code matches that line. Keep this reference when presenting or sending the customer-approved draft so the receiving team can recognize the agent-interface origin. It is not a verified agent identity, stored inquiry, retrievable quote or booking ID. A new draft may receive a new code; a cached response reuses its existing code.

Tour duration: use tour.duration_hours in search (including tour_options), trips[].duration_hours in details, and duration_hours in calculated quotes. These are the selected tour's published hours, not fixed departure or return times. A missing start time does not prevent selection or quotation. Never invent a start/end time from the duration. Null in search/quote means no positive duration is recorded.

Overnight details and quotes expose duration_days, duration_nights, duration_label, duration_kind and published_time_text. Standard overnight categories use their published days/nights, with duration_hours null. Special overnight categories retain their published category label; internal tripdays codes 8/9 are not day counts. Published times are verbatim, without default times. Do not convert days to hours. Fleet search supports standard overnight tours with trip_type=overnight and required charter_days=2..7. Every occupied calendar day including the final day is checked. One blocked day excludes the yacht; incomplete or beyond-three-month coverage means on_request. Capacity uses the selected overnight tour allowance. Comparison prices cover the entire tour and adult/child surcharges, excluding selected extras, payment fees and park cash; use calculate_quote for a configured quote. Adjacent-date alternatives shift the entire interval. Special night/24-hour categories are not in overnight fleet search.

Calculated quotes include trip_context with start_date, end_date and published_meals filtered to the selected tour type. Preserve meal status and conditions; confirmed overnight all-meals inclusions need no staff reconfirmation. Missing meal listings do not establish exclusion. selected_option_conditions also retains selected add-on and transfer source details. Dates do not imply fixed boarding or return times.

Quote trip_context.departure identifies the published pier for the selected tour region, using the same primary/secondary location pairs as the website. A missing matching pier stays null with status not_listed; never substitute the primary pier from another region. Published departure does not specify boarding or pickup time. The inquiry draft includes the departure pier/region.

Age-aware quote example: adults=12&child_ages[]=5&child_ages[]=8&child_ages[]=11&child_ages[]=13. For a yacht with children under12 this yields charter13adults/3children, but park12adults/4children. Do not submit adults=13 with those same four ages: that would double-count one guest. Ages are completed years at the charter date.

Multi-day park fees: Multi-day cruises may incur fees for several national parks or islands. Total admission fees can only be calculated after the final itinerary has been established. Pay separately at the parks; fees may change without prior notice. park_cash.calculation_status=itinerary_required, itinerary_required=true and total_thb/adult_total_thb/children_total_thb are null. Reference fees are individual published rates, not the cruise total or an upper limit. Do not multiply the highest fee by days or promise a fixed amount before the final itinerary. Published included park fees remain zero additional cost.