Inventory API

A REST API that provides access to information about the boats, engines, and trailers that make up Boats Group's inventory.

This document provides detailed information about the Inventory API specifically. For information that is common to all Boats Group APIs — namely details about authentication, specifying response formats & API versions, global query parameters, and error codes, please refer to the Overview page.

The base URL for the Inventory API is:

http://api.boats.com/inventory

If you only require information about a particular item, the best way to do that is to send a request to the API with the item's ID as in the following example:

http://api.boats.com/inventory/1234567

Executing a search is as simple as sending a GET request to the following API URL with the necessary query parameters:

http://api.boats.com/inventory/search

In addition to the global query parameters, the following custom query parameters are supported by the Inventory API:

Aliases	Type	Description	Example
`AdvancedKeywordSearch`	FUZZY	Searches across ModelYear, MakeString, Model, GeneralBoatDescription and Location.	`AdvancedKeywordSearch=Sea Ray`
`ApprovedProgramName`	VALUE	`ApprovedProgramName` indicates Inventory that has been marked as being part of the given Program.	`ApprovedProgramName=Princess Approved`
`BceuID`	VALUE	The `BceuID` parameter allows you to search for inventory by IDs from the Boats.com EU site.	`BceuID=1234567`
`BcnaID`	VALUE	The `BcnaID` parameter allows you to search for inventory by IDs from the Boats.com site.	`BcnaID=1234567`
`BoatCityNameNoCaseAlnumOnly`	VALUE	The `BoatCityNameNoCaseAlnumOnly` parameter allows you to search for inventory in a particular city with no case or non alpha characters.	`BoatCityNameNoCaseAlnumOnly=norfolk`
`BoatClassCodeNoCaseAlnumOnly`	VALUE	The `BoatClassCodeNoCaseAlnumOnly` parameter allows you to search for inventory of a particular boat class code with no case or non alpha characters.	`BoatClassCodeNoCaseAlnumOnly=catamaran`
`BoatNameNoCaseAlnumOnly`	VALUE	The `BoatNameNoCaseAlnumOnly` parameter allows you to search for inventory of a particular boat name with no case or non alpha characters.	`BoatNameNoCaseAlnumOnly=jolly roger`
`BtolID`	VALUE	The `BtolID` parameter allows you to search for inventory by IDs from the Boat Trader Online site.	`BtolID=1234567`
`DocumentID`, `id`	VALUE	The `DocumentID` parameter allows you to search for inventory by its unique ID, although the preferred way to search by unique ID is discussed in the Using IDs section of this document.	`DocumentID=1234567`
`EmbeddedVideoPresent`	VALUE	Whether embedded video is present (use 1) or absent (use 0)	`EmbeddedVideoPresent=1`
`EnhancementCode`	VALUE	The `EnhancementCode` parameter allows you to search for inventory with a particular enhancement.	`EnhancementCode=BC-FEATURED-BOATS-SEARCH`
`ExcludedCaliforniaListings`	SET	Allows for exclusion of listings for boats located in California.	`ExcludedCaliforniaListings=true`
`HasBoatHullID`	VALUE	Allows search for boats that have a HIN.	`HasBoatHullID=true`
`Image360PhotoPresent`, `Image360`	VALUE	Whether a 360° image is present (use 1) or absent (use 0)	`Image360PhotoPresent=1`
`ImmersiveTourPresent`, `ImmersiveTour`	VALUE	Whether an Immersive Tour information is present (use 1) or absent (use 0)	`ImmersiveTourPresent=1`
`IsAvailableForPls`	VALUE	Allows searching for boats that are available for co-brokerage.	`IsAvailableForPls=true`
`ItemReceivedDate`	VALUE	Date on which the boat was added to the Inventory Management Tool.	`ItemReceivedDate=2012-11-22`
`ItemReceivedDaysAgo`	VALUE	Restricts results to boats added this many days ago or less	`ItemReceivedDaysAgo=5`
`ListingTitle`	FUZZY	An extra note from the seller.	`ListingTitle=Priced to sell!`
`MakeStringNoCaseAlnumOnly`	VALUE	The `MakeStringNoCaseAlnumOnly` parameter allows you to search for inventory of a particular make with no case or non alpha characters.	`MakeStringNoCaseAlnumOnly=rinker`
`ModelNoCaseAlnumOnly`	VALUE	The `ModelNoCaseAlnumOnly` parameter allows you to search for inventory of a particular model with no case or non alpha characters.	`ModelNoCaseAlnumOnly=model`
`ProvisioningEventName`	VALUE	The `ProvisioningEventName` parameter allows you to search for inventory belonging to a given event as defined in Provisioning.	`ProvisioningEventName=The Big Boat Show`
`Service`	VALUE	The `Service` parameter allows you to search for inventory that is tagged with a given Provisioning service name.	`Service=example.service`
`SoldDate`	DATETIME	The date the boat was sold	`SoldDate=2012-11-30`
`TrimTabsIndicator`	BOOLEAN	Indicates whether the boat is equiped with trim tabs.	`TrimTabsIndicator=on`
`YachtWorldID`	VALUE	The `YachtWorldID` parameter allows you to search for inventory by IDs from the YachtWorld site.	`YachtWorldID=1234567`
`category`, `BoatCategoryCode`	VALUE	The `category` parameter allows you to search for inventory in a particular category.	`category=Power`
`city`, `BoatCityName`	VALUE	The `city` parameter allows you to search for inventory in a particular city.	`city=Norfolk`
`class`, `BoatClassCode`	VALUE	The `class` parameter allows you to search for inventory in a particular class.	`class=Convertible Boats`
`condition`, `SaleClassCode`	SET	The `condition` parameter allows you to search for inventory by sales condition. The allowed values are: Used, New	`condition=Used`
`coop`, `CoOpIndicator`	BOOLEAN	Indicates if an item is available for co-brokerage (i.e. another broker can attempt to sell the item)	`coop=true`
`country`, `BoatCountryID`	VALUE	The `country` parameter allows you to search for inventory in a particular country.	`country=US`
`description`, `GeneralBoatDescription`	FUZZY	The `description` parameter allows you to search for inventory with a particular wore or phrase in the inventory's description. It may contain a limited set of HTML tags.	`description=This is a sample description`
`engines`, `NumberOfEngines`	VALUE	The `engines` parameter allows you to search for inventory with a particular number of engines.	`engines=2`
`exactMake`, `MakeStringExact`	VALUE	The `exactMake` parameter allows you to search for inventory of a particular make as exact match. Note that the search is also case sensitive.	`exactMake=Rinker`
`exactModel`, `ModelExact`	VALUE	The `exactModel` parameter allows you to search for inventory of a particular model as exact match. Note that the search is also case sensitive.	`exactModel=Model 123`
`fuel`, `EngineFuel`	VALUE	The `fuel` parameter allows you to search for inventory by a particular fuel type.	`fuel=unleaded`
`hull`, `BoatHullMaterialCode`	VALUE	The `hull` parameter allows you to search for inventory by a particular hull material.	`hull=Fiberglass`
`length`, `NormNominalLength`	RANGE	The nominal or advertised length of the boat. Used for range searches and normalized to meters.	`length=10:20\|meter`
`make`, `MakeString`	FUZZY	The `make` parameter allows you to search for inventory of a particular make.	`make=Sea Ray`
`model`	FUZZY	The `model` parameter allows you to search for inventory of a particular model.	`model=30 Santego`
`modified`, `IMTTimeStamp`	DATETIME	The `modified` parameter allows you to search for inventory that was updated after a particular date.	`modified=12-25-2012`
`owner`, `OwnerPartyID`	VALUE	The `owner` parameter allows you to search for inventory owned by a particular dealer/private party.	`owner=1234567`
`price`, `NormPrice`	RANGE	The base price used for range searches and normalized to USD.	`price=1000:3000\|EUR`
`radius`, `DealerCoords`	RADIUS	The `radius` parameter allows you to search for inventory that exists within the desired radius of a particular set of latitude and longitude coordinates. See Units of Measure (UOM) and Currencies.	`radius=10.0,-20.5\|500\|meter`
`salesrep`, `SalesRepPartyID`	VALUE	The `salesrep` parameter allows you to search for inventory based on the ID of the the sales representative for the inventory.	`salesrep=1234567`
`state`, `BoatStateCode`	VALUE	The `state` parameter allows you to search for inventory in a particular state.	`state=VA`
`status`, `SalesStatus`	SET	The `status` parameter allows you to search for inventory with a particular sales status. The allowed values are: Active, Inactive, Sold, Delete, Sale Pending, On-Order, Trade-In Pending, Expired, Rejected	`status=Active`
`units`	VALUE	The `units` parameter allows you to Select boat measurement unit	`units=imperial:imperial_uk:metric`
`video`, `EmbeddedVideo`	BOOLEAN	The `video` parameter allows you to specify and search by the number of advertisement videos associated with an inventory item.	`video=on`
`year`, `ModelYear`	RANGE	The `year` parameter allows you to search for inventory of a particular model year or within a range of model years.	`year=1996:2002`
`keyword`	FUZZY	The `keyword` parameter allows you to search for inventory that contains a particular word or phrase in one of the following fields: `GeneralBoatDescription`, `MakeString`, `Model`	`keyword=blue`

