/yachtworld/boats/search

POST /api/yachtworld/boats/search

Price: 20 credits

Search YachtWorld boats and yachts for sale by keyword, make, model, type, class, condition, year, price, length, engines, fuel, hull, location, seller type and dealer: each with price, specifications, engines, media, seller and sales contact.

How to use it

Find boats for sale and read each listing's full record from the result. To list one dealer's inventory, pass seller.id from any of its boats as dealer_id.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• count integer required — Max number of boats to return (min: 1; max: 2000)
• keyword string nullable — Words matched against the listing text (examples: "catamaran"; minLength: 1)
• make string nullable — Boat make as the site writes it (examples: "Sea Ray"; minLength: 1)
• model string nullable — Boat model as the site writes it; requires make (examples: "340 Sundancer"; minLength: 1)
• boat_type string nullable — Power, sail or unpowered (one of: "power", "sail", "unpowered")
• boat_class string nullable — Boat class (one of: "power-aft", "power-airboat", "power-aluminum", "power-antique", "power-barge", "power-bass", "power-bay", "power-bowrider", "power-center", "power-commercial", "power-convertible", "power-crossover", "power-cruiser", "power-cruiseship", "power-cuddy", "power-deck", "power-dinghy", "power-dive", "power-downeast", "power-dragger", "power-dualconsole", "power-expeditionyacht", "power-expresscruiser", "power-flats", "power-flybridge", "power-fresh", "power-gigayacht", "power-gulet", "power-highperf", "power-house", "power-inflatable", "power-jet", "power-jon", "power-llaut", "power-lobster", "power-mega", "power-motor", "power-motorsailer", "power-multihull", "power-other", "power-passenger", "power-pcatamaran", "power-pilot", "power-pontoon", "power-pwc", "power-rib", "power-rivercruiser", "power-runabout", "power-saltfish", "power-skiff", "power-skifish", "power-skiwake", "power-sloop", "power-sportcruiser", "power-sportfish", "power-superyacht", "power-surfboat", "power-tender", "power-trawler", "power-troller", "power-tug", "power-unspec", "power-util", "power-walk", "sail-antique", "sail-barge", "sail-beachcat", "sail-catamaran", "sail-centercockpit", "sail-commercial", "sail-cruiser", "sail-cutter", "sail-day", "sail-deck", "sail-dinghy", "sail-gulet", "sail-ketch", "sail-motor", "sail-multihull", "sail-other", "sail-performance", "sail-pilot", "sail-racer", "sail-racercruiser", "sail-schooner", "sail-sloop", "sail-superyacht", "sail-trimaran", "sail-unspec", "sail-yawl", "unpowered-dinghy", "unpowered-kayak", "unpowered-tender")
• condition string nullable — New or used (one of: "new", "used")
• year_min integer nullable — Earliest model year (min: 1800; max: 2100)
• year_max integer nullable — Latest model year (min: 1800; max: 2100)
• price_min integer nullable — Lowest asking price in USD (min: 0)
• price_max integer nullable — Highest asking price in USD (min: 0)
• length_min number nullable — Shortest length in feet (min: 0)
• length_max number nullable — Longest length in feet (min: 0)
• engine_hours_min integer nullable — Lowest engine hours (min: 0)
• engine_hours_max integer nullable — Highest engine hours (min: 0)
• number_of_engines integer nullable — Number of engines (min: 1; max: 10)
• fuel_type string nullable — Fuel type (one of: "gasoline", "diesel", "electric", "other")
• hull_material string nullable — Hull material (one of: "fiberglass", "composite", "aluminum", "steel", "wood", "ferro-cement", "hypalon", "other")
• hull_shape string nullable — Hull shape (one of: "catamaran", "deep-vee", "displacement", "flat", "modified-vee", "monohull", "planing", "pontoon", "rib", "sea-v2", "semi-displacement", "trimaran", "tritoon", "other")
• country string nullable — Two-letter country code of the boat location (examples: "US"; pattern: ^[A-Za-z]{2}$)
• subdivision string nullable — State or province code of the boat location; requires country (examples: "FL"; minLength: 1)
• seller_type string nullable — Dealer or private owner (one of: "dealer", "owner")
• dealer_id string nullable — Seller id from a boat's seller.id (examples: "50058"; pattern: ^\d+$)
• sort string — Result ordering (default: "recommended"; one of: "recommended", "price_low_to_high", "price_high_to_low", "year_newest", "year_oldest", "length_longest", "length_shortest", "listed_newest", "listed_oldest")

