Kyero.com Import Specification

This page details the specification of an XML feed to send property information to Kyero.com (en español)

Last modified 16th December 2008 - V2.19 - version information

Getting Started
Overview
Guidelines & Conventions
Outline of Feed Structure
About Character Encoding
Testing the Structure
Testing the Character Encoding
Submitting a Feed for Validation
Automating Property Updates
Getting Help
Version Information

1. Getting Started

Refer to these detailed notes and this sample feed
Create your feed (sections 2 - 5)
Test it (sections 6 and 7)
Submit it to Kyero.com for final validation (section 8)

2. Overview

Your XML feed will contain all the property information for one Kyero.com advertiser account. We match the feed URL you give us to an advertiser account once we validate and approve the feed.

Each feed URL can only contain property information for a single Kyero account or estate agent. If you are creating feeds for multiple estate agents, each one will need to be available on a unique URL.

If you wish to password protect a feed so that it is not publicly available - simply provide the feed URL in one of the following formats:

http://username:password@website.com
ftp://username:password@website.com

We cannot accept a feed URL that requires any manual intervention (such as clicking on a 'confirm' button) because our property feed process is completely automatic.

Your property feed must be an absolute feed of all your property information - not an incremental one. Each time we process a feed, we evaluate it against every property for that account in the Kyero database. Your feed must contain ALL the properties that you want ADDED or UPDATED. It should not contain any properties that you want to DELETE.

When a property is ADDED to your database, there will be a new property record for it in your feed. It will be INSERTED to our database and we will process and store all associated images

If a property is UPDATED in your database, the <date> tag in your feed will change. When we see a change in the <date> tag, the property will be UPDATED in our database and we will process all associated images.

If a property is DELETED from your database, there will be no property record for it in your feed. We DELETE properties and any associated images from our database when there is no matching property record in your feed.

In order to correctly insert, update or delete, we must consistently identify each property as a unique entity in your feed. We do this using the <id> tag which must consistently and uniquely identify each one of your properties.

3. Guidelines & Conventions

You must code your feed to break new tags onto new lines (there's a single-line character limit that our parser can handle) - it also makes it much easier for us to read and troubleshoot your feed. Use \n in the script that creates your XML output. When you view the XML output in a text editor - you should see each tag on a new line. Use the same method for forcing line breaks in the description text for each property or you can use the UTF-8 numeric entity 

In the detailed notes we tell you what tags to use, what they can contain and whether a tag is mandatory or optional.

XML Tags look like this: <beds>4</beds>
Comments look like this: // optional numeric

A tag can be 'optional' or 'mandatory' and can contain 'alpha', 'alphanumeric' or 'numeric' characters. The <date> tag is the only exception where it must be formatted as datetime
YYYY-MM-DD HH:MM:SS

If a tag is permitted to be empty (optional tags) - this can be coded in one of four ways:

<beds></beds>
<beds>0</beds> (where numeric values are permissible)
<beds /> (self-closing)
(complete tag missing)

All tags are CaSe SenSiTiVe and MUST be in lower case throughout:
<DESC> is NOT the same as <desc>

Do not include a 'no image' or 'photo coming soon' image URL for properties where there are no actual property photos.

Do not use any [[CDATA]] tags in your feed as a 'quick fix' for character encoding problems. Please refer to the section About Character Encoding.

4. Outline of Feed Structure

The structure of a fully featured property record is detailed in the right-hand margin of this page. Your feed will contain multiple properties by repeating the structure enclosed by <property></property> for each one.

When building the feed, refer to the detailed notes and the sample xml feed.

5. About Character Encoding

There are five characters which must be encoded if you want to use them in your feed. This is because they have predefined functions in XML: (you could use their numeric entities too).

< - The less than sign (<) - <
> - The greater than sign (>) - >
& - The ampersand (&) - &
' - The single quote or apostrophe (') - '
" - The double quote (") - "

When should they be encoded and when left alone?

For example: <image id="9"> - the quotes are not encoded because they're delimiting an XML attribute within an XML tag.

<desc>A "beautiful" house</desc> - the quotes are encoded because they're part of a text string.

<property> should not be encoded as <property> or <property>

The text string bed & breakfast must be encoded as bed & breakfast or bed & breakfast - in the first instance using a XML entity and, in the second, a numeric entity.

