Real Estate XML Feed Documentation (GREF v1.0)

This documentation defines the structure and rules for the XML feed used to import real estate properties into our system. The format is designed according to modern standards with an emphasis on detailed element categorization and multi-language support.

1. Technical Information

• File Format: XML (Encoding: UTF-8)
• Format Version: 2.0
• Date Formats: ISO 8601 (e.g., 2026-00-00T00:00:00+01:00)
• Decimal Numbers: A dot (.) is used as a decimal separator.
• The XML feed export must be valid and comply with the defined format.
• The XML feed must be accessible via HTTPS.
• Before downloading the XML feed, we will check the last modification date using the HTTP Last-Modified header. We recommend configuring the HTTP server to include this header in the response to avoid unnecessary load on both sides caused by downloading unchanged XML files.
• The maximum XML feed size is 1 GB. For larger feeds, we recommend using GZIP compression.
• The maximum number of listings in the XML feed is 100,000.
• The XML feed must not contain listings that are unavailable, sold, or not for sale.
• The XML feed must not contain images with watermarks or advertisements.
• Individual property listings that do not contain the required fields will not be imported.
• The listing description must not contain contact details, URL links, or embedded elements; such listings will not be imported.
• A low amount of filled-in data may extend the publication time.
• Allowed image types: JPG/JPEG, PNG, WebP. Maximum image file size: 5 MB. Minimum resolution: 800 px on the longer edge.
• The maximum number of gallery images per listing depends on the purchased advertising package. If a listing contains more images, only the allowed number will be imported, in the order provided. If no cover image is specified, the first image in the list will be used. To ensure smooth image import, bulk downloading of images must not be blocked on your side (rate limiting, bot limiting, etc.).

2. Document Structure

The root element is <realty_feed>, which contains the attributes version and generated_at. Each property is wrapped in a <property> element.

3. Detailed Attribute Description

Required attributes are marked with an asterisk. At least one of more required attributes of the related parameters' group are marked with **.

3.1 Basic Information

3.2 Text Content and Localization

Use the lang attribute to distinguish between languages.

• titles/title: Short and descriptive property name.
• descriptions/description: Detailed description. We recommend using <![CDATA[ ... ]]> to preserve HTML formatting.

3.3 Location

3.4 Price Info

4. Property Features – Technical Glossary

All parameters in this section are optional. However, filling them in directly affects the quality of filtering and the property's position in search results.

4.1 Dimensions and Basic Data (Numeric)

4.2 Interior and Equipment (Boolean / Text)

4.3 Exterior and Plot (Boolean)

4.4 Utilities and Security (Boolean)

4.5 Location, Status, and Character (Enum / Mix)

5. Media and Contact

5.1 Images

The <images> element must contain at least one item.

• <cover>^**: Link to the main (title) photo.
• <gallery>^**: Contains a list of <image> elements with other photos.
• <floor_plans>: Optional floor plans of the property.

5.2 Video and Virtual Tour - OPTIONAL

• <videos>: Supports YouTube/Vimeo. The type attribute defines the platform. The url attribute defines the video shortcode.
• <virtual_tour>: Link to Matterport or another 3D scan.

5.3 Agent (Contact)

6. Sample XML File

