Real Estate — Single Office

Use this format when one office publishes its listings. The feed has an <agents> section and an <adverts> section; each <advert> points at its agent by reference.

Read first

Getting Started covers the shared rules — fetch schedule, the JamesEdition Feed Crawler 1.0 User-Agent, image rules, and supported video / virtual-tour sources.

Example

<?xml version="1.0" encoding="UTF-8"?>
<jamesedition_feed version="3.9">
  <agents>
    <agent reference="ag123">
      <first_name>Steve</first_name>
      <last_name>Smith</last_name>
      <email>steve.smith@example.com</email>
      <phone1>+1234567890</phone1>
      <phone2>+1234567891</phone2>
      <fax>+1234567892</fax>
      <agent_license_id>636289</agent_license_id>
      <profile_picture_url>https://example.com/steve.jpg</profile_picture_url>
      <language_codes>eng,spa</language_codes>
      <linkedin>https://linkedin.com/in/stevesmith</linkedin>
      <instagram>https://instagram.com/stevesmith</instagram>
      <facebook>https://facebook.com/stevesmith</facebook>
      <tiktok>https://tiktok.com/@stevesmith</tiktok>
      <biography>Luxury specialist; agent of the year 2022.</biography>
    </agent>
  </agents>

  <adverts>
    <advert reference="ls123" category="real estate">
      <type>sale</type>
      <price currency="USD" vat_included="yes">1607143</price>
      <!-- rentals: send <rental_price_per_day currency="EUR">350</rental_price_per_day> instead of <price> -->
      <price_on_request>no</price_on_request>
      <vat>21</vat>
      <property_type>Villa</property_type>
      <title>Luxury Villa in Exclusive Area</title>
      <description>A luxurious villa with formal rooms, a gourmet kitchen and a pool.</description>
      <year>2014</year>
      <preowned>yes</preowned>
      <mls_number>mls124</mls_number>
      <licence_id>VT-1234</licence_id>
      <location>
        <country>US</country>
        <region>New York</region>
        <city>Black River</city>
        <address>123 Luxury St</address>
        <zip>12345</zip>
        <latitude>43.9732</latitude>
        <longitude>-75.9108</longitude>
      </location>
      <hide_address>no</hide_address>
      <bedrooms>5</bedrooms>
      <bathrooms>4</bathrooms>
      <floors>2</floors>
      <living_area unit="sqm">217</living_area>
      <land_area unit="sqm">361</land_area>
      <emission_rating>A</emission_rating>
      <consumption_rating>B</consumption_rating>
      <amenities>
        <pool>yes</pool>
        <sea_view>yes</sea_view>
        <air_conditioning>yes</air_conditioning>
        <garden>yes</garden>
        <garage>yes</garage>
      </amenities>
      <media>
        <image>
          <image_url>https://example.com/p1.jpg</image_url>
        </image>
        <image>
          <image_url>https://example.com/p2.jpg</image_url>
        </image>
        <video>
          <video_url>https://youtu.be/example</video_url>
        </video>
        <virtual_tour_link>https://my.matterport.com/show/?m=exampleID</virtual_tour_link>
      </media>
      <external_url>https://agency.com/listing/123</external_url>
      <agent_reference>ag123</agent_reference>
    </advert>
  </adverts>
</jamesedition_feed>

Required fields

• the reference and category attributes on <advert>
• property_type
• location/country and location/city
• a price — price for sale / rental_price_per_day for rent (each with currency) or price_on_request=yes
• at least 2 images
• agent_reference matching an <agent>

Advert fields

Field	Required	Type	Example	Description
reference (attribute)	Yes	string	ls123	Unique advert ID, on the <advert> element.
category (attribute)	Yes	real estate	real estate	Asset category, on the <advert> element.
type	Yes	sale | rent	sale	Sale or rent.
price (currency attribute)	Yes¹	int	1607143 currency="USD"	Sale price. currency = ISO 4217. For rentals use rental_price_per_day.
rental_price_per_day (currency attribute)	Yes¹	int	350 currency="EUR"	Per-day rental price, for type=rent. currency = ISO 4217.
price_on_request	No	yes/no	no	When yes, price hidden on the public listing.
vat	No	number	21	VAT amount or rate on the price. The optional vat_included (yes/no) attribute on <price> states whether the quoted price already includes VAT.
vat_type	No	enum	vat_included	Alternative to the vat_included attribute on <price>: vat_included / vat_excluded.
property_type	Yes	enum	Villa	See Field reference.
title	No	string	Luxury Villa…
description	No	text	A luxurious villa…
year	No	int	2014	Year built.
preowned	No	yes/no	yes	no for new-build.
completion_status	No	enum	secondary	Alternative to preowned: off_plan = new build, secondary / completed = pre-owned.
mls_number	No	string	mls124
licence_id	No	string	VT-1234	Rental / tourism licence ID, where regulators require one (e.g. Spain, Portugal).
trakheesi_permit_number	No	string	7129834561	Dubai (RERA) listing permit number, where required.
location/country	Yes	ISO 3166-1 alpha-2	US
location/region	No	text (name)	New York	State / region name (matched by name, not a code).
location/city	Yes	string	Black River
location/address	No	string	123 Luxury St	Hidden if hide_address=yes.
location/zip	No	string	12345
location/latitude · longitude	No	float	43.97	Optional.
hide_address	No	yes/no	no	Hide the public address for this listing.
bedrooms	No	int	5	Number of bedrooms.
bathrooms	No	int	4	Number of bathrooms.
floors	No	int	2	Total floors in the property (how many storeys the building has) — not the floor the unit is on. A house is usually 1–2.
living_area (unit attribute)	No	int	217 unit="sqm"	sqm/sqft.
land_area (unit attribute)	No	int	361 unit="sqm"	sqm/sqft/ha/ac.
emission_rating · consumption_rating	No	enum	A	A–G, A+, B+, B-, A1–A4, X, NC, NI — see Field reference.
amenities	No	wrapper	<pool>yes</pool>	Amenities.
media/image/image_url	Yes (≥2)	url	https://…/p1.jpg	JPEG/PNG/WEBP, ≤100, ≤20 MB each.
media/video/video_url	No	url	https://youtu.be/…	Supported video sources.
media/virtual_tour_link	No	url	https://my.matterport.com/…	Supported virtual-tour sources.
external_url	No	url	https://agency.com/listing/123	The listing's page on your own site — shown as "View on agency site".
agent_reference	Yes	string	ag123	Must match an <agent> reference.

¹ A price is required unless price_on_request=yes — price for type=sale, rental_price_per_day for type=rent.

Agent fields

Field	Required	Type	Example
reference (attribute)	Yes	string	ag123
first_name · last_name	Yes	string	Steve / Smith
email	Yes	string	steve.smith@example.com
phone1	No	string	+1234567890
phone2 · fax	No	string
agent_license_id	No	string	636289
profile_picture_url	No	url
language_codes	No	string	eng,spa
linkedin / instagram / facebook / tiktok	No	url
biography	No	text