Multi-Property Search API |
|
 |
The Multi-Property Search API provides the ability to query a Bookerville account for properties within specified dates, and get a list of available properties along with photo thumbs, descriptions, estimated pricing, and links to send a customer to the booking process for each result.
Invoking the Multi-Property Search API
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 xmlPayload Field
The Multi-Property Search API requires that you POST an XML document in a separate HTTP POST (form) key-value pair, called
xmlPayload. The XML document you must submit in this field is as follows:
<bkvAccountId>: This is the Bookerville id of the account which the query is focusing on.
<startDate>: Start date of the availability search. Must use "yyyy-MM-dd" format.
<endDate>: End date of the availability search. Must use "yyyy-MM-dd" format.
<numAdults>: The number of adults. (Required)
<numChildren>: The number of children. (Optional)
<sendResultsAs>: (Optional) The default behavior is that Bookerville will return the results in HTML format, which is the same as the results list of the Multi-Property Search widget. If you prefer to get the data in XML format, so that you can format the display in your own custom HTML, then send in this optional field.
<photoFullSize>: (Optional) The default behavior is that Bookerville will return links to photo
thumbs. If you prefer links to the full-size versions of the photos, send "Y" in this optional field.
<sortField>: (Optional) You may pass in a value of "lastBooked" to sort the results in order of the date of the last booking for each property in the results.
<sortOrder>: (Optional) You may pass in a value of "ASC" (for ascending) or "DESC" (for descending) to control the direction of the sort, when using the sortField (above).
Multi-Property Search API Results
The default behavior will return results that are already display-formatted in HTML, in the same format as the results from the Multi-Property Search widget:
If you passed "xml" in the optional <sendResultsAs> field, then the results of a successful Multi-Property Search API call will appear as the following example XML:
The XML fields above are hopefully mostly self-explanatory, and correspond to the same items you can find in the results of the Multi-Property Search widget. By parsing them out of XML like this, you can then format the data into your own custom HTML to achieve an exact match to blend in with your custom website.
<bookingMessage>: This field will either contain "Ok", or a message indicating why the property either could not be priced, or failed minimum-stay requirements, etc.
<bookingTargetURL>: The URL (link) to offer the guest to click in order to proceed to book the property, with the dates and other items pre-populated.
Multi-Property Search API Exceptions
The results of the Multi-Property Search API may contain <error> stanzas or <warning> stanzas which are designed to help you debug issues. <error> stanzas are fatal, and a "failure" will be returned. <warning> stanzas are not fatal.
Examples:
Note that <error> and <warning> stanzas may appear in-line with other XML content. Explanations will be given inside each stanza.
