Documents
Resources
Learning Center
Upload
Plans & pricing Sign in
Sign Out
Your Federal Quarterly Tax Payments are due April 15th Get Help Now >>

realestate

VIEWS: 37 PAGES: 14

									realestate.com.au REAXML Functional Specification - Version 2.0




                       COMMERCIAL IN CONFIDENCE




realestate.com.au
REAXML Functional Specification



Version 2.0




Commercial in Confidence                 Page 1 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




Table of Contents

1      DOCUMENT CONTROL .................................................................................... 3
    1.1      VERSION SCHEDULE ..................................................................................... 3
    1.2      REVIEW LIST ................................................................................................ 3
    1.3      SIGN OFF ..................................................................................................... 3
2      INTRODUCTION................................................................................................ 4
3      DATA REQUIREMENTS ................................................................................... 5
    3.1    NEW LISTING REQUIREMENTS ....................................................................... 5
      3.1.1     residential ............................................................................................ 5
      3.1.2     rental .................................................................................................... 5
      3.1.3     rural ..................................................................................................... 6
      3.1.4     land ...................................................................................................... 6
      3.1.5     commercial .......................................................................................... 6
      3.1.6     business............................................................................................... 6
    3.2    UPDATE LISTING REQUIREMENTS .................................................................. 8
    3.3    FILE REQUIREMENTS..................................................................................... 8
      3.3.1     File Names: .......................................................................................... 8
      3.3.2     Compressed Files: ............................................................................... 8
    3.4    DATA REQUIREMENTS ................................................................................... 8
      3.4.1     Date & Time format: ............................................................................. 8
      3.4.2     Images: ................................................................................................ 9
      3.4.3     Suburb Names: .................................................................................... 9
      3.4.4     businessCategory and businessSubCategory values: .......................... 9
4      FUNCTIONAL OVERVIEW .............................................................................. 10
    4.1      DATA EXPORT AND FTP UPLOAD ................................................................. 10
    4.2      LOG FILES .................................................................................................. 11
    4.3      SYSTEM AVAILABILITY ................................................................................. 11
5      XML STRUCTURE .......................................................................................... 12
    5.1    PROPERTYLIST.DTD .................................................................................... 12
      5.1.1   Document Validity: ............................................................................. 12
      5.1.2   Document Well-Formedness: ............................................................. 12
    5.2    ELEMENTS: ................................................................................................. 12
      5.2.1   Username and Password: .................................................................. 12
      5.2.2   Agent ID: ............................................................................................ 13
      5.2.3   Unique ID: .......................................................................................... 13
      5.2.4   Images: .............................................................................................. 13




Commercial in Confidence                              Page 2 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




1 Document Control

1.1 Version Schedule

Version:       Date:              Prepared By:           Comments
1.0            26 July 2001       Chris Naunton          Final Release
1.1            22 Aug 2001        Chris Naunton          Updated data requirements
1.2            14 Sep 2002        Evan Karantonis        Commercial Listings modification
1.4            20 Feb 2003        Evan Karantonis        Added Extra Fields for specialised
                                                         setups
1.5            22 Sep 2003        Kristin Faulkner       Updated Data Requirements
2.0            21 Jan 2007        Doug McNestrie         Commercial Listings modifications



1.2 Review List

Date:                           Name:                             Position:




1.3 Sign Off

Date:                           Name:                             Position:




Commercial in Confidence                 Page 3 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




2 Introduction

This specification outlines the functionality of the REAXML system. The system
collects listing data from agents and imports the data into the REA database. The
data is then incorporated into property listings on the website.




Commercial in Confidence                 Page 4 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




3 Data Requirements
The following requirements are enforced by the system and must be adhered to.


3.1 New Listing Requirements

Each new property listing must contain certain required elements, as specified
below. Element definitions and validation checks for those elements can be found at:
http://www.reaxml.realestate.com.au/reaxml1-xml-format.html. Please ensure this is
referred to for each element. Some elements have dependencies and data
requirements.

Note that the propertyList DTD does not define many of these elements as
mandatory, even though they are required for new listings. This is because the DTD
allows for the case where the listing updates an existing property: in this case, only
the updated or changed elements need to be included. See the section below.


3.1.1 residential
A new residential listing requires at least the following elements:

       modTime and status (both attributes of residential)
       agentID
       uniqueID
       authority
       price
       full address, streetNumber, street, suburb, state/region and correct postcode
        (Aus Only)
       category
       headline
       description
       images, with at least one img
       bathroom
       bedroom


3.1.2   rental

       modTime and status (both attributes of rental)
       agentID
       uniqueID
       rent
       dateAvailable
       full address, streetNumber, street, suburb, state/region and correct postcode
        (Aus Only)
       category
       headline
       description
       bathroom


Commercial in Confidence                 Page 5 of 14
realestate.com.au REAXML Functional Specification - Version 2.0



       bedroom


3.1.3   rural

       modTime and status (both attributes of rural)
       agentID
       uniqueID
       authority
       price
       full address, streetNumber, street, suburb, state/region and correct postcode
        (Aus Only)
       ruralCategory
       headline
       description