<?xml version="1.0" encoding="UTF-8"?>
<realty_feed version="2.0" generated_at="2026-01-01T00:00:00Z">
   <property>
      <reference_id>REF-123456</reference_id>
      <internal_id>78910</internal_id>
      <type>house</type>
      <contract_type>sale</contract_type>
      <status>active</status>
        
      <dates>
            <created_at>2026-01-11T19:22:39+01:00</created_at>
            <updated_at>2026-02-09T15:00:00+01:00</updated_at>
      </dates>

      <titles>
            <title lang="sk">Luxusná vila s bazénom a výhľadom na more</title>
            <title lang="en">Luxury villa with pool and sea view</title>
      </titles>

      <descriptions>
            <description lang="sk"><![CDATA[Detailný popis nehnuteľnosti...]]></description>
            <description lang="en"><![CDATA[Detailed description of the property...]]></description>
      </descriptions>

      <location>
            <country_code>HR</country_code>
            <state>Croatia</state>
            <administrative_area>Dubrovačko-neretvanska županija</administrative_area>
            <city>Split</city>
            <postal_code>21000</postal_code>
            <street>Obala HRM 1</street>
            <coordinates exact="true">
                 <lat>43.5081</lat>
                 <lng>16.4402</lng>
            </coordinates>
      </location>

      <price_info>
            <price currency="EUR">1250000</price>
            <unit>total</unit>
            <tax_included>true</tax_included>
            <negotiable>false</negotiable>

            <texts_before>
                 <text lang="sk">od</text>
                 <text lang="en">from</text>
            </texts_before>

            <texts_after>
                 <text lang="sk">vrátane provízie</text>
                 <text lang="en">including commission</text>
            </texts_after>
      </price_info>

      <features>
            <size unit="m2">250</size>
            <lot_size unit="m2">800</lot_size>
            <rooms>5</rooms>
            <bedrooms>3</bedrooms>
            <bathrooms>2</bathrooms>
            <parking_spaces>2</parking_spaces>
            <parking>3</parking>
            <year_built>2022</year_built>

            <equipped_kitchen>true</equipped_kitchen>
            <furnished>true</furnished>
            <underfloor_heating>true</underfloor_heating>
            <washing_machine_dryer>true</washing_machine_dryer>
            <interior_fireplace>true</interior_fireplace>
            <interior_sauna>true</interior_sauna>
            <interior_pool>false</interior_pool>
            <interior_pool_stream>false</interior_pool_stream>
            <gym>true</gym>
            <laundry>true</laundry>
            <media_room>false</media_room>
            <elevator>true</elevator>
            <basement>true</basement>
            <interior_garage>true</interior_garage>

            <garden>true</garden>
            <balcony>true</balcony>
            <terrace>true</terrace>
            <exterior_sauna>false</exterior_sauna>
            <exterior_pool>true</exterior_pool>
            <exterior_pool_heating>true</exterior_pool_heating>
            <exterior_pool_filtration>true</exterior_pool_filtration>
            <exterior_pool_stream>true</exterior_pool_stream>
            <whirlpool>true</whirlpool>
            <exterior_garage>true</exterior_garage>
            <barbecue_area>true</barbecue_area>
            <backyard>true</backyard>
            <basketball_court>false</basketball_court>
            <lot>true</lot>
            <storage>true</storage>
            <central_heating>true</central_heating>
            <central_ventilation>false</central_ventilation>
            <air_conditioning>true</air_conditioning>
            <broadband_internet>true</broadband_internet>
            <wifi>true</wifi>
            <alarm>true</alarm>
            <video_surveillance>true</video_surveillance>
            <smoke_detectors>true</smoke_detectors>
            <electricity>true</electricity>
            <water>true</water>
            <gas>false</gas>
            <energy_certificate>A</energy_certificate>

            <sea_view>true</sea_view>
            <sea_first_line>true</sea_first_line>
            <water_view>true</water_view>
            <city_view>false</city_view>
            <coast_water>true</coast_water>
            <high_altitude>false</high_altitude>
            <closed_community>true</closed_community>
            <privacy>true</privacy>
            <privacy_or_gated>true</privacy_or_gated>
            <distance_to_sea unit="km">0.5</distance_to_sea>
            <distance_to_airport unit="km">1.5</distance_to_airport>
            <kindergarden unit="km">1.2</kindergarden>
            <shopping_mall unit="km">3.5</shopping_mall>
            <location_rating>A</location_rating>
            <renovation_status>MODERN</renovation_status>
            <new_construction>true</new_construction>
            <modern>true</modern>
            <investment>true</investment>
            <wheelchair_accessible>false</wheelchair_accessible>
      </features>

      <media>
            <images>
                 <cover>https://www.example.com/house/cover.jpg</cover>
                 <gallery>
                      <image>https://www.example.com/house/image_1.jpg</image>
                      <image>https://www.example.com/house/image_2.jpg</image>
                 </gallery>
                 <floor_plans>
                      <plan>https://www.example.com/house/image_plan_1.jpg</plan>
                      <plan>https://www.example.com/house/image_plan_2.jpg</plan>
                 </floor_plans>
            </images>
            <videos>
                 <video type="youtube">
                      <url>K7Nmr6O--7c</url>
                 </video>
            </videos>
            <virtual_tour>https://my.matterport.com/show/?m=example</virtual_tour>
      </media>

      <agent>
            <name>John Doe</name>
            <email>[email protected]</email>
            <phone type="mobile">+421900123456</phone>
            <phone type="landline">+42121234567</phone>
            <whatsapp>+421900123456</whatsapp>
      </agent>
   </property>
</realty_feed>