XML Feeds - Technical specification ‎(xml feeds)‎

XML Feeds - Technical specification

This document gives enough information to understand how the homein XML Feeds are structured. This document is aimed to a technical audiance, it assumed that the reader has basic understandings for how XML works.

homein offers you the possibility to create your own XML Feed that our spider will read from your website. We will check your feed for updates every 24 hours once everything is set-up, the only you need to think about once you have given us the url to your feed is to keep your data updated. You can either create an XML feed that followings our specifications described later on in this document or if you already have an XML feed contact us to see if we can integrate it.

Once you're properties have been imported successfully to homein.com your properties will automatically feed out to the sites:

Google Base, http://www.google.com/base
Trovit, http://www.trovit.com
Vast, http://www.vast.com
Nuroa, http://www.nuroa.com

You don't need to do anything to activate this and it's 100% free for you as a homein.com customer. We are constantly working on expanding the visibility of your products.

If you have any questions send our tech team an email on tech@homein.com.

Good luck with the integration,
The homein staff

Versions

Below you can see the versions that have been release of the xml feed.

Version	Date	Description
1.0	19/04/2008	First release of the feed
1.1	18/05/2008	The element <description> has been added, it enables the adding of free text descriptions.
1.2	24/06/2008	<property_condition> is log longer a required element.
1.3	26/10/2008	If the <title> element doesn't exist or is empty the first 100 characters of the <description> element will be used.
1.4	18/02/2009	Documentation update, the feed format remains the same. Now we also syndicate your homein properties to vast.com

XML format

The fastest and safest way to integrate to our system is to use our XML Feed format, this chapter will specify this format.

Your feed must contain all the properties you want to have online, at the moment we don’t support feeds that incrementally add properties. This means that if a property existed in your feed yesterday and today you have removed it from your feed then it will be removed from homein. Note that if you change details about a property in homein’s extranet and then you change it to something differently in your xml feed then the changes you made in the extranet will be overwritten next time the homein spider crawls your feed.

Note that you can start with implementing a feed with only the required elements to get everything up and running quick but to improve the quality of your properties we strongly recommend that you spend some time in also putting in as many as possible of the optional elements. For optional elements that are not specified the default value will be used, default values are indicated later on in this section where every single element is detailed.

The feed must have the <properties> element as a root element, every new property will be represented by a <property> element.

<?xml version="1.0" encoding="UTF-8" ?>
<properties>
<property>
	...required and optional elements defined in this document
</ property>
<property>
	...required and optional elements defined in this document
</ property>
</properties>

Verify that the text that you write into your feed is UTF-8, else some characters might not show up on homein.com.

Required elements

The elements listed in this section must exist for each property in the feed. If they are missing the import will be marked as corrupt.

<title>

The title that will be used for the property. If this element is empty the first 100 characters of the <description> element will be used.
Format:
Text, max 100 chars.

<reference_code>

Reference code you use internally. It’s important to implement this field, it’s the only way for us to be able to update existing properties or to remove properties that should not be online any more. If multiple properties have the same reference code they will overwrite each other.
Format:
Text, max 10 chars.

<listing_section>

Marks where the listing should be shown, rentals or sales.
Format:
Text. Possible values for this element are:

rentals
sales

<property_type>

Kind of property that is being advertised.
Format:
Text. Possible values for this element are:

Studio
Apartment
Attic
Duplex
DetachedHouse
SemiDetachedHouse
TerracedHouse

<street>

The full address to the location of the property, this element is only required when the latitude and longitude are not valid. For example: New oxford street 6, London.
Format:
Text, max 100 chars. The full address can contain the following things:

Street
Street number (optional)
Postcode (optional)
City
Country (optional)

The more you give in the address the easier it will be for us at homein to show your properties on the map.

<longitude>

This marks the longitude for the property; if this value is present also the latitude must be present. If the longitude and the latitude are valid the street field will not be used to decide the map location of the property.
Format:
Number, decimal

<latitude>

This marks the latitude for the property; if this value is present also the longitude must be present. If the longitude and the latitude are valid the street field will not be used to decide the map location of the property.
Format:
Number, decimal

<price>

Price the property is being advertised for. In case of a rental property then this will be the price per month.
Format:
Number (integer).

<size>

The size of of the property expressed in square metres (m2).
Format:
Number (integer).

<bedrooms>

