XML Import specification
Details of the XML specification used by Hot-properties24.com to import property details from other systems into Hot-properties24.com.
This page details the specification of an XML feed to send property information to Hot-properties24.com (en español)
Last modified 30th December 2011 – V0.1
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 Hot-properties24.com for final validation (section 8)
2. Overview
Your XML feed will contain all the property information for one Hot-properties24.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 Hot-properties24.com account or estate agent. If you are creating feeds for multiple estate agents, each one will need to be available on a unique URL.
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 Hot-properties24 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 descriptions themselves.
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 datetimeYYYY-MM-DD HH:MM:SS
If a tag is permitted to be empty (optional tags) – this can be coded in one way:
<beds></beds>
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, these will be stripped during import. Please refer to the section About Character Encoding.
4. Outline of Feed Structure
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 this sample xml feed.
When building the feed, refer to the detailed notes and this 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 Hot-properties24.com, test it using this character validator, selecting UTF-8 as the encoding scheme.
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:
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 completely.
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
or
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 Hot-properties24.
8. Submitting a Feed for Validation
Once you have a feed that passes character encoding validation and XML schema validation, update XML URL field in your agent area with your feed URL.
We will validate the feed on a development system and provide you with feedback via email, normally the same business day.
9. Automating Property Updates
Once we have successfully tested your feed we will process it manually on the live Hot-properties24.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.
Feeds that do not conform to our specification or display adverse behaviour may be updated once per week only or disabled.
It’s important to remember that you should ALWAYS use your original property management system to manage your property details.
This means that if you change property details using your Hot-properties24.com account, these changes will be lost when we next process your feed.
The Hot-properties24.com system only features Spanish properties. Those which are located outside of Spain or contain no location information will not be imported to Hot-properties24.com If you find that a property is missing on Hot-properties24.com, check on your property management system that it is using a location within Spain.