Your search results may include the following fields, which are not searchable, but which can be specified by name in the "fields" parameter:

Name	Description	Example
`AdditionalDetailDescription`	Additional boat description information. It may contain a limited set of HTML tags.	`This boat is fantastic!`
`BallastWeightMeasure`	The amount of weight used to help maintain a boats balance or buoyancy.	`8500 lb`
`BaseMsrpPrice`	Base manufacturers price.	`170.00 USD`
`BathroomsCountNumeric`	The number of bathrooms.	`2`
`BeamMeasure`	The boat's beam.	`13.33 ft`
`BoatEngineLocationCode`	Boat Engine Location Code	`Starboard`
`BoatEngineTypeCode`	The type of engine on the boat.	`Inboard/Outboard`
`BoatHullID`	Hull identification number. Similar to VIN for automobiles	`ABC1232323`
`BoatKeelCode`	The type of keel, applicable only to sailboats.	`Canting Keel`
`BoatLocation`	Location information about the boat.
BoatCityName	The city in which the boat is located.	Norfolk
BoatCountryID	The country abbreviation in which the boat is located in.	US
BoatStateCode	The state in which the boat is located.	Virginia
`BoatName`	The name of the boat.	`Jolly Roger`
`BridgeClearanceMeasure`	The boat's bridge clearance.	`80.0 ft`
`BuilderName`	The name of the boat builder.	`Custom Boat Builders`
`CabinHeadroomMeasure`	The boat's cabin headroom.	`6.4 ft`
`CabinsCountNumeric`	The number of cabins.	`2`
`CompanyName`	The name of the company selling the boat.	`Boating USA`
`ConvertibleSaloonIndicator`	The `ConvertibleSaloonIndicator` parameter indicates whether or not the boat has a convertible saloon.	`on`
`CruisingSpeedMeasure`	The boat's cruising speed.	`15 mph`
`DeadriseMeasure`	The boat's deadrise angle.	`22 degree`
`DesignerName`	The name of the boat designer.	`Custom Boat Designers`
`DisplacementMeasure`	The displacement weight of the boat.	`141,000.0 lb`
`DisplacementTypeCode`	The boat's type of displacement.	`Full Load`
`DoubleBerthsCountNumeric`	The number of double berths.	`2`
`DriveTransmissionDescription`	Drive transmission description.	`15 degree V-drive, direct mounted.`
`DriveTypeCode`	The boat's drive type.	`Stern`
`DriveUp`	The boat's draft with the drive up.	`2.4 ft`
`DryWeightMeasure`	Indicates the weight of the item when all fluids are empty.	`4000.0 lb`
`ElectricalCircuitMeasure`	The rating of the boat's electrical system	`110 volt`
`EngineMakeString`	The brand of the boat's engine(s).	`Mercury`
`EngineModel`	The model of the boat's engine(s).	`40 ELPT FourStroke`
`EngineModelYear`	The model year of the boat's engine(s).	`2011`
`EnginePower`	Power rating for the engine.	`120.0 hp`
`ExternalLink`	External link data for the boat.
Uri	The external link for the boat.	http://www.domain.com/boatdetails/boatid
Text	The text of the external link.	An Awesome Boat Dealer Website
Type	The type of external link.	Dealer Website
`FreeBoardMeasure`	The vertical distance between the waterline and the top of the hull side.	`3.2 ft`
`FreightPrice`	Price for freight. Applicable for new inventory.	`170.00 USD`
`FuelTankCapacityMeasure`	The total volume of fuel the boat can carry.	`1000 gal`
`FuelTankCountNumeric`	The number of fuel tanks.	`2`
`FuelTankMaterialCode`	The material used to construct the fuel tanks.	`Aluminum`
`HeadsCountNumeric`	The number of heads.	`2`
`HoldingTankCapacityMeasure`	The total volume of the black-water holding tanks.	`100 gal`
`HoldingTankCountNumeric`	The number of black-water holding tanks.	`2`
`HoldingTankMaterialCode`	The material used to construct the holding tanks.	`Plastic`
`Images`	The images available for the boat.
Priority	The priority order of the image	1
Caption	A caption for the photo	This is the main photo
Uri	The photo URL	http://www.domain.com/images/photo1.jpg
LastModifiedDateTime	The date and time the image was last modified.	2010-05-26T14:38:47-08:00
`Images360`	The 360 (panoramic) images for the boat
Uri	The photo URL	http://www.domain.com/images/photo360.jpg
LastModifiedDateTime	The date and time the image was last modified.	2010-05-26T14:38:47-08:00
`ImmersiveTour`	Immersive Tour link data for the boat.
Uri	The Immersive Tour link for the boat.	http://www.domain.com/boatdetails/boatid
Title	Some description for the link	An Awesome Boat Immersive Tour
`IncludedOptionsPrice`	Price for options added to boat. Applicable for new inventory.	`199.00 USD`
`KeelDown`	The boat's draft with the keel down.	`1.4 ft`
`KeelUp`	The boat's draft with the keel up.	`4.3 ft`
`LastModificationDate`	Date at which the boat information was last updated	`2012-08-20`
`LengthAtWaterLine`	The length of the boat at the water line.	`14 ft`
`LengthOfDeck`	The length of the boat's deck.	`14 ft`
`LengthOverall`	The overall length of the boat.	`14 ft`
`MaxDraft`	The boat's maximum draft.	`8.0 ft`
`MaximumNumberOfPassengersNumeric`	The maximum number of passengers the boat can carry.	`6`
`MaximumSpeedMeasure`	The boat's maximum speed.	`18 miles per hour`
`Office`	Office information regarding the boat.
Name	The name of the office	Marine USA
PostalAddress	The postal address for the office.	123 Office Street
City	The city in which the office is located.	Norfolk
State	The state in which the office is located.	VA
PostCode	The postal code for the office.	12345
Country	The country in which the office is located.	US
Phone	A phone number to contact the office.	+1 (222) 333-4455
Email	An email address to contact the office.	[email protected]
`OptionActiveIndicator`	Indicates whether or not the boat should be displayed after it is sold.	`on`
`PrepPrice`	Price for preparing a boat for sale. Applicable for new inventory.	`100.00 USD`
`PriceHideInd`	The `PriceHideInd` field means the price shouldn't be displayed.	`true`
`PriceQualifier`	Text to describe pricing. Typically used to describe options.	`Includes $100 gas gift card.`
`PropellerCruisingSpeed`	The propellor RPM at the defined Cruising Speed.	`4800`
`PropellerType`	The boat's type of propeller.	`3 Blade`
`RangeMeasure`	The boat's range.	`218 mi`
`RegistrationCountryCode`	The country in which the boat is registered.	`Canada`
`RopeCutterIndicator`	Whether or not the particular engine is equipped with a rope cutter.	`true`
`SalesRep`	Sales Representative information for the boat.
Name	The name of the sales representative assigned to an inventory item.	John Doe
PartyID	The party id of the sales representative	123
SalesRepMessage	A block of HTML with additional information about the sales rep.	You can trust me!
`SavingsPrice`	Savings to be subtracted from a boat's price.	`200.00 USD`
`SearchResultsPricePrefixCode`	A code indicating what message, if any, should be displayed before a boat price in search results.	`MSRP_STARTING_AT`
`SingleBerthsCountNumeric`	The number of single berths.	`2`
`Source`	The originating system of the record	`IMT`
`StockNumber`	Dealer assigned stock number	`123235234`
`TaxStatusCode`	Used to indicate if the the Tax has been paid or is not applicable. Possible values are 'Tax Paid', 'Tax Not Paid', and 'Tax Not Applicable'	`Tax Paid`
`TotalEngineHoursNumeric`	The combined running time in hours of all the boat's engines.	`760`
`TotalEnginePowerQuantity`	Total combined power for all engines on the boat.	`3300 HP`
`TotalLiferaftCapacityNumeric`	The number of passengers that may be carried in the boat's lifeboat(s).	`12`
`TotalPrice`	The price of the boat including prep, freight and options.	`50000 USD`
`TwinBerthsCountNumeric`	The number of twin berths.	`2`
`WarrantyExpirationDate`	The date the boat's warranty expires.	`2012-06-01`
`WarrantyPeriod`	The length of the boat's warranty.	`2 years`
`WaterHeaterCapacityMeasure`	The total volume of water heaters.	`100 gal`
`WaterHeaterCountNumeric`	The number of water heaters.	`2`
`WaterHeaterMaterialCode`	The material used to construct the water heaters.	`Stainless Steel`
`WaterTankCapacityMeasure`	The total volume of fresh-water tanks.	`100 gal`
`WaterTankCountNumeric`	The number of fresh-water tanks.	`2`
`WaterTankMaterialCode`	The material used to construct the fresh-water tanks.	`Plastic`
`WindlassTypeCode`	The type of windlass installed on the boat.	`Electric`
`OriginalPrice`	The price of the boat in the Original Currency. Cannot be returned separate to Price.	`123456 USD`

The Inventory API supports several standard units of length and currencies. Parameters that accept units of measurement and currencies are case-insensitive.

{"error":{"message":"Authentication error: invalid API key."}}

<?xml version="1.0"?>
<root><error><message>Authentication error: invalid API key.</message></error></root>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>error</key>
    <dict>
      <key>message</key>
      <string>Authentication error: invalid API key.</string>
    </dict>
  </dict>
</plist>

Inventory API

Introduction

Resource URL

Using IDs Method: GET

Search Method: GET

Other Fields in the results

Units of Measure (UOM) and Currencies

Responses