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>
<!-- rent: set <type>rent</type>, send the rent in <price> and say what it covers:
<rental_period>month</rental_period> (day, week, month or year) -->
<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>
<private_listing>no</private_listing>
<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
referenceandcategoryattributes on<advert> property_typelocation/countryandlocation/city- a price:
price(sale or rent, withrental_periodon rent) orrental_price_per_day(rent only, a daily rate), each withcurrency, orprice_on_request=yes - at least 2 images
agent_referencematching 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" | Listing price for sale and rent. Shown exactly as sent. currency = ISO 4217. |
rental_price_per_day (currency attribute) | Yes¹ | int | 350 currency="EUR" | Rent only: the price per day, imported as sent. currency = ISO 4217. See Price. |
rental_period | No | day | week | month | year | month | Rent only: the period the price covers. Add it to every rent listing. See Rental period. |
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. |
private_listing | No | yes/no | no | When yes, the listing is imported as a private listing: its price, address, description and the photos you choose stay hidden from the public page. Only works once JamesEdition has enabled private listings for your office. Sending no or leaving the tag out never makes a private listing public. To do that, change it in the listing editor. |
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. |
¹ Every listing needs a price: price (sale or rent, shown exactly as sent), rental_price_per_day (rent only, a daily rate imported as sent), or price_on_request=yes. See Price.
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 |