3.1.4   land

       modTime and status (both attributes of land)
       agentID
       uniqueID
       price
       full address, streetNumber, street, suburb, state/region and correct postcode
        (Aus Only)
       landCategory
       headline
       description


3.1.5   commercial

       modTime and status (both attributes of commercial)
       agentID
       uniqueID
       commercialAuthority
       commercialListingType (sale OR rent OR both)
       IF sale: price
       IF rent: commercialRent
       Full address, streetNumber, street, suburb, state/region and correct postcode
        (Aus Only)
       commercialCategory
       headline
       description


3.1.6   business

       modTime and status (both attributes of business)
       agentID
       uniqueID
       commercialListingType (sale OR rent OR both)


Commercial in Confidence                 Page 6 of 14
realestate.com.au REAXML Functional Specification - Version 2.0



       IF sale: price
       IF rent: businessLease
       address: suburb, state and correct postcode (Aus Only)
       businessCategory
       headline
       description




Commercial in Confidence                 Page 7 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




3.2 Update Listing Requirements

For listings that merely update an existing property listing only the following elements
are required for each type of listing:

       modTime and status (attributes)
       agentID
       uniqueID

Plus the updated or changed elements themselves.



3.3 File Requirements
3.3.1 File Names:
File names shall conform to the following:

    1. The name shall begin with the Agent‟s username / Agent ID;
    2. The name must be unique for each file; and
    3. The name must not contain spaces.

To ensure uniqueness it is recommended that the date and time be included in the
file name. E.g.:

USERNAME_2001-07-26_13-42-08.XML



3.3.2 Compressed Files:
The REAXML system accepts XML files that have been compressed using the ZIP
archive format. Such files must have an extension of “.zip” or “.ZIP”.

For large XML files (e.g. those containing encoded image data or a large number of
property listings) it is recommended that compression be used to speed up FTP
transfer. Realestate.com.au may require files over a certain size to be compressed.



3.4 Data Requirements
3.4.1 Date & Time format:
Where required, date and time data must be in following format:

YYYY-MM-DD-hh:mm:ss (in 24 hour format).

If time data is not available, YYYY-MM-DD-00:00:00 or simply YYYY-MM-DD may
be used. Note, however, that in this case a time of midnight will be assumed and this
will affect the accuracy of timestamp checking.




Commercial in Confidence                 Page 8 of 14
realestate.com.au REAXML Functional Specification - Version 2.0



3.4.2 Images:
All images must be in JPEG format.

A minium image size of 800 x 600 pixels is required. Furthermore, images must be of
a high quality: smaller sized images rescaled upwards to meet the 800 x 600
requirement are unacceptable. Larger images will be accepted but are unnecessary
and will not improve the quality of the final image as it appears on the
realestate.com.au website.

Images shall be of a 4:3 aspect ratio. Images of a different ratio will appear distorted
when rescaled to by realestate.com.au‟s systems. This is with the exception of
portrait images in which case they are placed onto a black canvas to prevent
distortion.


3.4.3 Suburb Names:
The suburb names contained within the <suburb> XML tag must be valid and proper
suburb / locality names. These can only be added if they are deemed legitimate
bordered localities. In Australia by the appropriate department within the relevant
state government, in New Zealand, these are determined by „Land Information New
Zealand‟

Instances of “North”, “East”, etc should come after the suburb title. For instance,
“Balwyn North” is acceptable; “North Balwyn” is not. (Note that the REA XML System
attempts to correct such errors, but its accuracy is not guaranteed.)


3.4.4 businessCategory and businessSubCategory values:
For Business listings, the XML elements businessCategory and
businessSubCategory must contain one of the category and sub-category names
defined in the document at:

http://reaxml.realestate.com.au/BusinessCategories.txt

Failure to include a valid category or sub-category may prevent the business listing
from appearing in realestate.com.au search results.




Commercial in Confidence                 Page 9 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




4 Functional Overview
The following diagram represents the process by which agents‟ XML data is imported
in the REA database.



              Agent 1

                                                                  reaxml.realestate.com.au
                  Export
                 XML doc                                          DirWatcher
    Agent
     DB                                                                        REAXMLParser




                                         FTP upload
                                                                                    REA
                                                                                  Database
              Agent 2


                  Export
                 XML doc
      Agent
       DB




4.1 Data Export and FTP Upload

Agents are responsible for exporting data to a valid and well-formed XML document.
The document may contain a complete dump of the agent‟s entire property database,
or merely contain data for properties added or modified since the last export
(preferred). Agents will then upload the exported file(s) via FTP to the server
reaxml.realestate.com.au.

Each agent will be provided with an FTP username and password and will upload to
their own directory. Anonymous FTP will not be allowed. An agent will not have
access to files uploaded by another agent.

Preferably, if an agent uses an automated procedure to upload files it should be able
to detect a failed FTP transfer and retry where appropriate.

