Loading
The VacaVilla xml API is a web service that can be used to query the VacaVilla's vacation homes database in order to use VacaVilla's database of properties on your website.
Each query to the web service returns an XML string containing the requested data, such string can be cached and used as is together with XSL to display an HTML page or used a source of data to be imported into your database.
1. Introduction
3. Request: Available zones in the specified country
a. Response: Available zones in the specified country
4. Request: Available subzones in the specified zone
a. Response: Available subzones in the specified zone
5. Request: Available towns in the specified zone/subzone
a. Response: Available towns in the specified zone/subzones
6. Request: Total List of the Amenities
a. Response: Total List of the Amenities
a. The description section response
b. The amenities section response
c. The pictures section response
d. The prices section response
e. The discount section response
f. The extraprices section response
g. The calendar section response
A request to the VacaVilla XML API takes the following form:
www.vacavilla.com/[language code]/webservices/v1/[parameters]/currency/[currency code]/api.xml
The first parameter is the language code for the request, any text in the response (such as the property descriptions) will be in the specified language. the available codes are: en (english), it (italian), de (german), fr (french)
The string contained in [parameters] determines the kind of data you are asking and expect in return
"currency code" contains the code of the currency for the prices, currently EUR for Euro.
This request s used to retrieve the available zones for the given country, their names and VacaVilla's codes.
Parameters:
service/searchformhelper (required)
this parameter specifies the kind of service you are requesting, in this case you are using our search form helper service
helperservice/zones_in_country (required)
this parameter says that you are asking for a list of zones in the specified country
country/[country code] (required)
this parameter specifies the country that you are requesting, the cod must be specified in the three chars ISO code (ie. ITA for Italy, or ESP for Spain)
depth/[number] (required)
this parameter specifies the depth of the request, that means that if a depth of 1 is specified the returned list will contain all the regions for the requested country, if a depth higher than 1 is specified the API will also return sub-zones (like Chianti in Tuscany for example)
Example:
This request will return the full list of regions of Italy where VacaVilla has at least one vacation home.
The response for the "zones in the specified country" request will be like the following one:
<zonelist>
<zone code="ABR" ne="42.7188800,14.7533918" sw="41.6607151,12.7044416">
<name>Abruzzo</name>
</zone>
</zonelist>
Response elements:
zone: the zone tag represent a zone in the database and contains three attributes:
code: VacaVilla's code for the zone, this is the code you will need when you need to specify a zone in other queries
ne: the Google maps north-east bound of the zone
sw: the Google maps south-west bound of the zone
name: the name tag is the human-readable name of the zone. the name is in the zone's country language (ie. Toscana and not Tuscany)
This request s used to retrieve the available subzones for the given zone, their names and VacaVilla's codes.
Parameters:
service/searchformhelper (required)
this parameter specifies the kind of service you are requesting, in this case you are using our search form helper service
helperservice/subzones_in_zone (required)
this parameter says that you are asking for a list of zones in the specified country
zone/[zone code] (required)
this parameter specifies the zone that you are requesting, the code must be a valid VacaVilla zone code that can be retrieved using the "Available zones in country" request
depth/[number] (required)
this parameter specifies the depth of the request, that means that if a depth of 1.
Example:
This request will return the list of subzones in Tuscany (TOS) where VacaVilla has at least one vacation home
The response for the "subzoness in the specified zone" request will be like the following one:
<zonelist>
<zone code="ARE" ne="43.667872,12.238312" sw="43.19116,11.31546">
<name>Arezzo e dintorni</name>
</zone>
<zone code="CHI" ne="43.77506035,12.0506286" sw="43.2402007,10.91766357">
<name>Chianti</name>
</zone>
</zonelist>
Response elements:
zone: the zone tag represent a zone in the database and contains three attributes:
code: VacaVilla's code for the subzone, this is the code you will need when you need to specify a zone in other queries
ne: the Google maps north-east bound of the subzone
sw: the Google maps south-west bound of the subzone
This request is used to retrieve the available towns for the given zone/subzone
Parameters:
service/searchformhelper (required)
this parameter specifies the kind of service you are requesting, in this case you are using our search form helper service
helperservice/towns_in_zone (required)
this parameter says that you are asking for a list of towns in the specified zone
zone/[zone code] (required)
this parameter specifies the zone that you are requesting, the code must be a valid VacaVilla zone code that can be retrieved using the "Available zones in country" and from "Available subzones in a zone“
Examples:
This request will return the full list of towns in Tuscany where VacaVilla has at least one vacation home.
This request will return the full list of towns in Chianti area where VacaVilla has at least one vacation home.
The response for the "towns in the specified zone" request will be like the following one:
<townlist>
<town>Albinia</town>
<town>Ambra</town>
</townlist>
Response elements:
town: the name of the town, the value of the tag is in the town's country language (ie. Firenze and not Florence)
This request is used to retrieve the total list of the amenities used to describe VacaVilla's properties.
Parameters:
· service/getamenitieslist (required)
this parameter specifies the kind of service you are requesting, in this case you are using our amenities list service
Example:
https://www.vacavilla.com/webservices/v1/service/getamenitieslist/api.xml
The response for the "total list of the amenities" request will be like the following one:
<amenities>
<amenity code="34">
<name>Wood-fire Heating</name>
<description/>
<categories>
<category>
<name>Equipment</name>
<description/>
</category>
</categories>
</amenity>
<amenity code="17">
<name>Well-equipped garden</name>
<description/>
<categories>
<category>
<name>Equipment</name>
<description/>
</category>
</categories>
</amenity>
.
.
</amenities>
Response elements:
amenity: the amenity tag represent an amenity and contains three attributes:
o code: VacaVilla's code for the amenity, this is the code you will find in the property’s data
o name: is the amenity
o category name: is the name of the category to which the amenity belongs
The tag names are self-explanatory, the "amenities" tag contains any number of "amenity" tags, each one of these tags has a "code" attribute, a "name", a "description" and any number of "category" to which the “amenity” may belong
This request is used to retrieve a list of houses, various parameter can be used to filter and restrict the list
Parameters:
service/searchhouses (required)
this parameter specifies the kind of service you are requesting, in this case you are using our vacation homes search engine
country/[country code] (required)
this parameter specifies the country that you are requesting, the code must be specified in the three chars ISO code (ie. ITA for Italy, or ESP for Spain)
start/[number] (required)
the record number from which you want the list to start, 0 for the beginning ( 10 if you want to skip the first ten results and start the list from the 11th vacation home)
items/[number] (required)
the number of items you want to retrieve, keep in mind that the higher this value the longer it will take to complete the request. Use “0” if you want to retrieve ALL the properties
zone/[zone code] (optional)
this parameter specifies the zone that you are requesting, the code must be a valid VacaVilla zone code that can be retrieved using the "Available zones in country" request
town/[town name] (optional)
this parameter specifies the town that you ae requesting, the name must be valid on VacaVilla's database and can be retrieved using the "Available towns in zone request"
radius/[number] (optional)
if a town is specified you can also specify a max. distance in km, that will list all the vacation homes that are at max that specified distance from the town
from/[dd/mm/yyyy]/nights/[number] (optional)
restricts the search only to those houses that are available from the date specified for the specified number of nights
sleeps/[number] (optional)
retrieve only the houses that have that minimum specified sleeps
data/[data sections] (optional)
tells the webservice to return the specified data section (see. "data" paragraph)
Examples:
https://www.vacavilla.com/webservices/v1/service/searchhouses/start/0/items/0/country/ITA/api.xml
This request will return ALL the vacation homes in Italy
This request will return all the data of the first ten vacation homes in Tuscany
This request will return the first ten vacation homes available from the August 6th 2011 for 7 nights
WARNING:
this request may take a long time if you request ALL the database using all the available "data" parameters and no limits specified in "start" and "items", to avoid possible timeouts and failures, the following url provides a daily snapshot of the full database:
www.vacavilla.com/[en|de|fr|it]/webservices/v1/service/searchhouses/affcode/[affiliate_code]/data/description:1,amenities:1,pictures:1,prices:1,extraprices:1,calendar:1/ start/0/items/0/currency/[EUR|USD]/api.xml
The response for the "list of houses" request will be like the following one:
<propertylist>
<property id="29121" nref="VV29121">
<name>Barbiana 2</name>
<groupcode/>
<proptype>Apartment</proptype>
<stars>5</stars>
<zone>Toscana</zone>
<town>Vicchio</town>
<zipcode>50039</zipcode>
<stateprovince>FI</stateprovince>
<country>ITA</country>
<countryname>Italia</countryname>
<latitute>43.9880395</latitute>
<longitude>11.5020752</longitude>
<minsleeps>4</minsleeps>
<maxsleeps>5</maxsleeps>
<totalbedrooms>2</totalbedrooms>
<doublebedrooms>2</doublebedrooms>
<singlebedrooms>0</singlebedrooms>
<bathrooms>1</bathrooms>
<bathroomsshower>0</bathroomsshower>
<bookinglink>
nc/book0/startdate/1312628460/nights/7/house/29121.html
</bookinglink>
<houselink>
vacation-home/startdate/1312628460/nights/7/house/29121.html
</houselink>
<selectedprice starttime="1312628460" endtime="1313233260">
<value>1330</value>
<discountvalue>1330</discountvalue>
<currency>EUR</currency>
</selectedprice>
<pricestart starttime="08/01/2011" endtime="15/04/2011">
<value>100</value>
<discountvalue>100</discountvalue>
<currency>EUR</currency>
</pricestart>
</property>
<propertylist>
Response elements:
property: this tag contains the details for every property in the list, it contains two items: "id" is the house id you'll have to use to request the house details, and "nref" is the VacaVilla's public reference code
name: this tag contains the name of the current property
stars: contains the rating level expressed with a number from 1 to 5 where 5 is the highest level
zone: contains the human-readable name of the zone. the name is in the zone's country language (ie. Toscana and not Tuscany)
town: the name of the town, the value of the tag is in the town's country language (ie. Firenze and not Florence)
zipcode: the zipcode of the property
stateprovince: the state or province of the property (ie. FI for Florence)
country: the country of the property, the code is specified in the three chars ISO code (ie. ITA for Italy, or ESP for Spain)
latitude: the latitude of the property expressed in a format suitable for Google Maps
longtude: the latitude of the property expressed in a format suitable for Google Maps
minsleeps: the minimum number of sleeps of the property
maxsleeps: the maximum number of sleeps of the property
totalbedrooms: the total number of bedrooms
doublebedrooms: the number of double bedrooms
singlebedrooms: the number of single bedrooms
bathrooms: the number of bathrooms
bathroomsshower: the number of bathrooms with shower
bookinglink: the link of the booking page for the property on the VacaVilla's website, simply pre-pend "https://www.vacavilla.com/" to this path to obtain the full URL
houselink: the link of the details page for the property on VacaVilla's website, simply pre-pend "https://www.vacavilla.com/" to this path to obtain the full URL
selectedprice: this tag is present only if you have requested a specific start time and duration for the request, and contains the full price for the requested period. The tag has two properties "starttime" and "endtime" that contains the starting date and ending date for the current price
value: contains the price
discountvalue: the price with any discount applied, if the property has a special discount available for the selected period this value will be different from the one in "value"
currency: this tag contains the currency of the current price
pricestart: this tag is present only if you haven't specified any start time and duration for the request and contains the lowest daily price for the property. The tag has two properties "starttime" and "endtime" that contains the starting date and ending date for the current price
value: contains the price
discountvalue: the price with any discount applied, if the property has a special discount available for the selected period this value will be different from the one in "value"
currency: this tag contains the currency of the current price
This request is used to retrieve a single house.
Parameters:
service/viewhouse (required)
this parameter specifies the kind of service you are requesting, in this case you are using the service to display a single house
house/[house id] (optional)
this parameter specifies the id of the house you are requesting, you can find this id in the response of the searchhouses service, it's the id attribute of the property tag
data/[data sections] (optional)
tells the webservice to return the specified data section (see. "data" paragraph)
Example:
This request will return the full data for the house with id 30230
The response for the "house data" request will be like the following one:
<propertylist>
<property id="29121" nref="VV29121">
<name>Barbiana 2</name>
<groupcode/>
<proptype>Apartment</proptype>
<stars>5</stars>
<zone>Toscana</zone>
<town>Vicchio</town>
<zipcode>50039</zipcode>
<stateprovince>FI</stateprovince>
<country>ITA</country>
<countryname>Italia</countryname>
<latitute>43.9880395</latitute>
<longitude>11.5020752</longitude>
<minsleeps>4</minsleeps>
<maxsleeps>5</maxsleeps>
<totalbedrooms>2</totalbedrooms>
<doublebedrooms>2</doublebedrooms>
<singlebedrooms>0</singlebedrooms>
<bathrooms>1</bathrooms>
<bathroomsshower>0</bathroomsshower>
<bookinglink>
nc/book0/startdate/1312628460/nights/7/house/29121.html
</bookinglink>
<houselink>
vacation-home/startdate/1312628460/nights/7/house/29121.html
</houselink>
<selectedprice starttime="1312628460" endtime="1313233260">
<value>1330</value>
<discountvalue>1330</discountvalue>
<currency>EUR</currency>
</selectedprice>
<pricestart starttime="08/01/2011" endtime="15/04/2011">
<value>100</value>
<discountvalue>100</discountvalue>
<currency>EUR</currency>
</pricestart>
</property>
<propertylist>
Response elements:
property: this tag contains the details for every property in the list, it contains two properties: "id" is the house id you'll have to use to request the house details, and "nref" is the VacaVilla's public reference code
stars: contains the rating level expressed with a number from 1 to 5 where 5 is the highest level
zone: contains the human-readable name of the zone. the name is in the zone's country language (ie. Toscana and not Tuscany)
town: the name of the town, the value of the tag is in the town's country language (ie. Firenze and not Florence)
zipcode: the zipcode of the property
stateprovince: the state or province of the property (ie. FI for Florence)
country: the country of the property, the code is specified in the three chars ISO code (ie. ITA for Italy, or ESP for Spain)
latitude: the latitude of the property expressed in a format suitable for Google Maps
longtude: the latitude of the property expressed in a format suitable for Google Maps
minsleeps: the minimum number of sleeps of the property
maxsleeps: the maximum number of sleeps of the property
totalbedrooms: the total number of bedrooms
doublebedrooms: the number of double bedrooms
singlebedrooms: the number of single bedrooms
bathrooms: the number of bathrooms
bathroomsshower: the number of bathrooms with shower
bookinglink: the link of the booking page on for the property on the VacaVilla's website, simply pre-pend "https://www.vacavilla.com/" to this path to obtain the full URL
houselink: the link of the details page for the property on VacaVilla's website, simply pre-pend "https://www.vacavilla.com/" to this path to obtain the full URL
selectedprice: this tag is present only if you have requested a specific start time and duration for the request, and contains the full price for the requested period. The tag has two properties "starttime" and "endtime" that contains the starting date and ending date for the current price
value: contains the price
discountvalue: the price with any discount applied, if the property has a special discount available for the selected period this value will be different from the one in "value"
currency: this tag contains the currency of the current price
pricestart: this tag is present only if you haven't specified any start time and duration for the request and contains the lowest daily price for the property. The tag has two properties "starttime" and "endtime" that contains the starting date and ending date for the current price
value: contains the value of the price
discountvalue: the value f the price with any discount applied, if the property has a special discount available for the selected period this value will be different from the one in "value"
currency: this tag contains the currency of the current price
In addition to the data above the service will return the various data sections specified with the "data" parameter (see the specific "data" paragraph)
The "data" parameter is a special parameter available in the "house list" and "house data" services and allows you to specify which kind of data you want to receive in addition to the basic house data, you can choose between the following six options:
To make a full data request use the data parameter in the following format:
data/description:1,amenities:1,pictures:1,prices:1,discounts:1,extraprices:1,calendar:1
this command instruct the service to return all the data for all the parameters.
Example:
The request above returns all the data for the property with id 30230
https://www.vacavilla.com/en/webservices/v1/service/viewhouse/data/calendar:1/house/30230/api.xml
The request above will return the base house data and the full availability
If you have specified the "description:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<descriptions>
<description>
Delightful house that has been divided into 2 apartments in the hills that rise above the Arno valley. In the lower part of the fenced-in property there is the owners' house who you share the access with. The accommodation's hillside position offers you a broad view of the countryside that reaches the Chianti hills and the Pratomagno and Vallombrosa mountains. The area is characterized by Romanesque churches and ancient farms. On the terraced land with olive trees you will find a jacuzzi bath (2x2) and areas equipped with table and chairs for outdoor dining as well as a barbecue. Shared washing machine and dryer in an adjacent room. A provincial road passes approx. 50 m below the property. Beauty treatments and access to a small fitness room are possible on request. Simple but cosy and complete furnishings, characterized by walls lined with wood. Parking on the street. PLEASE NOTE: Arrivals must take place between 5.00 p.m. and 7.00 p.m.;
</description>
<interior>
ACCOMODATION: (70 m2) Gr. fl.: living/dining room (satellite TV, hi-fi) with double divan bed, kitchen corner (oven, freezer), 1 bathroom with shower. 1st fl . (access by means of a spiral stairway): small lounge/study (TV) with double sofa bed and access to a small rooftop terrace, 1 double bedroom with an additional 3rd bed
</interior>
<distances>
LOCATION: 0.3 km grocery shops, 2 km horse riding, 3 km Reggello (all kinds of shops and sport facilities), 4 km brand name outlet, 9 km Figline, 10 km the motorway toll booth, 33 km golf course, 27 km Florence, 46 km Arezzo, 65 km Siena
</distances>
</descriptions>
The house descriptions are divided in three different paragraph divided by general “description", "interior” description and "distances"
If you have specified the "amenities:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<amenities>
<amenity code="248">
<name>Countryside</name>
<description/>
<categories>
<category>
<name>Kind of Holiday</name>
<description/>
</category>
</categories>
</amenity>
<amenity code="267">
<name>Parking</name>
<description/>
<categories>
<category>
<name>Equipment</name>
<description/>
</category>
</categories>
</amenity>
<amenity code="27">
<name>Horse-riding</name>
<description/>
<value>2</value>
<metrics>km</metrics>
<categories>
<category>
<name>Activities</name>
<description/>
</category>
</categories>
</amenity>
<amenity code="16">
<name>Golf course</name>
<description/>
<value>33</value>
<metrics>Km</metrics>
<categories>
<category>
<name>Activities</name>
<description/>
</category>
</categories>
</amenity>
<amenity code="41">
<name>Satellite TV</name>
<description/>
<categories>
<category>
<name>Equipment</name>
<description/>
</category>
</categories>
</amenity>
</amenities>
The tag names are self-explanatory, the "amenities" tag may contain any number of "amenity" tags, each one of these tags has a "code" attribute, a "name", a "description" and any number of "category" to which the “amenity” may belong. Each "amenity" tag may have a "value" and "metrics" tags, if present these two represent the value of the amenity. In the example above the "Horse-Riding" is 2Km far away of the house, while the "grading" (the level of the house) is of 3 out of “/5”.
If you have specified the "pictures:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<pictures>
<mainpicture path="https://www.vacavilla.com/uploads/tx_uservacationhomes/DSCF29142__1024x768__OK_01.JPG">
<description/>
</mainpicture>
<picture path="https://www.vacavilla.com/uploads/tx_uservacationhomes/DSCF29142__1024x768__OK_01.JPG">
<description/>
</picture>
</pictures>
Inside the "pictures" tag you may find any number of "picture" each with the "path" attribute that specifies the full URL for each picture, you may also find a description if the picture has one.
There will always be only one "mainpicture" that specifies which picture has to be showed as the first picture for the house.
If you have specified the "prices:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<prices>
<price starttime="08/01/2011" endtime="15/04/2011">
<value>60</value>
<discountvalue>60</discountvalue>
<currency>EUR</currency>
<fixed>0</fixed>
<incwe>-1</incwe>
<maxdays>28</maxdays>
</price>
</prices>
Inside the "prices" tag you may find any number of "price" tags, the data inside the "price" tag is valid only between the "starttime" and "endtime" attribute of the tag, the date inside those attributes is specified in the format DD/MM/YYYY.
Each "price" tags contains the following tags:
value : this is the amount of the daily price for the period specified by "starttime" and "endtime"
discountvalue : if a discount is available for the current price here you will find the discounted amount
currency : this tag specifies the currency for the "value" and "discountvalue" tags
fixed : if this tag contains the value "1" this price has to be added only once to the booking and not multiplied for each day of the booking duration
incwe : not used
maxdays : this is the max number of days for which you can multiply the daily price, in practice if you have a request longer than "maxdays" you have to use "value" * "maxdays" as the booking amount
If you have specified the "discounts:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<discounts>
<discount starttime="0" endtime="0">
<value>12.00</value>
<mindays>21</mindays>
<lastminutedays>0</lastminutedays>
</discount>
</discounts>
Inside the "discounts" tag you may find any number of "discount" tags, the data inside the "discount" tag is valid only for booking whose start date is between the "starttime" and "endtime" attribute of the tag, the date inside those attributes is specified in the format DD/MM/YYYY, if the date is 01/01/1970, it means that the discount is always valid and there are no time restrictions.
Each "discount" tag contains the following tags:
If you have specified the "extraprices:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<extracost>
<included>
<price starttime="08/01/2011" endtime="06/01/2012">
<description>
Linen with weekly change unless otherwise indicated in the description
</description>
</price>
</included>
<extra>
<price id="4" starttime="08/01/2011" endtime="06/01/2012">
<description>
Deposit in cash (to be handed over on arrival) fixed price
</description>
<unit id="6">fixed price</unit>
<value>100.00</value>
<currency>EUR</currency>
<rules>2</rules>
</price>
</extra>
</extracost>
Inside the "extracost" tag you will also find two sections, the "included", that contains the costs included in the booking price, and the "extra", that contains the extra costs to pay for the booking directly to the owner of the house and not included in the booking price.
Inside the "extra" and the "included" sections you may find any number of "price" tags. The data inside the "price" tag is valid only between the "starttime" and "endtime" attributes, but if their value is “01/01/1970” the extra cost is always valid. The date inside those attributes is specified in the format DD/MM/YYYY. The "id" attribute of the price tag is the unique id of that kind of extra price.
Each "price" tags may contain the following tags:
currency : this tag specifies the currency for the "value" tag. If “value” is “0.00” the “currency” has not to be shown
rules: this tag is the valid rule for the extra cost
0 - means that the extra cost has to be paid "upon consumption" by the client, directly to the owner of the house
2 - means that the extra cost (the “value” in “currency” if not “0.00”) has to be paid directly to the owner of the house. (IT'S A MANDATORY COST)
3 - means that the cost (the “value” in “currency” if not “0.00”) has to be paid directly to the owner of the house, but only if explicitly requested to the owner himself (IT ISN'T A MANDATORY COST)
If you have specified the "calendar:1" option in the "data" parameter you will receive a response like the following one (in addition to the basic house data and the other data section requested):
<calendar>
<status date="20110819">B</status>
<status date="20110820">B</status>
<status date="20110821">B</status>
<status date="20110822">B</status>
<status date="20110823">B</status>
</calendar>
<bookingconditions>
<condition starttime="08/01/2011" endtime="06/01/2012">
<startday>6</startday>
<minstay>7</minstay>
</condition>
<condition starttime="07/01/2012" endtime="04/05/2012">
<startday>6,1,2,3,4,5,0</startday>
<minstay>4</minstay>
<minstayadd>1</minstayadd>
</condition>
<condition starttime="22/09/2012" endtime="04/01/2013">
<startday>6,1,2,3,4,5,0</startday>
<minstay>4</minstay>
<minstayadd>1</minstayadd>
</condition>
</bookingconditions>
Inside the "calendar" tag you may find any number of "status" tag, each with its own "date" attribute that identifies the day for which the "status" tag states the availability, that may be any of the following value:
O : means that the date specified is occupied and is not available
B : means that the date specified is blocked and is not available
U : means that the date specified is unavailable and cannot be booked
A : means that the date specified is available and can be booked
Inside the "bookingconditions" tag you may find any number of "condition" tag each with its own "starttime" and "endtime" attribute that identifies the period in which the booking condition is true. Each condition contains the criteria that must be satisfied by the request to be valid for the current house, they are:
