Search API (draft)
http://api.travelbookingnetwork.com/search.aspx
Terminology
Vendor: The generic term for a destination, business or service that we take bookings for – for example a B&B, hotel, museum, guided tour etc.
Location: A predefined geographical area at the town, city or county level – for example Bath, Greater London, Isle Of Wight. We define these locations and create
new ones from time to time. Vendors can be in one or more location (i.e. Oxford and Oxfordshire). A list of locations can be obtained using our Locations API.
About this API
This API allows you to get a list of all vendors within a given area, together with details of the number of rooms they have available on specified dates and broad
pricing details. If no dates are specified then a list of all vendors that that are “Live” in your partner account within the area will be returned, without querying
their availability.
The area to search within can either be defined as a rectangular map area or by using one of our predefined locations.


Rectangular area: Use a pair of latitude and longitude coordinates to specify the south-west and north-east points of the area.
Location: Specify the ID of the location and all vendors in that location will be searched.
It is possible to supply both an area and a location, in which case the vendor must satisfy both criteria.
Request format
The request is made as an HTTP GET with the following parameters:
Name
Description
Type
partnerid
The partner ID which we will supply to you
Integer
apikey
The API Key which we will supply to you
String
swlat
The latitude of the south-west boundary of your search area
Decimal
swlng
The longitude of the south-west boundary of your search area
Decimal
nelat
The latitude of the north-east boundary of your search area
Decimal
nelng
The longitude of the north-east boundary of your search area
Decimal
locationid
The ID of the location you wish to search in, normally this would be instead of specifying
the four parameters above although you can specify these as well if you wish. A list of
locations can be obtained using our Locations API.
Integer
stay
A value of true or false specifying whether to include places to stay (e.g. B&Bs and hotels)
in the search.
Boolean
rent
As above for rental properties (e.g. holiday lets)
Boolean
visit
As above for places to visit (e.g. museums and gardens)
Boolean
tour
As above for guided tours (e.g. bus tours)
Boolean
arrivaldate
The arrival date in the format yyyy-mm-dd (optional)
Date
nights
The number of nights the customer will be staying for
Integer
orderby
The list of vendors will be ordered by the parameter you specify. Possible values are
default, price, or name. Ordering by price is only available if you have specified an arrival
date and number of nights, since the lowest priced room available is used to determine
the order. The default order is randomised each day to ensure each vendor gets equal
exposure. If this parameter is omitted then default is assumed.
String
Example request specifying geographical area and booking dates:
api.travelbookingnetwork.com/search.aspx?partnerid=123&apikey=abcdef&swlat=51.75018&swlng=-1.25815&nelat=51.75739
&nelng=-1.25223&stay=true&rent=false&visit=true&tour=true&arrivaldate=2012-06-14&nights=2&orderby=default
Example request specifying location and booking dates:
api.travelbookingnetwork.com/search.aspx?partnerid=123&apikey=abcdef&locationid=100
&stay=true&rent=false&visit=false&tour=true&arrivaldate=2012-06-14&nights=2&orderby=default
Example request specifying location without dates
api.travelbookingnetwork.com/search.aspx?partnerid=123&apikey=abcdef&locationid=100&stay=true&rent=false&visit=false&tour=false
Response
An XML document is returned with the following elements:
Name
Description
results
Document root node
Attributes
Type
Container
status
Container
code
The status code – see below
Integer
message
Details for the status code if applicable
String
vendor
id: The ID of the property (String)
Container
name
The name of the vendor
String
type
The type of vendor. Possible values are Stay, Rent, Visit or Tour.
String
location
The location of the vendor (for example Oxford)
postcode
The vendor’s postcode, usually with a space after the outward code
String
summary
A brief summary of the vendor, maximum length 150 characters
String
photourl
The URL of the thumbnail photo for the vendor hosted by us
URL
lat
The latitude of the vendor
Decimal
proximity: Possible values are in or near
String
lng
The longitude of the vendor
Decimal
numavailable
The number of rooms / tickets available on the dates specified
Integer
minprice
The lowest price room / ticket available on the dates specified
Decimal
maxprice
The highest price room / ticket available on the dates specified
Decimal
currency
The currency of the prices, for example GBP or EUR
String
ratingaverage
The average customer rating on a scale of 1 to 5
Decimal
ratingcount
The number of customer ratings
Integer
tbnurl
The URL of the vendor’s page on the Travel Booking Network website
URL
Status codes
Code
Description
0
Success
1
Problem with the search area or location specified
2
Problem with the vendor types specified (stay, rent etc)
3
Problem with the date or number of nights
10
Invalid credentials or authentication error
Example response
<?xml version="1.0" encoding="utf-8"?>
<results>
<status>
<code>0</code>
<message></message>
</status>
<vendor id="sthughs">
<name>St Hugh's College</name>
<type>Stay</type>
<location proximity="in">Oxford</location>
<postcode>OX2 6LE</postcode>
<summary>Whilst not an old college, this college in north Oxford has the advantage of spacious gardens and parking.</summary>
<photourl>http://www.travelbookingnetwork.com/thumbs/st-hughs-thumbnail(3).jpg</photourl>
<lat>51.76699</lat>
<lng>-1.26188</lng>
<numavailable>8</numavailable>
<minprice>37.50</minprice>
<maxprice>52.50</maxprice>
<currency>GBP</currency>
<ratingaverage>4.1</ratingaverage>
<ratingcount>627</ratingcount>
<tbnurl>http://www.travelbookingnetwork.com/vendor/sthughs.aspx</tbnurl>
</vendor>
<vendor id="lmhoxford">
<name>Lady Margaret Hall, Oxford</name>
<type>Stay</type>
<location proximity="in">Oxford</location>
<postcode>OX2 6QA</postcode>
<summary>Lady Margaret Hall, founded in 1878, is located in acres of gardens towards the north of the University.</summary>
<photourl>http://www.travelbookingnetwork.com/thumbs/untitled(2).jpg</photourl>
<lat>51.76468</lat>
<lng>-1.25407</lng>
<numavailable>3</numavailable>
<minprice>45.00</minprice>
<maxprice>68.00</maxprice>
<currency>GBP</currency>
<ratingaverage>4.3</ratingaverage>
<ratingcount>554</ratingcount>
<tbnurl>http://www.travelbookingnetwork.com/vendor/lmhoxford.aspx</tbnurl>
</vendor>
</results>