Call us: +39 0577 1656 690 - Email us: info@vacavilla.com

Loading

Vacavilla XML API

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. 

VacaVilla XML API Requests

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.

Request: Available zones in the specified country

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:

https://www.vacavilla.com/webservices/v1/service/searchformhelper/helperservice/zones_in_country/country/ITA/depth/1/api.xml

This request will return the full list of regions of Italy where VacaVilla has at least one vacation home.

Response: Available zones in the specified country

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)

Request: Available subzones in the specified zone

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:

 https://www.vacavilla.com/webservices/v1/service/searchformhelper/helperservice/subzones_in_zone/zone/TOS/depth/1/api.xml

This request will return the list of subzones in Tuscany (TOS) where VacaVilla has at least one vacation home

Response: Available subzones in the specified zone

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

    • 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)

Request: Available towns in the specified zone/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:

https://www.vacavilla.com/webservices/v1/service/searchformhelper/helperservice/towns_in_zone/zone/TOS/api.xml

This request will return the full list of towns in Tuscany where VacaVilla has at least one vacation home.

https://www.vacavilla.com/webservices/v1/service/searchformhelper/helperservice/towns_in_zone/zone/CHI/api.xml

This request will return the full list of towns in Chianti area where VacaVilla has at least one vacation home.

Response: Available towns in the specified zone/subzone

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)

Request: Total List of the Amenities

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

 

Response: Total List of the Amenities

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

 

Request: List of houses

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

https://www.vacavilla.com/webservices/v1/service/searchhouses/start/0/items/10/country/ITA/zone/TOS/data/description:1,amenities:1,pictures:1,prices:1,extraprices:1,calendar:1/api.xml

This request will return all the data of the first ten vacation homes in Tuscany

https://www.vacavilla.com/webservices/v1/service/searchhouses/start/0/items/10/country/ITA/from/06/08/2011/nights/7/api.xml

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

 

Response: List of houses

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

  • groupcode: if the property belongs to a group of apartments here you will find the code that bound them together
  • proptype: contains the type of the property, it can contains "Apartment" or "Independent House"
  • 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

Request: House data

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:

https://www.vacavilla.com/en/webservices/v1/service/viewhouse/data/description:1,amenities:1,pictures:1,prices:1,extraprices:1,calendar:1/house/30230/api.xml

This request will return the full data for the house with id 30230

Response: House Data

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

  • name: this tag contains the name of the current property
  • proptype: contains the type of the property, it can contains "Apartment" or "Independent House"
  • groupcode: if the property belongs to a group of apartments here you will find the code that bound them together
  • 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

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:

  • description: if specified returns the house description in the chosen language
  • amenities: if specified returns the list of the amenities for the specified house
  • pictures: if specified returns the list of the pictures for the house
  • prices: if specified returns all the prices for the property
  • discounts: if specified returns every discoutnavailable for the property
  • extraprices: if specified returns the list of the extra costs for the property
  • calendar: if specified returns the availability calendar for the house

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:

https://www.vacavilla.com/en/webservices/v1/service/viewhouse/data/description:1,amenities:1,pictures:1,prices:1,discounts:1,extraprices:1,calendar:1/house/30230/api.xml

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

The description section response

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"

 

The amenities section response

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”.

The pictures section response

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.

The prices section response

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

The discounts section response

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:

  • value : this is the amount in percentage of the discount to apply to the booking price for every booking that begins between "starttime" and "endtime"
  • mindays : this is the minimum duration of booking for which the discount can be applied, 14 here means that the discount is valid only for bookings of 2 weeks
  • lastminutedays: the discount is valid only for bookings made <lastminutedays> days or less prior arrival date. If today is the 1st of June and <lastminutedays> is set to 15, every booking made today for any date before 15th June must have this discount applied

The extraprices section response

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:

  • description : is the complete description of the extra cost
  • unit: contains the unit of the extra price with it's own unique id, if for example this tag contains "per person" it means that the extra price has to be added once for each person in the booking

  • value : this is the amount to pay to the owner for the extra cost. If “value” is “0.00”, the “value” has not to be shown
  • 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)

The calendar section response

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:

    • means that the date specified is occupied and is not available

    • means that the date specified is blocked and is not available

    • : means that the date specified is unavailable and cannot be booked

    • : 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:

  • startday: the content of this tag states the days of the week on which the house is bookable, each number represent a day of the week starting from 0 = Sunday to 6 = Saturday
  • minstay: the minimum number of days for which the house is bookable, 7 here means that the house can be booked for the minimum of a week
  • minstayadd: if this tag is present contains the minimum number of extra days that can be booked in addition to the minstay value, this value has to be used only if the requested period length is not a multiple of the minstay value, example:
    • minstay = 7, minstayadd = 3, request = 14 -> use minstay since the requested period is twice the minstay
    • minstay = 7, minstayadd = 3, request = 10 -> the request is valid since it's longer than minstay, and adding one minstayadd you get exactly the requested period
    • minstay = 4,  minstayadd = 1, startday = 6,1,2,3,4,5,0 starttime = 07/01/2012, endtime = 04/05/2012 in this case the house can booked for a minimum of 4 days starting from any day of the week in the period starting from 7th January 2012 to 4th May 2012