Real Estate — Multi Office

Use this format when several offices publish through one feed. It has three sections: <offices>, <agents>, and <listings>. Each <agent> belongs to an office, and each <listing> points at its office and 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 (two offices)

<?xml version="1.0" encoding="UTF-8"?>
<jamesedition_feed version="4.4">
  <offices>
    <office reference="of-charlotte">
      <name>HM Properties — Charlotte</name>
      <country_code>US</country_code>
      <country_subdivision>North Carolina</country_subdivision>
      <city>Charlotte</city>
      <address>28210 Fairview Road</address>
      <zip>28210</zip>
      <phone1>+1234567890</phone1>
      <phone2>+1234567891</phone2>
      <fax>+1234567892</fax>
      <email>charlotte@example.com</email>
      <description>Charlotte headquarters.</description>
      <biography>Boutique brokerage serving the Charlotte luxury market.</biography>
      <external_url>https://example.com/charlotte</external_url>
      <office_logo_url>https://example.com/logo.png</office_logo_url>
      <language_codes>eng,spa</language_codes>
      <linkedin>https://linkedin.com/company/hm-properties</linkedin>
      <instagram>https://instagram.com/hmproperties</instagram>
      <facebook>https://facebook.com/hmproperties</facebook>
      <tiktok>https://tiktok.com/@hmproperties</tiktok>
    </office>
    <office reference="of-ny">
      <name>HM Properties — New York</name>
      <country_code>US</country_code>
      <country_subdivision>New York</country_subdivision>
      <city>New York</city>
      <address>5th Avenue 100</address>
      <zip>10011</zip>
      <phone1>+1987654321</phone1>
      <phone2>+1987654322</phone2>
      <fax>+1987654323</fax>
      <email>ny@example.com</email>
      <description>New York branch.</description>
      <biography>Manhattan luxury specialists since 1998.</biography>
      <external_url>https://example.com/ny</external_url>
      <office_logo_url>https://example.com/logo.png</office_logo_url>
      <language_codes>eng,fra</language_codes>
      <linkedin>https://linkedin.com/company/hm-properties</linkedin>
      <instagram>https://instagram.com/hmproperties</instagram>
      <facebook>https://facebook.com/hmproperties</facebook>
      <tiktok>https://tiktok.com/@hmproperties</tiktok>
    </office>
  </offices>
  <agents>
    <agent reference="ag-steve" office_reference="of-charlotte">
      <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>
    </agent>
    <agent reference="ag-jane" office_reference="of-ny">
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <email>jane.doe@example.com</email>
      <phone1>+1987654321</phone1>
      <phone2>+1987654322</phone2>
      <fax>+1987654323</fax>
      <agent_license_id>998877</agent_license_id>
      <profile_picture_url>https://example.com/jane.jpg</profile_picture_url>
      <language_codes>eng,fra</language_codes>
      <linkedin>https://linkedin.com/in/janedoe</linkedin>
      <instagram>https://instagram.com/janedoe</instagram>
      <facebook>https://facebook.com/janedoe</facebook>
      <tiktok>https://tiktok.com/@janedoe</tiktok>
    </agent>
  </agents>
  <listings>
    <listing 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>
      </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>ag-jane</agent_reference>
      <office_reference>of-ny</office_reference>
    </listing>
  </listings>
</jamesedition_feed>

Required fields

the reference and category attributes on <listing>
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
office_reference matching an entry in <offices> (and agent_reference matching <agents> to link the agent)

Listing fields

Field	Required	Type	Example	Description
`reference` (attribute)	Yes	string	`ls123`	Unique listing ID, on the `<listing>` element.
`category` (attribute)	Yes	`real estate`	`real estate`	Asset category, on the `<listing>` 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`	One of the supported property types — 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>`	Full list: 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.
`office_reference`	Yes	string	`of123`	Must match an `<office>` reference.

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

Office fields

Field	Required	Type	Example
`reference` (attribute)	Yes	string	`of123`
`name`	Yes	string	`HM Properties — Charlotte`
`country_code`	Yes	ISO 3166-1 alpha-2	`US`
`city`	Yes	string	`Charlotte`
`country_subdivision` · `address` · `zip`	No	string	`North Carolina`
`phone1`	Yes	string	`+1234567890`
`phone2` · `fax` · `email`	No	string
`description` · `external_url` · `office_logo_url`	No
`biography`	No	text
`language_codes`	No	string	`eng,spa`
`linkedin` / `instagram` / `facebook` / `tiktok`	No	url

Agent fields

Field	Required	Type	Example
`reference` (attribute)	Yes	string	`ag123`
`office_reference` (attribute)	Yes	string	`of123`
`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

Example (two offices)​

Required fields​

Listing fields​

Office fields​

Agent fields​

Example (two offices)

Required fields

Listing fields

Office fields

Agent fields