The REAXML system will periodically check each Agent‟s incoming FTP directory.
Any new files will be processed by the system.




Commercial in Confidence                 Page 10 of 14
realestate.com.au REAXML Functional Specification - Version 2.0



4.2 Log Files

For each XML file uploaded by an agent and processed by the REAXML system, a
new log file will be created, containing details generated while that XML file was
being parsed. This will list selected details on each property (including the REA
PropertyID) and the action performed: added, updated, or ignored because of some
defined error. The output of the log file is tab-delimited, allowing for easy
manipulation by a spreadsheet program or other tools.

These log files will available for the agent to view over the internet. For example, an
agent may find log files at:

http://reaxml.realestate.com.au/ftp_username/logs/

This area will be restricted using HTTP Basic-Authentication. The data provider will
be required to enter their username and password before access is granted.

Alternatively, the logs may be downloaded via FTP in the directory /logs/


4.3 System Availability

The FTP server at reaxml.realestate.com.au is available 24/7 to accept
connections. The REAXML system is currently scheduled to run throughout the day
on an hourly basis.

Therefore, any data uploaded via FTP during the day should be processed by the
following morning at the latest depending on the volume on information to be
processed.




Commercial in Confidence                 Page 11 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




5 XML Structure
A Document Type Definition (DTD), propertyList.dtd, defines the REA XML
structure. The current version of the DTD is available at:

http://reaxml.realestate.com.au/

Also available is an example document that conforms to the DTD.


5.1 propertyList.dtd

The XML files created by an Agent should conform to the propertyList.dtd. As such,
the XML file should make the following Document Type Declaration:

<!DOCTYPE propertyList SYSTEM
"http://reaxml.realestate.com.au/propertyList.dtd">


5.1.1   Document Validity:

The REAXML system employs a non-validating parser to parse incoming XML files.
As such, the system will attempt to process documents that do not strictly conform to
the propertyList.dtd, provided required elements (as defined in the DTD) are included
(soon to be revised).

However, invalid documents may produce undesirable results: data contained within
incorrectly named tags, for instance, will be ignored.


5.1.2   Document Well-Formedness:

The REAXML system will reject any XML documents that are not well-formed. The
log file will record the error generated by the parser.

It is the responsibility of the Agent to ensure well-formedness. For instance, special
characters such as “<”, “>” and “&” must be transformed to entity references. (The
<description> element seems to be a common culprit for bad data.)



5.2 Elements:

The following explains is more detail some of the elements contained within the DTD:

5.2.1 Username and Password:
Each XML file must contain details of username and password.

Single agents:
An individual agent should use their normal realestate.com.au ID and password for
these fields.


Commercial in Confidence                 Page 12 of 14
realestate.com.au REAXML Functional Specification - Version 2.0




Groups of affiliated agents:
The head office of the group will be responsible for exporting the data of all agents in
the group. A unique username and secret password will identify the group. Using this
username, the head office will be authorised to modify property listings for all agents
in the group (but not other unaffiliated agents).


5.2.2 Agent ID:
The <agentID> element contains the REA agent code for the agent listing the
property.


5.2.3 Unique ID:
The <uniqueID> element contains the agent‟s own unique property identifier. If the
agent does not generally use such an identifier, other unique information (such as the
property‟s address) should be used here. The uniqueID should be 50 characters or
less.


5.2.4 Images:
The <img> element must specify as an attribute the type of image. Either:
     “m” – the main image for the property;
     “a” through “l” (lowercase “L”) – additional images ;

The image itself can be identified by the URL attribute, or alternatively may be
included within the <img> element as Base64 encoded data.

The <img> element may also contain the modTime attribute that specifies the date
and time the image was last modified. This is not required, but is highly
recommended. Where modTime is not included:
    if an image URL is provided, the URL will be queried and the modification
       time from the HTTP header will be used;
    if the image is included as encoded data, the database will always be updated
       with the included image.

5.2.5 Extra Fields
The <extraFields> element should only be used by agents that have a specialised
import/export agreement with realestate.com.au Ltd. This field enables tracking of
information that is not directly linked to www.realestate.com.au but maybe relevant to
the client. The default import scheme does not entitle the Inter-connect provider to
utilise the functionality described below.
      The element must contain the table attribute which specifies the name of the
         customised table where the information is to be kept.
      In addition, it must include one or more <eField> elements that correspond to
         the individual fields in the customised table

A brief example is shown below where information will be kept in a customised table
called TestInfo which has two fields LandSize and Notes which are filled with
820sqm and “special note‟ respectively

<extraFields table=”TestInfo”>
       <eField name=” LandSize”> 820sqm </eField>
       <eField name=” Notes”> special note </eField>


Commercial in Confidence                 Page 13 of 14
realestate.com.au REAXML Functional Specification - Version 2.0



</extraFields>
The format of the values for the individual fields in the customised table must be
decided by the application generating the XML document and will be based upon the
agreed requirements between the client and realestate.com.au Ltd.




Commercial in Confidence                 Page 14 of 14

								
To top