In this example, the XML entity & is the same as it's HTML equivalent. However, in general, HTML entities should not be used in your feed. There should be no HTML entities, tags or formatting anywhere within the feed.

Before submitting a feed to Kyero.com, test it using this character validator, selecting UTF-8 as the encoding scheme.

Confused about character encoding? - Joel on Software has a great article on the subject.

6. Testing the Structure

Once you have a feed ready for processing, test it initially by opening it in a Mozilla browser (Firefox, not Internet Explorer).

If Firefox can display it successfully, it contains no fundamental XML structural errors. If not, Firefox will give you the line number of the feed which contains the first error. Firefox will also reveal basic character encoding problems.

Once you can view the feed in Firefox, visit this XML validator.
If your file is structurally valid, you'll see this message:

Validation Results:
Encoding: Unicode (UTF-8)
XML file is VALID!

Alternatively, you'll receive an error message with some clues about where the problem is. The validator will only report on the first 10 errors so it may be necessary to run the validator multiple times before it validates your file in it entirety.

You can test the validator with this sample feed.

Once you have an XML file that is structurally sound, you're ready to test for character encoding.

7. Testing Character Encoding

Visit this W3.org character validator to validate your feed URL.

Select the encoding type as: UTF-8 (Unicode, worldwide), click Check.

Unfortunately, even when the feed is correctly encoded, you will still receive some errors. At the top of the results page, a correctly validated feed will display either:

This Page Is well-formed XML!
Result: Passed validation

This Page Is Tentatively Valid XML!
Result: Tentatively passed validation

Scroll to the bottom of the results page and, under the title:
Important warnings you'll see this error when the feed has 'Passed validation':

No DOCTYPE found! Checking XML syntax only.

This can be safely ignored. Similarly, when the feed has 'Tentatively passed validation', ignore these other additional warnings:

Missing "charset" attribute for "text/xml" document.

Character Encoding Override in effect!

(You can test for these acceptable errors using this sample feed.)

ALL other errors should be investigated and resolved before submitting a feed to Kyero.

8. Submitting a Feed for Validation

