Property Details API

Invoking the Property Details API

The Property Details API provides the name, address, features, amenities, taxes, rates, minimum-stay requirements, photo URLs, and other information specific to a Bookerville property.

The URL to use for invoking the Property Details API is:
https://www.bookerville.com/API-PropertyDetails?s3cr3tK3y=1234567890ABCDEFGHIJKLMNOPQRS&bkvPropertyId=19

You will of course replace the "s3cr3tK3y" parameter with your own Bookerville API access token. If you don't have one, you may apply for one here: Request API Token

Note: for testing purposes it is fine to pass your API access token using simple query string parameters in the URL as in the sample above. Once you have completed testing, it is far better to pass it as an HTTP POST (form) parameter instead, because that is more secure.

The bkvPropertyId parameter must be an integer and is the unique identifier for the property within Bookerville. This value is obtained from the Summary API.

Property Details API Results

The results of a successful Property Details API call will appear as the following example XML:
<Property property_id="19" last_update="2015-04-27 03:41:27"> <PropertyName>Soledad Mansion</PropertyName> <Address> <Address1>316 Mission Drive</Address1> <Address2/> <City>San Diego</City> <State>California</State> <ZipCode>90016</ZipCode> <Country>USA</Country> <LatitudeLongitude/><LatitudeLongitude/> </Address> <Details> <MaximumOccupancy>12</MaximumOccupancy> <PropertyType type="Single Family House"/> <SquareMeters>325</SquareMeters> <SquareFeet>3500</SquareFeet> <Bedrooms count="0"/> <Bathrooms count="0.0"/> <roomConfigurations> <room> <label>Master Bedroom</label> <size>225</size> <sizeMetric>Square Meters|Square Feet</sizeMetric> <ceilingFan>Y|N</ceilingFan> <tv> (integer) </tv> <privateBathroom>Y|N</privateBathroom> <roomType>Bedroom | LivingRoom</roomType> <maxOccupants> (integer) </maxOccupants> <beds> <bed> <size>California King|King|Queen|Full|Twin|Sofa Bed</size> <type>Box Spring|Memory Foam|Hybrid|Waterbed</type> <adjustableHeight>Y|N</adjustableHeight> <adjustableFirmness>Y|N</adjustableFirmness> <heated>Y|N</heated> </bed> </beds> </room> </roomConfigurations> <CheckIn>2:30 pm</CheckIn> <CheckOut>11:00 am</CheckOut> <Currency>USD</Currency> <UnitSize units=""/> </Details> <Description> <PropertyDescription/> <RateDescription/> <LocationDescription/> </Description> <LocalAttractions>LaJolla Shores Beach, LaJolla downtown, SeaWorld, San Diego Zoo, Wild Animal Park, Mt. Palomar, Seaport Village, Balboa Park, Gaslamp District, Mission Bay, Mission Beach, Pacific Beach, LaJolla Windansea Beach, Scripps Aquarium, too much to list here!</LocalAttractions> <Suitability> <Pets value="no"/> <Smoking value="no"/> <HandicapAccessible value="no"/> <Children value="no"/> <Cribs value="2"/> <FloorNumber value="33"/> <Elevator value="yes"/> </Suitability> <Amenities> <Pool value="no"/> <HotTub value="no"/> <AirConditioning value="no"/> <Heating value="no"/> <TVs value="2"/> <!-- Will be number of TVs --> <CableSatellite value="yes"/> <WiFi value="no"/> <WasherDryer value="no"/> <Fireplace value="no"/> <BasketBall value="no"/> <Sandbox value="no"/> <PropertyClass value="no"/> <CeilingFans value="0"/> <HairDryer value="no"/> <Refrigerator value="0"/> <Toaster value="no"/> <CoffeeMaker value="no"/> <IronAndBoard value="no"/> <Blender value="no"/> <Oven value="no"/> <Microwave value="no"/> <DishWasher value="no"/> <Grill value="no"/> <Terrace value="yes"/> <Deck value="yes"/> <Balcony value="yes"/> <BeachFront value="no"/> <LakeFront value="no"/> <RiverFront value="no"/> <BeachView value="no"/> <LakeView value="no"/> <WaterAccess value="no"/> <DistanceToDestination value="no"/> <Destination value="no"/> <Linens value="no"/> <Towels value="yes"/> <Kitchen value="yes"/> <FireExtinguisher value="yes"/> <SmokeDetector value="yes"/> <FreeParking value="yes"/> <AccessBy4WD value="yes"/> <EventsPartiesAllowed value="yes"/> </Amenities> <Photos> <Photo order="1"> <URL>http://192.168.1.2:8080/props/prop19/dscf9879.jpg</URL> </Photo> <Photo order="2"> <URL>http://192.168.1.2:8080/props/prop19/dscf9876.jpg</URL> </Photo> <Photo order="3"> <URL>http://192.168.1.2:8080/props/prop19/dscf9583.jpg</URL> </Photo> <Photo order="4"> <URL>http://192.168.1.2:8080/props/prop19/dscf9593.jpg</URL> </Photo> </Photos> <Currency>USD | EUR | GBP | JPY | AUD | CAD | MXN | DKK | BRL | SEK | THB</Currency> <Rates> <Rate> <Label/> <StartDate>2015-04-01</StartDate> <EndDate>2015-05-31</EndDate> <DailyWeeknightRate>300.00</DailyWeeknightRate> <DailyWeekendRate>400.00</DailyWeekendRate> <WeeklyRate>1800.00</WeeklyRate> <MonthlyRate>6000.00</MonthlyRate> <WeekendNights>Fri|Sat</WeekendNights> </Rate> <Rate> <Label/> <StartDate>2015-06-10</StartDate> <EndDate>2015-09-30</EndDate> <DailyWeeknightRate>600.00</DailyWeeknightRate> <DailyWeekendRate>800.00</DailyWeekendRate> <WeeklyRate>3450.00</WeeklyRate> <MonthlyRate>10350</MonthlyRate> <WeekendNights>Fri|Sat</WeekendNights> </Rate> </Rates> <PerPersonPerNight>20.00</PerPersonPerNight> <FreeGuests>8</FreeGuests> </MultiDayDiscounts> <MultiDayDiscount> <MinNights>14</MinNights> <DiscountType>Percent of Rent</DiscountType> <Discount>25.00</Discount> </MultiDayDiscount> <MultiDayDiscount> <MinNights>7</MinNights> <DiscountType>Percent of Rent</DiscountType> <Discount>15.00</Discount> </MultiDayDiscount> </MultiDayDiscounts> <AutoDiscounts> <AutoDiscount> <DaysOut>20</DaysOut> <DiscountType>Flat Amount</DiscountType> <Discount>100.00</Discount> </AutoDiscount> <AutoDiscount> <DaysOut>15</DaysOut> <DiscountType>Percent of Rent</DiscountType> <Discount>10.00</Discount> </AutoDiscount> </AutoDiscounts> <SecurityDeposit> <Required>yes</Required> <Type>Refundable</Type> <Amount>375.00</Amount> <AmountType>Flat Amount</AmountType> <WaiverAmount>45.00</WaiverAmount> <GuestChoice>no</GuestChoice> </SecurityDeposit> <Taxes> <Tax> <id>1</id> <Label>State</Label> <PriceModel>Percent | Flat Amount | Flat Amount Per Night | Flat Amount Per Guest</PriceModel> <Rate>5.8600</Rate> </Tax> <Tax> <id>2</id> <Label>County</Label> <PriceModel>Percent | Flat Amount | Flat Amount Per Night | Flat Amount Per Guest</PriceModel> <Rate>3.0000</Rate> </Tax> <Tax> <id>3/id> <Label>Local</Label> <PriceModel>Percent | Flat Amount | Flat Amount Per Night | Flat Amount Per Guest</PriceModel> <Rate>2.0000</Rate> </Tax> </Taxes> <bookAheadDays>(integer)</bookAheadDays> <CheckInNotAllowedDates> <Date>20240315</Date> <Date>20240316</Date> <Date>20240317</Date> <Date>20241031</Date> <Date>20241124</Date> </CheckInNotAllowedDates> <WholeBlocksBookedTogether> <WholeBlock> <StartDate>2024-06-23</StartDate> <EndDate>2024-06-30</EndDate> <WholeWeek>true</WholeWeek> </WholeBlock> <WholeBlock> <StartDate>2024-06-30</StartDate> <EndDate>2024-07-07</EndDate> <WholeWeek>true</WholeWeek> </WholeBlock> <WholeBlock> <StartDate>2024-08-31</StartDate> <EndDate>2024-09-03</EndDate> <WholeWeek>false</WholeWeek> </WholeBlock> </WholeBlocksBookedTogether> <MinStays> <MinStay> <StartDate>2015-04-01</StartDate> <EndDate>2015-04-30</EndDate> <MinimumNightsStay>3</MinimumNightsStay> </MinStay> <MinStay> <StartDate>2015-05-01</StartDate> <EndDate>2015-08-31</EndDate> <MinimumNightsStay>7</MinimumNightsStay> </MinStay> <MinStay> <StartDate>2015-09-01</StartDate> <EndDate>2015-10-31</EndDate> <MinimumNightsStay>3</MinimumNightsStay> </MinStay> </MinStays> <Fees> <Fee required="yes"> <Name>Booking Fee</Name> <Description>Booking Fee</Description> <Cost type="Flat Fee">25.00</Cost> </Fee> <Fee required="yes"> <id>25640</id> <!-- Most fees will have an id, sometimes Booking Fee and Cleaning Fee will not --> <Name>Wine and Roses</Name> <Description>A chilled bottle of top-brand wine, and a dozen fresh, beautiful roses will be in your room when you arrive. The perfect touch for a romantic getaway!</Description> <Cost type="Flat Fee">65.00</Cost> </Fee> <Fee required="no"> <id>4652</id> <Name>Heated Pool</Name> <Description>Pool will be heated to 87 degrees during your stay.</Description> <Cost type="Flat Fee Per Night">250.00</Cost> </Fee> <Pre-Payment> <Amount>25.00</Amount> <AmountType>Percent|Flat Amount</AmountType> </Pre-Payment> <CancelationFees> <CancelationFee> <NumDaysToArrival>14</NumDaysToArrival> <fee>90.00%</fee> </CancelationFee> <CancelationFee> <NumDaysToArrival>30</NumDaysToArrival> <fee>50.00%</fee> </CancelationFee> </CancelationFees> </Fees> </Property>