Response

• @type string (default: "YachtworldBoat")
• id string required
• url string nullable
• make string nullable
• model string nullable
• model_range string nullable
• year integer nullable
• boat_name string nullable
• headline string nullable
• condition string nullable
• status string nullable
• boat_type string nullable
• boat_class string nullable
• classes array (default: [])
• seller_type string nullable
• description string nullable
• description_html string nullable
• descriptions array (default: [])
  • @type string (default: "YachtworldBoatDescription")
  • language string nullable
  • description string required
  • description_type string nullable
  • visibility string nullable
• main_descriptions array (default: [])
  • @type string (default: "YachtworldBoatDescription")
  • language string nullable
  • description string required
  • description_type string nullable
  • visibility string nullable
• price object nullable
  • @type string (default: "YachtworldBoatPrice")
  • currency string nullable
  • amount number nullable
  • is_hidden boolean nullable
  • amounts object (default: {})
    • * number
  • base_amounts object (default: {})
    • * number
  • special_amounts object (default: {})
    • * number
• previous_price object nullable
  • @type string (default: "YachtworldBoatPreviousPrice")
  • amount number nullable
  • currency string nullable
  • revised_at integer nullable
• location object nullable
  • @type string (default: "YachtworldAddress")
  • street string nullable
  • street2 string nullable
  • city string nullable
  • subdivision string nullable
  • country string nullable
  • postal_code string nullable
  • iso_subdivision string nullable
  • latitude number nullable
  • longitude number nullable
• contact object nullable
  • @type string (default: "YachtworldBoatContact")
  • name string nullable
  • phone string nullable
  • address object nullable
    • @type string (default: "YachtworldAddress")
    • street string nullable
    • street2 string nullable
    • city string nullable
    • subdivision string nullable
    • country string nullable
    • postal_code string nullable
    • iso_subdivision string nullable
    • latitude number nullable
    • longitude number nullable
• seller object nullable
  • @type string (default: "YachtworldBoatSeller")
  • id string nullable
  • name string nullable
  • display_name string nullable
  • alias string nullable
  • root_name string nullable
  • root_alias string nullable
  • type string nullable
  • image string nullable
  • image_enhanced string nullable
  • phones array (default: [])
    • @type string (default: "YachtworldPhone")
    • number string required
    • type string nullable
  • location object nullable
    • @type string (default: "YachtworldAddress")
    • street string nullable
    • street2 string nullable
    • city string nullable
    • subdivision string nullable
    • country string nullable
    • postal_code string nullable
    • iso_subdivision string nullable
    • latitude number nullable
    • longitude number nullable
  • is_broker_spotlight boolean nullable
  • is_finance_advantage boolean nullable
• sales_rep object nullable
  • @type string (default: "YachtworldBoatSalesRep")
  • id string nullable
  • first_name string nullable
  • last_name string nullable
  • type string nullable
  • locale string nullable
  • message string nullable
  • certifications array (default: [])
  • phones array (default: [])
    • @type string (default: "YachtworldPhone")
    • number string required
    • type string nullable
  • location object nullable
    • @type string (default: "YachtworldAddress")
    • street string nullable
    • street2 string nullable
    • city string nullable
    • subdivision string nullable
    • country string nullable
    • postal_code string nullable
    • iso_subdivision string nullable
    • latitude number nullable
    • longitude number nullable
• specifications object nullable
  • @type string (default: "YachtworldBoatSpecifications")
  • length_ft number nullable
  • length_m number nullable
  • length_overall_ft number nullable
  • length_overall_m number nullable
  • length_waterline_ft number nullable
  • length_waterline_m number nullable
  • length_deck_ft number nullable
  • length_deck_m number nullable
  • beam_ft number nullable
  • beam_m number nullable
  • max_draft_ft number nullable
  • max_draft_m number nullable
  • drive_up_draft_ft number nullable
  • drive_up_draft_m number nullable
  • max_bridge_clearance_ft number nullable
  • max_bridge_clearance_m number nullable
  • cabin_headroom_ft number nullable
  • cabin_headroom_m number nullable
  • freeboard_ft number nullable
  • freeboard_m number nullable
  • deadrise_at_transom_deg number nullable
  • cruising_speed_kn number nullable
  • cruising_speed_mph number nullable
  • cruising_speed_kmh number nullable
  • cruising_speed_rpm number nullable
  • max_speed_kn number nullable
  • max_speed_mph number nullable
  • max_speed_kmh number nullable
  • max_speed_rpm number nullable
  • range_nmi number nullable
  • range_mi number nullable
  • range_km number nullable
  • displacement_kg number nullable
  • displacement_lb number nullable
  • dry_weight_kg number nullable
  • dry_weight_lb number nullable
  • ballast_kg number nullable
  • ballast_lb number nullable
  • cabin_count integer nullable
  • guest_cabin_count integer nullable
  • crew_cabin_count integer nullable
  • head_count integer nullable
  • guest_head_count integer nullable
  • crew_head_count integer nullable
  • has_convertible_saloon boolean nullable
  • max_passenger_count integer nullable
  • seating_capacity integer nullable
  • max_capacity number nullable