Once you have a feed that passes character encoding validation and XML schema validation, open a new support ticket with your feed URL. (Don't forget to tell us which Kyero.com advertising account the feed is for).

We will validate the feed on a development system and provide you with feedback, normally the same business day.

Please don't submit a ticket for a feed that has structural or character encoding errors. We will refer you back to this document and the specifications and tests detailed here.

9. Automating Property Updates

Once we have successfully tested your feed we will process it manually on the live Kyero.com system and inform you when the properties are visible.

Once your properties are live, we will process your feed every day at approximately 01:30 CET.

It's important to remember that you should ALWAYS use your original property management system to manage your property details, NOT your Kyero.com account. When we process your feed, we REPLACE the information already contained in your Kyero.com account.

This means that if you change property details using your Kyero.com account, these changes will be lost when we next process your feed. However, properties marked as 'incomplete' are an exception to this general rule.

As we process your feed, a property will be marked as 'incomplete' if we cannot recognise each of these pieces of information:

price
province
town
property type

An incomplete property is not visible to the public on Kyero. To make it live, it needs to be updated EITHER from your Kyero.com account OR your original property management system.

When you make changes to properties marked as 'incomplete' from your Kyero.com account, these changes will be remembered - even when we process your feed again.

Rather than 'fix' incomplete properties, the best course of action is to avoid a property being marked as 'incomplete' in the first place. To do this, simply ensure that your property management system contains all the mandatory information fields.

The Kyero.com system uses the official post-office database to identify the exact location of a property. For this reason you might notice slight differences between the location used in your property management system and the one used by Kyero.com

If the Kyero system doesn't recognise where a particular location is, it will mark the property as 'incomplete'. Updating the location using your property management system will ensure that the property is updated correctly on Kyero.com

The property type is taken from your property management system whenever possible. If it is missing or is not recognised by the Kyero.com system, the property will be marked as 'incomplete'. Updating the property type using your property management system will ensure that the property is updated correctly on Kyero.com

The Kyero system has two types of rental property - Holiday Rentals and Long Term Lets. When a property price is specified as 'per week' it is featured in the 'Holiday Rentals' section and when entered as 'per month' it is featured in the 'Long Term Lets' section.

If your property management system does not have a compatible way of specifying such rental periods, all the rental properties from your property management system will be marked as 'incomplete' on Kyero.com. Simply update the rental price and rental term using your Kyero account for each rental property - these changes will be remembered even after we process your feed again.

It might be possible for a property to be available for sale AND to rent within your property management system. The Kyero.com system does not support this feature and will import the property as 'for sale' only.

We suggest creating a duplicate property in your property management system and marking one as a rental property and the other as a property for sale. Do NOT create an extra property from your Kyero.com account because it will be deleted the next time we process your feed.

The Kyero.com system only features Spanish properties. Those which are located outside of Spain or contain no location information will not be imported to Kyero.com If you find that a property is missing on Kyero.com, check on your property management system that it is using a location within Spain and that it is not marked as 'incomplete' in your Kyero.com account.

The Kyero system supports a maximum of ten photos per property. If a property has more than ten photos in your property management system, it will be imported to Kyero.com using the first ten photos only. If you can change the order of photos using your property management system this will be reflected on Kyero.com

10. Getting Help

If you have a problem or question which is not addressed here, or you spot an error in our documentation, please open a new support ticket to contact us in the first instance.

11. Version Information

16/12/2008 - V2.19: Added 'new_build' option to existing <price_freq> tag to accommodate new build and off-plan properties for sale.
<price_freq>sale</price_freq> still used for resale properties.
27/11/2008 - V2.18: <feed_version> changed to 2_1
Added <features> tags to enable automatic language translation of property features.
Added <da>, <it>, <pt> and <ru> language tags in the <desc> node to add full text descriptions for each language.
10/09/2007 - V2.17: Revised specification for testing character encoding with the updated W3C validator.
02/05/2007 - V2.16: Revised specification to remove <primary> tag for images. Added note about ordering images by priority.
19/04/2007 - V2.15: Revised section 5 to use three character numeric entities - Thanks Lucy!. Also added link to Joel on Software article on character encoding.
30/03/2007 - V2.14: Simplified XML schema validator, revised web address, corrected version numbers in this document - Thanks Simon!
Was: globalhideaway.com
Now: http://validator.kyero.com
06/12/2006 - V2.13: Revised notes in section 6 about validation - now using online XSD and feed URL instead of uploading files. Removed reference to character validation of an uploaded file in section 7. Removed links to XSD file.
23/11/2006 - V2.12: Revised notes making <beds>, <baths>, <pool>, <built> & <plot> tags mandatory
12/10/2006 - V2.11: Revised XSD schema to allow property types containing '/' and '-' characters
12/10/2006 - V2.10: Revised XSD schema to pass property types containing spaces
28/09/2006 - V2.09: Revised XSD schema to test that property type tag is not empty
11/07/2006 - V2.08: Revised XSD schema to test for valid <feed_version> and <ref> tags
07/07/2006 - V2.07: Revised notes about forcing line breaks with \n
23/06/2006 - V2.06: Revised notes about UTF-8 character encoding; Removed UTF-8 and ASCII character tables
14/06/2006 - V2.05: Created this page and associated documents; Changed character encoding to UTF-8; Added procedures for schema and character encoding testing; Removed FTP file upload option
12/05/2006 - V2.04: Changed <date> notes to specify standard datetime format
19/04/2006 - V2.03: Added note for <desc> tag about line breaks
07/02/2006 - V2.02: Added <surface_area>, <built> and <plot> tags to property record
24/11/2005 - V2.01: Added notes about encoding & as &; CDATA tag not to be used; Added note about w3.org; Description tag now optional; Added price format notes; Added notes about <leasehold> and <part_ownership> applicable only when <price_freq> is set to 'sale'; Added <primary> image notes; Added note about all tags in lower case; Changed <Kyero> tag to <kyero>
27/05/2005 - V2.00: Initial draft of V2 import specification

Winner of the 2008 & 2007 CNBC award for Best Property Portal Spain and 2007 Best International Property Portal, Kyero.com is the leading web site connecting buyers and sellers of Spanish property. Featuring 100,000 properties from 1,500 estate agents, Kyero.com is privately owned and based in southern Spain.

Kyero.com was the first dedicated Spanish property portal to join the Association of International Property Professionals (AIPP), a consumer association setting standards and protecting buyers of overseas property.