Note: a missing XML field, or a field which has nothing in it, should not be interpreted as "deleting" the existing value in your system, nor overwriting it with blank, null, or zero. If we want to communicate a delete, or overwrite with blank, etc. then it will be positively expressed as such in the XML feed. Best practice for missing or empty XML fields is to simply ignore them - take no action updating your data for it.

<CheckIn> and <CheckOut>: These times will be specified in European/Military format, i.e. "3:30 PM" will be expressed as "15:30".

<Rates>: Bookerville provides a very large degree of flexibility to managers in setting rates. There can be an arbitrary number of <Rate> stanzas, each representing a date-range for which the rates apply. These <Rate> stanzas will never overlap each other though.

Rates are calculated for bookings as follows:

• If monthly rates are specified, price each 28-day contiguous block, starting with the check-in date, with the monthly rate.
  
• If weekly rates are specified, price each remaining 7-day contiguous block with the weekly rate.
  
• Remaining days are each priced with weekday & weekend daily rates. (Fri. and Sat. are weekend nights.)
  

<FreeGuests>: This is the expected number of guests for the standard rates. A booking which has more than this number of guests will be subject to the over-occupancy surcharges. Please note: if zero, then it means this property has no limit to the number of guests which qualify to be covered by the nominal rates. In other words: if this value is zero, simply ignore it.