• engines array (default: [])
  • @type string (default: "YachtworldBoatEngine")
  • make string nullable
  • model string nullable
  • year integer nullable
  • category string nullable
  • drive_type string nullable
  • fuel_type string nullable
  • hours number nullable
  • power_hp number nullable
  • power_kw number nullable
  • propeller_type string nullable
  • propeller_material string nullable
  • location string nullable
  • has_rope_cutter boolean nullable
  • has_folding_propeller boolean nullable
• hull object nullable
  • @type string (default: "YachtworldBoatHull")
  • hin string nullable
  • material string nullable
  • shape string nullable
  • keel_type string nullable
  • includes_bowsprit boolean nullable
• fuel_type string nullable
• fresh_water_tanks array (default: [])
  • @type string (default: "YachtworldBoatTank")
  • capacity_l number nullable
  • capacity_gal number nullable
  • capacity_gal_uk number nullable
  • quantity integer nullable
  • material string nullable
• fuel_tanks array (default: [])
  • @type string (default: "YachtworldBoatTank")
  • capacity_l number nullable
  • capacity_gal number nullable
  • capacity_gal_uk number nullable
  • quantity integer nullable
  • material string nullable
• holding_tanks array (default: [])
  • @type string (default: "YachtworldBoatTank")
  • capacity_l number nullable
  • capacity_gal number nullable
  • capacity_gal_uk number nullable
  • quantity integer nullable
  • material string nullable
• features object nullable
  • @type string (default: "YachtworldBoatFeatures")
  • electronics array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • inside_equipment array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • outside_equipment array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • electrical_equipment array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • covers array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • additional_equipment array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • sails array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • rigging array (default: [])
    • @type string (default: "YachtworldBoatFeature")
    • code string required
    • value string nullable
  • battery string nullable
  • windlass string nullable
  • electrical_circuit string nullable
  • has_joystick_control boolean nullable
  • has_rope_cutter boolean nullable
  • has_trim_tab boolean nullable
• legal object nullable
  • @type string (default: "YachtworldBoatLegal")
  • coop_type string nullable
  • listing_type string nullable
  • hull_warranty string nullable
  • warranty_until_at integer nullable
  • tax_country string nullable
  • tax_status string nullable
  • flag_of_registry string nullable
  • builder_name string nullable
  • designer_name string nullable
  • lifestyles array (default: [])
  • is_berth_available boolean nullable
  • is_not_for_sale_in_us_waters boolean nullable
• media array (default: [])
  • @type string (default: "YachtworldBoatMedia")
  • url string required
  • media_type string nullable
  • description string nullable
  • format string nullable
  • width integer nullable
  • height integer nullable
  • sort_order integer nullable
  • status string nullable
  • source string nullable
  • video_embed_url string nullable
  • thumbnail string nullable
  • created_at integer nullable
  • updated_at integer nullable
• virtual_tour object nullable
  • @type string (default: "YachtworldBoatMedia")
  • url string required
  • media_type string nullable
  • description string nullable
  • format string nullable
  • width integer nullable
  • height integer nullable
  • sort_order integer nullable
  • status string nullable
  • source string nullable
  • video_embed_url string nullable
  • thumbnail string nullable
  • created_at integer nullable
  • updated_at integer nullable
• image_count integer nullable
• video_count integer nullable
• attributes array (default: [])
• boat_trader_id string nullable
• imt_id string nullable
• bcna_id string nullable
• find_dealer_url string nullable
• is_featured boolean nullable
• is_enhanced boolean nullable
• is_sponsored boolean nullable
• is_oem_model boolean nullable
• is_current_model boolean nullable
• has_cpyb_logo boolean nullable
• created_at integer nullable
• updated_at integer nullable
• sold_at integer nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The entity was not found, or a precondition failed Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.