JamesEdition Feed

Public XML feed consumed by the JamesEdition crawler. Conforms to the JamesEdition Multi-Office specification, version 4.3. Full tag reference: https://docs.jamesedition.com/docs/je-multi-office/fields.

Endpoint

GET /properties/feeds/jamesedition.xml

Authentication: Public, no credentials required.

The endpoint expects a User-Agent header containing JamesEdition Feed Crawler (for example, JamesEdition Feed Crawler 1.0). A mismatch is logged as a warning but the request is not blocked, so any client can fetch the feed.

Schedule

JamesEdition polls the feed three times a day, at approximately:

00:11 UTC
08:11 UTC
16:11 UTC

The feed is generated on request; there is no cache. Expect low latency on each call.

Eligibility

A listing is included in the feed when all of the following hold:

Condition	Value
`pushToJamesEdition`	`true`
`status`	`ACTIVE`
`propertyType`	Mapped in our property-type table (see below)

OFFICE and COMMERCIAL types are filtered out at the feed boundary, even if the pushToJamesEdition flag is set.

Property-type mapping

Fondaro `propertyType`	JamesEdition type
`APARTMENT`	Apartment
`PENTHOUSE`	Penthouse
`VILLA`	Villa
`HOUSE_DETACHED`	House
`HOUSE_SEMI_DETACHED`	House
`TOWNHOUSE`	Townhouse
`BUNGALOW`	Bungalow
`CHALET`	Chalet
`FINCA`	Finca
`COUNTRY_HOUSE`	Country house
`ESTATE`	Estate
`CASTLE`	Castle
`LAND`	Land
`OFFICE`	(filtered)
`COMMERCIAL`	(filtered)

Response format

Content type: application/xml; charset=utf-8.

Root element: <jameslist_feed version="4.3"> with three children:

Element	Contents
`<offices>`	One `<office reference="{orgUuid}">` per organization that has at least one eligible listing.
`<agents>`	One `<agent office_reference="{orgUuid}" reference="{agentUuid}">` per agent referenced by at least one eligible listing. Deduplicated.
`<listings>`	One `<listing reference="{listingUuid}">` per eligible listing.

Reference IDs

All reference attributes are internal Fondaro UUIDs:

Attribute	Source
`<office reference>`	`organization.id`
`<agent reference>`	`agent.id`
`<agent office_reference>`	`organization.id`
`<listing reference>`	`propertyListing.id`

These IDs are permanent. They never change for a given entity.

Empty-closed vs. omitted tags

The JamesEdition spec distinguishes required fields (must be present, empty-closed if no value) from optional fields (can be omitted). We follow the spec:

Required tag with no value: emitted empty-closed, for example <zip />.
Optional tag with no value: omitted from the XML entirely.

Example request

curl -H "User-Agent: JamesEdition Feed Crawler 1.0" \
  https://api.fondaro.com/properties/feeds/jamesedition.xml

Example response

Abbreviated, showing one office, one agent, and one listing:

<?xml version="1.0" encoding="UTF-8"?>
<jameslist_feed version="4.3">
  <offices>
    <office reference="a1b2c3d4-e5f6-7890-abcd-ef1234567890">
      <name>Konrad Real Estate</name>
      <brokerage_license_id />
      <zip />
      <country_code>ES</country_code>
      <country_subdivision />
      <city>Marbella</city>
      <address>Calle Ejemplo 12</address>
      <phone1>+34 000 000 000</phone1>
      <phone2 />
      <fax />
      <email>hello@example.com</email>
      <description>Boutique luxury brokerage on the Costa del Sol.</description>
      <external_url>https://konradrealestate.es</external_url>
      <office_logo_url>https://cdn.example.com/logo.png</office_logo_url>
      <language_codes>eng, spa</language_codes>
    </office>
  </offices>
  <agents>
    <agent office_reference="a1b2c3d4-e5f6-7890-abcd-ef1234567890" reference="b2c3d4e5-f6a7-8901-bcde-f12345678901">
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <email>jane@example.com</email>
      <phone1>+34 111 111 111</phone1>
      <phone2>+34 222 222 222</phone2>
      <profile_picture_url>https://cdn.example.com/jane.jpg</profile_picture_url>
      <agent_license_id />
      <biography>Ten years selling oceanfront villas in Marbella.</biography>
    </agent>
  </agents>
  <listings>
    <listing reference="c3d4e5f6-a7b8-9012-cdef-123456789012">
      <display_reference>HQL-12345</display_reference>
      <preowned>no</preowned>
      <year>2023</year>
      <price_on_request>no</price_on_request>
      <rental>no</rental>
      <price currency="EUR">2450000</price>
      <location>
        <country>ES</country>
        <region>Costa del Sol</region>
        <latitude>36.5101</latitude>
        <longitude>-4.8824</longitude>
        <city>Marbella</city>
        <address>Urbanizacion Ejemplo 42</address>
        <zip>29660</zip>
      </location>
      <title>Villa in Marbella, ES</title>
      <description>Newly built beachfront villa with panoramic sea views.</description>
      <property_type>Villa</property_type>
      <bedrooms>5</bedrooms>
      <bathrooms>4</bathrooms>
      <living_area unit="sqm">420</living_area>
      <land_area unit="sqm">1200</land_area>
      <amenities>
        <pool>yes</pool>
        <sea_view>yes</sea_view>
        <garage>yes</garage>
        <terrace>yes</terrace>
        <garden>yes</garden>
        <air_conditioning>yes</air_conditioning>
      </amenities>
      <media>
        <image>
          <image_url>https://cdn.example.com/listings/villa-1/01.jpg</image_url>
        </image>
        <image>
          <image_url>https://cdn.example.com/listings/villa-1/02.jpg</image_url>
        </image>
      </media>
      <agent_reference>b2c3d4e5-f6a7-8901-bcde-f12345678901</agent_reference>
      <office_reference>a1b2c3d4-e5f6-7890-abcd-ef1234567890</office_reference>
      <hide_address>no</hide_address>
      <address_is_confidential>no</address_is_confidential>
    </listing>
  </listings>
</jameslist_feed>

Images are capped at 100 per listing, ordered by their stored order value.

Derived fields

A handful of fields are computed at feed-build time rather than read directly from storage:

Field	Derivation
`<preowned>`	`isNewConstruction === true` emits `no`, otherwise `yes`.
`<rental>`	`listingType === RENT` emits `yes`, otherwise `no`.
`<price_on_request>`	`price == null` emits `yes`, otherwise `no`.
`<title>`	`${propertyTypeLabel} in ${city}, ${countryCode}`. Falls back to just `propertyTypeLabel` when city or country are missing.
`<hide_address>`	Hardcoded `no`.
`<address_is_confidential>`	Hardcoded `no`.

Amenity mapping

Amenity tags are emitted only when the source field is true. False values are not emitted.

Source field	Emitted tag
`hasPool`	`<pool>yes</pool>`
`hasSeaView`	`<sea_view>yes</sea_view>`
`hasGarage`	`<garage>yes</garage>`
`hasTerrace`	`<terrace>yes</terrace>`
`hasGarden`	`<garden>yes</garden>`
`isFurnished`	`<furnished>yes</furnished>`
`hasAirConditioning`	`<air_conditioning>yes</air_conditioning>`
`hasLift`	`<elevator>yes</elevator>`

Errors

On an internal error the endpoint returns HTTP 500 with an empty body. We log the error server-side; we do not leak details to the response to keep the feed output clean for the crawler.

Notes

XML special characters (&, <, >, ") in user-entered titles, descriptions, and addresses are escaped by the feed builder. Downstream consumers should decode them as standard XML.
Organizations with zero eligible listings are omitted from <offices>. The feed never emits an <office> with no matching <listing> entries.
Reference stability means you can safely cache mappings between JamesEdition's internal IDs and our UUIDs without worrying about churn.