<PerPersonPerNight>: This is the over-occupancy surcharge if the total number of guests for a booking exceeds the expected occupancy (see <FreeGuests> above). The formula for calculating over-occupancy surcharges is: (total guests - <FreeGuests>) * <PerPersonPerNight>

<MultiDayDiscounts>: Multi-Day Discounts are applied only to remaining days left after monthly and weekly rates have been applied. Only one Multi-Day Discount may be applied per booking: choose the greatest discount that applies.

<AutoDiscounts>: Bookerville's Auto-Discounter allows managers to specify a schedule of increasing discounts as vacant dates get closer. Only one Auto-Discount may be applied per booking: choose the greatest Auto-Discount that applies.

<SecurityDeposit>: This is a potential security deposit. If <Required> is "yes" then it is required, otherwise it is not.

• <Type>: "Refundable" or "Waiver". If "Waiver", then it is not refundable and the amount will be included in the booking total.
  
• <Amount>: Amount of the refundable security deposit.
  
• <AmountType>: "Flat Amount" or "Percent of Rent" - how to interpret the <Amount> field.
  
• <WaiverAmount>: If waiver (or guest option to choose) this will be the (non-refundable) waiver amount.
  
• <GuestChoice>: "yes" or "no". If "yes" then the guest is presented with a choice of either the Refundable Security Desposit, or the non-refundable waiver. Your system may or may not provide such guest options during booking, so you and/or your property manager customer will have to make a decision about what the default security deposit policy will be in your system.
  

<bookAheadDays>: This is the minimum number of days ahead that a guest must book in advance of arriving. A value of zero means they can book the same day as arrival. A value of 1 means guests must book at least one day before the arrival date; 2 means guests must book at least two days before the arrival date, etc.

<MinStays>: these work just like <Rates> - There can be an arbitrary number of <MinStay> stanzas, each representing a date-range for which the minimum-stay applies. These <MinStay> stanzas will never overlap each other though. Please note: the default should be understood to be 1-night min-stay. Any dates for which no MinStay records are shown should be considered to have a 1-night minimum stay.

<BookAheadDays>: The minimum numbver of days in advance of the arrival date that bookings must be made.

<Fees>: These are additional fees to be included in the booking total. Can be optional or mandatory. The Cost "type" can be any of these values:

• Flat Fee
  
• Flat Fee Per Night
  
• Percent of Rent
  
• Flat Fee Per Night Per Guest
  
• Percent of Total
  

There can only be one "Percent of Total" fee. This has been created to handle Travel Insurance, which is typically calculated as a percent of the absolute total of the booking.

<PrePayment>: This stanza contains any pre-payment required to secure a booking.

Property Details API Errors

The results of the Property Details API may contain one or more error stanzas, which are designed to help you debug issues.

Example:
<error>API access token not found</error>

Note that <error> and <warning> stanzas may appear in-line with other XML content. Explanations will be given inside each stanza.