This element indicates number of bedrooms for the property.
Format:
Number (integer).

<bathrooms>

This element indicates number of bathrooms for the property.
Format:
Number (integer).

Optional elements

These elements are optional so if you don’t have these fields don’t worry. Don’t forget that the more information you’re able to give us the more information we will be able to serve you potential customers.

<property_condition>

Format:
Possible values for this element are:

New
Renovated
Original
NeedsWork

<status>

What status the property currently has, note, the status is set to delete then it will no longer be possible to update the property. In order for this field to have any effect you have to define the element <reference_code>.
Format:
Text, default value is “published”. Possible values for this element are:

Online
Paused
Deleted

<description>

A free text description of the property, note that it’s important that the text is html encoded, so for example the & sign should come as & . This is done in the following way:

PHP
$description = htmlspecialchars($description);
C#
// requires that you have a reference to the System.web library
description = System.Web.HttpUtility.HtmlEncode(description);

It’s also recommended to put the text data within a CDATA section.
Format:
Text.

<floor>

Floor the property is on, 0 is the ground floor.
Format:
Number (integer). Values between 0 and 100 accepted.

<parking>

The element indicates if the property has a parking included.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<lift>

Indicator for if the property has a lift or not.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<terrace>

If the property has a terrace.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<terrace_size>

The size of the terrace, if the element terrace is false this element will be ignored.
Format:
Number (integer)

<air_conditioning>

If the property has air-conditioning.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<heating>

If the property has a heating system.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<swimming_pool>

If the property has a swimming pool.
Format:
Text, default value is none. Possible values for this element are:

None
Private
Communal

<garden>

If the property has garden.
Format:
Text, default value is none. Possible values for this element are:

None
Private
Communal

<kitchen>

What kind of kitchen the property has.
Format:
Text, default value is “DoNotSpecify”. Possible values for this element are:

DoNotSpecify
Fitted
OpenPlan
KitchenDinner

<storeroom>

If the property has a storage room.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<flooring>

What kind of floor the property has.
Format:
Text, Possible values for this element are:

ParquetWooden
Ceramic
Cement
MosaicTiling
Various

<wardrobes>

If the property has built-in wardrobes.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<communal_fees>

How much the monthly communal fees are
Format:
Number (integer)

<communal_fee_incl>

Only for “rentals” listings, it indicates if the communal fees are included in the montly rent.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<furnished>

Only for “rentals” listings, it indicates if the property is furnished.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<equipped_kitchen>

Only for “rentals” listings, it indicates if the property has a fully equipped kitchen.
Format:
Boolean, default value is “false”. Possible values for this element are:

true
false

<bills>

Only for “rentals” listings, it indicates if the bills are included in the monthly rent.
Format:
Text, default value is “no”. Possible values for this element are:

No
Yes
Some

<photos> and <photo>

The <photos> element is a container for the <photo> elements. The <photos> element can contain up to 25 <photo> elements for each property. The value of the <photo> should be an absolute url to where the image can be found, try not to link to a thumbnail version of the image. This will decrease the result of your images.

XML Sample:

<photos>
<photo>http://www.myagency.com/photos/property_img1.jpg</photo>
<photo>http://www.myagency.com/photos/property_img2.jpg</photo>
</photos

Sample feed

<?xml version="1.0" encoding="UTF-8" ?>
<properties>
<property>
	<title>Nice beach apartment</title>
	<reference_code>DEMO1234</reference_code>
	<listing_section>sales</listing_section>
	<property_type>Apartment</property_type>
	<description>
	<![CDATA[
Beautiful apartment in Barcelona with terrace &amp; air condition.

The apartment is available for may 2008, the agencys commission is 10% of the total sales price.
]]>
	</description>
	<street>Calle Valencia 218, Barcelona, Spain</street>
	<price>320000</price>
	<property_condition>New</property_condition>
	<size>80</size>
	<bedrooms>3</bedrooms>
	<bathrooms>1</bathrooms>
	<floor>5</floor>
	<parking>false</parking>
	<lift>true</life>
	<terrace>true</terrace>
	<terrace_size>30</terrace_size>
	<swimming_pool>Communal</swimming_pool>
	<photos>
		<photo>http://www.yoursite.com/property/kitchen.jpg</photo>
		<photo>http://www.yoursite.com/property/bath.jpg</photo>
	</photos>
</property>
</properties>