Rentability XML Import Service
Contents
Introduction
The XML import service allows for the creation and updating of Rentability listings via an XML file that conforms to our property XML schema. The schema covers almost all aspects of a Rentability listing including tariffs, features, description and availability (bookings). New listings can be created and existing listings updated. This service will be of most interest to those property managers with existing property/availability databases or websites who want to automatically upload and/or continuously synchronize their existing data with their Rentability account.
Quick links
- The Rentability property XML schema...
- Auto-generated schema documentation...
API key and API console
To use the import service, you need to know your API key. The key should be considered secret and is used to authenticate when uploading your XML file to the Rentability server. To find your API key, navigate to the INTEGRATE section of your account and click on the API tab:
You'll also find a link to your API 'console' page here. The console shows the results of previous uploads and shows you an errors or problems that are occurring.
HTTP POST API
Currently, XML that conforms to our schema can be uploaded to Rentability via an HTTP POST request to the following URL:
https://www.rentability.com/rentability_xml_push
Note that this is an SSL URL. You must use the HTTPS protocol. This URL also requires a basic HTTP authentication header to be present. The login being the Rentability account login (email address) and the password being the API key for that account. The body of the request should be the property XML and the content type should be set to "text/xml".
Response
The response to posting property XML will be a set of error messages for each property that failed to import/update entirely successfully. Below is an example of what to expect:
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<property yourReference="myref_3">
<error>Some kind of error message</error>
</property>
...
</errors>
XML document structure
Basic XML structure:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>my_ref_1</yourReference>
...
</property>
<property>
<yourReference>my_ref_2</yourReference>
...
</property>
</propertyList>
Or if you want to reference your existing properties using their Rentability ID numbers:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<rentabilityId>12345</rentabilityId>
...
</property>
<property>
<rentabilityId>12346</rentabilityId>
...
</property>
</propertyList>
The propertyList root element contains 1 or more property elements. When importing new properties, each property element must have a yourReference element. On subsequent imports (updating existing properties), you can supply either yourReference or rentabilityId (assigned by us) in order to identify the property to update. It it suggested that you use yourReference unless you are updating properties that were added to Rentability manually through the web interface. yourReference is usually the identification value that you use in your source database. You can safely ignore the property number Rentability assigns to your listings but you must ensure that the reference number/value you use for yourReference remains constant.
When updating an existing property, most elements under propertyList are optional. Note that if an element is present, it should be considered an entire replacement for any data supplied previously. For example, if you have an assets element, all existing assets with be deleted and you will need to specify all assets to add your listing. The same applies to tariffs, bookings, features and localInfo.
Basic property details
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
<title>The Pigeonnier</title>
<shortDescription>Peace and calm in the heart of french wine country</shortDescription>
<location>
<countryCode>FR</countryCode>
<region>Aquitaine</region>
<town>Razac-d'Eymet</town>
<coordinates latitude="74.05" longitude="-117.85"/>
</location>
<maxCapacity>6</maxCapacity>
<numBedrooms>3</numBedrooms>
<numBathrooms>1</numBathrooms>
<numDoubleBeds>2</numDoubleBeds>
<numSingleBeds>3</numSingleBeds>
<smokingPermitted>true</smokingPermitted>
<wheelchairAccess>false</wheelchairAccess>
<petsAllowed>false</petsAllowed>
<description>
<text>...</text>
</description>
...
</property>
...
</propertyList>
Assets
The assets element defines all of the photos and videos that should appear on the listing. The actual data for each asset must be publicly accessible via HTTP at the time of import. The showInGallery element controls whether or not the asset is shown in the gallery at the top of the advert.
If you specify an assets element, you must add a mainImage element under the enclosing property element. This is where you specify your main property photo. The main image must refer to a photo asset and not a video.
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<mainImage idref="ID000"/>
<assets>
<asset id="ID000">
<resourceURL>http://www.example.com/photos/123.jpg</resourceURL>
<caption>image caption</caption>
<showInGallery>true</showInGallery>
</asset>
<asset id="ID001">
<resourceURL>http://www.example.com/photos/124.jpg</resourceURL>
<caption>image caption 2</caption>
<showInGallery>true</showInGallery>
</asset>
</assets>
</property>
...
</propertyList>
Property Features
Specify property features with a features element. You can find the list of supported features types in the auto-generated schema documentation.
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<features>
<feature type="video player"/>
<feature type="swimming pool"/>
<feature type="dishwasher"/>
...
</features>
</property>
...
</propertyList>
Tariffs
There are four types of tariff you can add to you listing. Tariffs can either be daily or weekly and have seasons (date ranges with associated price) or not have seasons (fixed price all year). These combinations of options result in four different tariff sub-elements that can be added to your XML.
Prices for season-less tariffs are specified as a minimum and maximum price.
Example of a season-less weekly tariff:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<tariffs>
<weeklyTariff changeover="tuesday" name="Weekly tariff" catering="self catering" currency="EUR">
<minMaxPrices min="1200" max="2000"/>
</weeklyTariff>
</tariffs>
</property>
...
</propertyList>
Example of a season-less daily tariff:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<tariffs>
<dailyTariff name="My daily tariff" catering="self catering" currency="GBP">
<minMaxPrices>
<sun min="100" max="160"/>
<mon min="100" max="160"/>
<tue min="100" max="160"/>
<wed min="100" max="160"/>
<thu min="100" max="160"/>
<fri min="150" max="220"/>
<sat min="150" max="220"/>
</minMaxPrices>
</dailyTariff>
</tariffs>
</property>
...
</propertyList>
Pricing for seasonal tariffs is composed of one of more dates elements that specifies a start and end date and associated pricing for that range of time. Pricing can either be fixed or a minimum and maximum as shown below.
Date ranges can overlap but later dates elements have priority over earlier ones.
You can also mark a date range as unavailable by adding an unavailable element to a dates element instead of pricing (see example below).
Example of a seasonal daily tariff:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<tariffs>
<seasonalDailyTariff name="Daily tariff" catering="self catering" currency="USD">
<dates starts="2008-01-01" ends="2008-03-31">
<minMaxPrices>
<sun min="100" max="100"/>
<mon min="100" max="100"/>
<tue min="100" max="100"/>
<wed min="100" max="100"/>
<thu min="100" max="100"/>
<fri min="140" max="180"/>
<sat min="140" max="180"/>
</minMaxPrices>
</dates>
<dates starts="2008-04-01" ends="2008-06-30">
<prices>
<sun price="200"/>
<mon price="200"/>
<tue price="200"/>
<wed price="200"/>
<thu price="200"/>
<fri price="200"/>
<sat price="200"/>
</prices>
</dates>
<dates starts="2008-07-01" ends="2008-07-20">
<unavailable/>
</dates>
...
</seasonalDailyTariff>
</tariffs>
</property>
...
</propertyList>
Example of a seasonal weekly tariff:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<tariffs>
<seasonalWeeklyTariff changeover="wednesday" name="Weekly tariff" catering="self catering" currency="EUR">
<dates starts="2008-01-01" ends="2008-04-31">
<minMaxPrices min="1000" max="2000"/>
</dates>
<dates starts="2008-02-12" ends="2008-02-20">
<unavailable/>
</dates>
<dates starts="2008-05-01" ends="2009-10-15">
<price price="2600"/>
</dates>
...
</seasonalWeeklyTariff>
</tariffs>
</property>
...
</propertyList>
Bookings
Availability is set by adding bookings to a property. Specify a bookings element to replace all existing bookings. For example:
<?xml version="1.0" encoding="UTF-8"?>
<propertyList ...>
<property>
<yourReference>PROP_5</yourReference>
...
<bookings>
<booking arrives="2008-04-19" nights="10">
<name>Smith</name>
</booking>
<booking arrives="2008-05-11" nights="5">
<notes>Bringing dog</notes>
<name>Wills</name>
</booking>
<booking arrives="2008-05-27" nights="2">
</booking>
</bookings>
</property>
...
</propertyList>