Sign in or Sign up
News and Events

XML Feed for Projects and Layouts

1. Feed Purpose

The XML feed transfers structured data about real estate projects and typical layouts. Its purpose is to allow the receiving system to automatically create and update project cards, display prices, statuses, galleries, amenities, payment terms, EOI, and marketing promo materials from developers.

The feed transfers layouts in aggregated form: one layout record describes a typical layout and the number of available units of that type. It is not a list of specific apartments, offices, or lots.

  • realty-feed: root container of the entire XML feed. Main ID: —
  • offers: one project or complex. Main ID: complex-id
  • layouts: typical layout inside a project. Main ID: id
  • payment_plans: one project payment option. Main ID: id
  • eoi_item: one EOI condition. Main ID: —
  • stock: marketing campaign, news item, or promotional message from the developer. Main ID: —

1.1 What Is an XML Feed

An XML feed is a structured file containing data about real estate projects and typical layouts. It includes descriptions, photos, prices, addresses, statuses, specifications, amenities, and other data required to display properties on an agency website or in a catalog.

In simple terms, an XML feed is a data stream about real estate that the receiving system regularly downloads, reads, and uses to automatically update property cards.

Alnair provides the data. Website development, catalog development, CRM integration, and import logic are handled by the client or the client's technical team.

1.2 What the Agency Needs

To use the XML feed, the agency needs its own technical infrastructure capable of regularly downloading the XML, parsing its structure, and updating data in its system.

  • Website or property catalog: the place where projects and layouts from the feed will be displayed.
  • Technical team or developer: setup of XML downloading, parsing, and import.
  • XML parser: reading the XML structure and converting it into the internal data model.
  • Import module: creating, updating, and deactivating projects and layouts.
  • Task scheduler: regular import execution on a schedule, for example via cron or scheduler.
  • Error logging: monitoring unknown enum values, empty fields, and loading errors.

1.3 How the Agency Uses the XML Feed

A typical workflow looks as follows:

  1. The agency system downloads the XML from a personal web link.
  2. The XML is saved as a raw snapshot for diagnostics and reprocessing.
  3. The parser reads the realty-feed, offers, layouts structure and nested blocks.
  4. The import module creates new projects and layouts or updates existing ones.
  5. Objects that disappear from the new feed are marked as inactive.
  6. The agency website displays up-to-date project cards, prices, galleries, and statuses.

Main integration capabilities:

  • Automatic updates: projects and layouts are updated without manual input.
  • Property page creation: feed data is used for project and layout cards.
  • Up-to-date prices and statuses: the website receives XML updates on schedule.
  • Filters and search: district, price, property type, room count, and area fields can be used for filtering.
  • Media galleries: project photos, themed galleries, and layout images can be displayed in the interface.

2. General XML Structure

<realty-feed>
  <generation-date>2026-06-17T12:06:39+04:00</generation-date>
  <offers>...</offers>
  <offers>...</offers>
</realty-feed>

  • realty-feed: object. Root feed block.
  • generation-date: datetime. XML generation date and time. Used to check data freshness.
  • offers: object[]. List of projects or complexes. Each offers block contains project data and its layouts.

2.1 Feed Access and Download Limits

The feed is provided to the client via a personal web link. The link is unique to the client and is used by the receiving system to automatically download the XML.

The personal link is available to the administrator in the Alnair account. The administrator can pass this link to the client's technical team for import setup.

  • Access type: personal web link. Individual XML feed URL for the client.
  • Where to get the link: Alnair account. The link is available to the client administrator.
  • Feed update frequency: every 4 hours. XML data is updated on the Alnair side once every 4 hours.
  • Minimum download interval: no more than once per hour. The receiving system must not access the feed more than once per hour.
  • Limit exceeded: access blocking. If requests are too frequent, feed access may be temporarily blocked.

Recommended integration logic: configure scheduled downloading via cron or scheduler, save the last received XML, and do not request the feed on every website page load. The optimal mode is to download the feed no more than once per hour while taking into account that new data appears approximately every 4 hours.

3. Project: <offers>

offers is the main feed entity. It contains the project description, developer, location, construction and sales status, prices, media, amenities, payment plans, EOI, marketing promotions, and typical layouts.

<offers>
  <complex-id>5646</complex-id>
  <type>project</type>
  <logo>https://...</logo>
  <photo>https://...</photo>
  <title>...</title>
  <description>...</description>
  <price_on_request>1</price_on_request>
  <status>...</status>
  <construction_start_at>2025-01-01T00:00:00+04:00</construction_start_at>
  <construction_progress>15</construction_progress>
  <planned_completion_at>2027-12-31T00:00:00+04:00</planned_completion_at>
  <predicted_completion_at>2027-12-31T00:00:00+04:00</predicted_completion_at>
  <amenities>...</amenities>
  <developer>...</developer>
  <city>Dubai</city>
  <address>...</address>
  <latitude>25.000000</latitude>
  <longitude>55.000000</longitude>
  <districts>...</districts>
  <album>...</album>
  <albums>...</albums>
  <constructions_count>1</constructions_count>
  <for_sale_count>10</for_sale_count>
  <price>...</price>
  <br_prices>...</br_prices>
  <updated_at>2026-06-17T10:53:20+04:00</updated_at>
  <is_sold_out>0</is_sold_out>
  <payment_plans>...</payment_plans>
  <sales_status>...</sales_status>
  <stocks>...</stocks>
  <eoi>...</eoi>
  <service_charge>...</service_charge>
  <assignment>...</assignment>
  <is_limited_publication>0</is_limited_publication>
  <layouts>...</layouts>
</offers>

  • complex-id: integer. Unique project ID in Alnair. Use as the external project ID for upsert.
  • type: enum. Top-level entity type: project or compound. Store the raw value and import as a top-level project.
  • logo: url. Project logo. Show in branding, do not use as cover.
  • photo: url. Main project image / cover. Use as cover image and hero image.
  • title: localized object. Project name in en/ru/ar. Display according to interface language.
  • description: localized HTML. Project description in en/ru/ar. Render safely; HTML is inside CDATA.
  • price_on_request: 0/1. Price hiding flag. If 1, show “Price on request”.
  • status: object. Construction status. Do not confuse with sales_status.
  • construction_start_at: datetime. Construction start date. Display if filled.
  • construction_progress: decimal. Construction completion percentage. Display as a percentage.
  • planned_completion_at: datetime. Planned project completion date. Use as the handover date.
  • predicted_completion_at: datetime. Predicted completion date. Can be used as an updated completion date.
  • amenities: object. Project amenities and features. Map by key.
  • developer: object. Project developer. Store name and logo.
  • city / address: string. Project city and address. Use in location data.
  • latitude / longitude: decimal. Coordinates. Use for the map.
  • districts: object. Project districts. Use for filters and the project card.
  • album: object. Main uncategorized project gallery. Show as the general gallery.
  • albums: object. Themed project galleries. Group by title.
  • for_sale_count: integer. Number of available units in the project. Can be displayed as availability.
  • price: object. General project price range. Hide when price_on_request=1.
  • br_prices: object[]. Prices by bedroom count or category. Use for filters and listings.
  • updated_at: datetime. Project update date. Use for synchronization.
  • is_sold_out: 0/1. Sold-out flag. Use together with sales_status.
  • payment_plans: object[]. Payment options from the developer. Display as payment options.
  • sales_status: localized object. Project sales status. Defines the sales stage.
  • stocks: object. Marketing campaigns and promotional messages from the developer. Display as promo blocks.
  • eoi: object. Expression of Interest. Display only for Presale (EOI).
  • service_charge: object. Service charge. Display if value is filled.
  • assignment: decimal. Assignment condition. Empty means not specified.
  • is_limited_publication: 0/1. Publication restriction. If 1, do not publish publicly without permission.
  • layouts: object[]. Typical project layouts. Import as child entities of the project.

4. Localized Fields

Localized fields have the same structure: values in English, Russian, and Arabic are passed inside the tag.

<title>
  <en>Project Name</en>
  <ru>Название проекта</ru>
  <ar>اسم المشروع</ar>
</title>

  • en: English value. Recommended fallback.
  • ru: Russian value.
  • ar: Arabic value.

Fallback rule:

  1. Use the interface language if it is filled.
  2. If the required language is empty, use en.
  3. If en is empty, use ru.
  4. If ru is empty, use ar.
  5. If all values are empty, do not display the field.

5. Statuses

5.1 Construction Status: <status>

Construction status shows the physical state of the project. It does not indicate sales availability.

<status>
  <key>development_stage_progress</key>
  <en>In Progress</en>
  <ru>Строится</ru>
  <ar>قيد الإنشاء</ar>
</status>

  • Scheduled: the project is planned.
  • In Progress: construction is in progress.
  • Ready: the project is completed.
  • Stopped: construction is stopped.

5.2 Sales Status: <sales_status>

Sales status shows the commercial stage of the project: announcement, presale, launch, active sales, or sold out.

  • Preliminary Info: early project information.
  • Announcement: the project has been announced.
  • Presale (EOI): EOI collection is in progress.
  • Launch: sales launch.
  • On Sale: the project is available for purchase.
  • Sold Out: the project is sold out.
  • Pending: the status is awaiting update.

6. Developer and Location

These blocks are needed to display the developer brand and the geographical location of the project.

<developer>
  <title>
    <en>Developer Name</en>
    <ru>Developer Name</ru>
    <ar>Developer Name</ar>
  </title>
  <logo>https://...</logo>
</developer>
<city>Dubai</city>
<address>Project Address, Dubai</address>
<latitude>25.01809076</latitude>
<longitude>55.13354525</longitude>
<districts>
  <district>Jumeirah Village Triangle (JVT)</district>
</districts>

  • developer.title: localized object. Developer name.
  • developer.logo: url. Developer logo.
  • city: string. City.
  • address: string. Address.
  • latitude / longitude: decimal. Coordinates for the map.
  • districts.district: string[]. Project districts.

7. Prices

7.1 Project Price: <price>

The project-level price shows the general price range for available offers in the project.

<price>
  <min>815462</min>
  <max>2089780</max>
  <min_usd>222009</min_usd>
  <max_usd>568942</max_usd>
  <currency>AED</currency>
</price>

  • min: decimal. Minimum price.
  • max: decimal. Maximum price.
  • min_usd: decimal. Minimum price in USD.
  • max_usd: decimal. Maximum price in USD.
  • currency: enum. Main currency, usually AED.

If price_on_request = 1, exact prices are not displayed publicly, even if price is filled.

7.2 Prices by Category: <br_prices>

br_prices groups prices and areas by bedroom count or property type. This is useful for filters and short project cards.

<br_prices>
  <key>1</key>
  <count>7</count>
  <min_price>1070564</min_price>
  <max_price>1289674</max_price>
  <min_price_m2>17204</min_price_m2>
  <max_price_m2>18483</max_price_m2>
  <currency>AED</currency>
  <min_area><m2>57.92</m2><ft2>623.45</ft2></min_area>
  <max_area><m2>74.17</m2><ft2>798.36</ft2></max_area>
</br_prices>

  • studio: studios.
  • 1-6: number of bedrooms.
  • villa: villas.
  • townhouse: townhouses.
  • n: not applicable / non-residential category / other.

8. Media

Media in the feed is divided into several types. These should not be merged into one gallery without considering their purpose: one image may be the project cover, another the logo, another a promotion image, and another a floor plan.

  • logo: offers.logo. Project logo. Show in project branding; do not use as cover.
  • photo: offers.photo. Main project image / cover. Use as cover image in the card and hero image on the project page.
  • album.image: offers.album.image. Main uncategorized project gallery. Show in the general project gallery.
  • albums.album.images.image: offers.albums.album.images.image. Themed project gallery. Group by albums.album.title.
  • developer.logo: offers.developer.logo. Developer logo. Show in the developer block.
  • stocks.stock.logo: offers.stocks.stock.logo. Marketing campaign image. Show inside the promotion block.
  • layouts.album.image: offers.layouts.album.image. Gallery of a specific typical layout. Show at layout level.
  • levels_photos.level_photo.image: offers.layouts.levels_photos.level_photo.image. Layout image by level. Use as floor plan.

<photo>https://...</photo>
<album>
  <image>https://...</image>
</album>
<albums>
  <album>
    <title><en>Infrastructure</en><ru>Инфраструктура</ru><ar>...</ar></title>
    <images>
      <image>https://...</image>
    </images>
  </album>
</albums>

  • Project presentation: project presentation images.
  • Construction progress: construction progress photos.
  • Finishing examples: finishing examples.
  • Infrastructure: project infrastructure.
  • View: views and surroundings.

Not every category must be present in every project. If the category title is empty, images can be imported as uncategorized or placed in the general gallery.

There is no separate history/story XML tag in the current structure. News, promotional messages, and project marketing materials are passed through stocks. For construction history, the Construction progress category can be used if it is present in albums.

9. Amenities

amenities describes project amenities and features. For integration, it is better to use key, while localized values should be used for display.

<amenities>
  <amenity>
    <key>project_facilities_gym</key>
    <en>Gym</en>
    <ru>Тренажёрный зал</ru>
    <ar>صالة رياضية</ar>
  </amenity>
</amenities>

  • amenities: object. Amenities container.
  • amenity: object. One amenity.
  • key: enum. Technical key.
  • en / ru / ar: string. Amenity name in three languages.

The key projecet_hotel_license contains a typo, but it must be mapped as Hotel License. It is recommended to support the alias and not break the import.

10. Marketing Promotions: <stocks>

stocks are marketing campaigns, news, and promotional messages from developers. They may include special prices, discounts, launch terms, EOI announcements, temporary payment offers, and advertising materials. This block is not an inventory stock and does not define unit availability.

<stocks>
  <stock>
    <title>...</title>
    <description>...</description>
    <start_at>2025-06-26T00:00:00+04:00</start_at>
    <end_at/>
    <logo>https://...</logo>
  </stock>
</stocks>

  • stocks: object. Marketing messages container.
  • stock: object. One campaign, news item, or promotional announcement.
  • title: localized object. Promotion title.
  • description: localized HTML. Promotion description.
  • start_at: datetime. Start date.
  • end_at: datetime. End date; may be empty.
  • logo: url. Promotion image.

Use for_sale_count, layouts.sale_units_count, and sales_status for property availability, not stocks.

11. EOI

EOI means Expression of Interest. The block describes preliminary interest or deposit terms for projects in Presale (EOI) status.

<eoi>
  <is_eoi_return>0</is_eoi_return>
  <eoi_items>
    <eoi_item>
      <price>100000</price>
      <percent/>
      <description>
        <en>EOI amount for 2 Bedrooms</en>
        <ru>Сумма EOI для 2-комнатных</ru>
        <ar>...</ar>
      </description>
    </eoi_item>
  </eoi_items>
</eoi>

  • is_eoi_return: 0/1/empty. 0 = non-refundable, 1 = refundable, empty = not specified.
  • eoi_items: object. EOI terms container.
  • eoi_item: object. One EOI condition.
  • price: decimal. Fixed EOI amount.
  • percent: decimal. EOI percentage, if used.
  • description: localized object. Condition description.
  • sales_status.en = Presale (EOI) and eoi_items is filled: show EOI.
  • Any other sales_status: hide EOI.

12. Service Charge and Assignment

<service_charge>
  <value>172.22</value>
  <unit>sq. m</unit>
  <currency>AED</currency>
</service_charge>
<assignment>40.00</assignment>

  • service_charge.value: service charge amount. If empty, do not show the block.
  • service_charge.unit: calculation unit, usually sq. m. May be empty.
  • service_charge.currency: currency, usually AED. May be empty.
  • assignment: percentage after which assignment is possible. Empty = information not specified, not a restriction.

13. Payment Plans: <payment_plans>

payment_plans describes payment options for the property from the developer. One project may have multiple payment plans. Each plan breaks payment down by stages: booking, construction, handover, and post-handover. Fees and additional charges are passed separately, so the total percent may exceed 100%. For example, 104% may mean 100% of the property price + 4% DLD fee.

  • Basic: id, title, currency. Plan identifier, title, and currency. title is free text, not an enum.
  • Booking: on_booking_percent, on_booking_fix, on_booking_payments_count, on_booking_fees. Payments and fees at the booking stage.
  • Construction: on_construction_percent, on_construction_fix, on_construction_payments_count, on_construction_fees. Payments during construction.
  • Handover: on_handover_percent, on_handover_fix, on_handover_payments_count, on_handover_fees. Payments at property handover.
  • Post-handover: post_handover_percent, post_handover_fix, on_post_handover_payments_count, on_post_handover_fees. Payments after handover.
  • ROI: roi_percent, roi_fix, roi_payments_count, roi_fees. Fields for ROI or guaranteed income schemes.
  • Additional fees: additional, additional_percent, additional_fix, additional_fix_m2. Additional payments, for example DLD Fee.
  • Periods: period_after_handover, period_after_roi. Frequency of recurring payments.
  • Totals: price_total, fees_included_total. Total plan amounts and included fees.

14. Layouts: <layouts>

layouts describes a typical layout inside a project. It is an aggregated unit type, not a specific apartment or office.

  • id: integer. Unique layout ID. Use as the external layout ID.
  • title: localized object. Layout name. Display according to interface language.
  • project_id: integer. Parent project ID. Link with offers.complex-id.
  • building_name: localized object. Building name. Do not display if empty.
  • price_on_request: 0/1. Price hiding flag. If 1, do not show the price.
  • area_min / area_max: object. Area range. m2 and ft2.
  • area_balcony_min / area_balcony_max: object. Balcony area range. May be empty.
  • type: localized object. Property type. See Unit type reference.
  • sale_units_count: integer. Number of available units of this type. It is not a list of lots.
  • album: object. Layout gallery. Show at layout level.
  • levels_photos: object. Images by level. Use as floor plans.
  • floors_count: integer. Number of levels. 1, 2, 3, etc.
  • rooms_count: localized object. Room count. See Rooms count reference.
  • price: object. Layout price range. Hide when price_on_request=1.
  • is_limited_publication: 0/1. Publication restriction. If 1, hide publicly.

15. Enum Value References

  • Project type: project, compound.
  • Sales status: Preliminary Info, Announcement, Presale (EOI), Launch, On Sale, Sold Out, Pending.
  • Construction status: Scheduled, Ready, Stopped, In Progress.
  • Unit type: Apartment, Villa, Townhouse, Duplex, Triplex, Penthouse, Retail, Office, Suite.
  • Rooms count: Studio, 1 BR, 2 BR, 3 BR, 4 BR, 5 BR, 6 BR, 7 BR, 8 BR, NA.
  • BR price key: studio, 1, 2, 3, 4, 5, 6, villa, townhouse, n.
  • Gallery category: Project presentation, Construction progress, Finishing examples, Infrastructure, View.
  • Currency: AED.
  • Service charge unit: sq. m.
  • Boolean flags: 0, 1; empty is allowed for some fields.

If the feed contains a value that is not in the reference list, the import must not fail. The value must be stored as a raw value, mapped as unknown, and logged for review.

16. Empty Values

An empty value means “not specified”, not 0. Empty tags may look like <field/> or <field></field>.

  • assignment: assignment condition is not specified.
  • service_charge.value: service charge is not specified.
  • eoi.is_eoi_return: EOI refundability is not specified.
  • area_balcony_min.m2: balcony area is not specified.
  • description.en: description is missing.

17. Display Rules

  • Price hidden: price_on_request = 1. Show “Price on request”.
  • Price visible: price_on_request = 0. Show price min/max.
  • EOI: sales_status.en = Presale (EOI) and EOI is filled. Show EOI.
  • EOI not relevant: sales_status.en != Presale (EOI). Hide EOI.
  • Sold out: is_sold_out = 1 or sales_status.en = Sold Out. Show “Sold out” or hide from listing.
  • Limited publication: is_limited_publication = 1. Do not publish publicly.
  • Assignment empty: assignment empty. Do not show the assignment block.
  • Service charge empty: service_charge.value empty. Do not show service charge.

18. Import Rules

  • Project: search by complex-id; if found, update; if not found, create.
  • Layout: search by layouts.id; link to project by project_id.
  • Deletion: if an object disappears from the new feed, mark it inactive instead of deleting it immediately.
  • Unknown enum: store raw value, map as unknown, and log.
  • Empty values: do not convert to 0 without an explicit field-specific rule.

Project field → Source

  • external_project_id: complex-id.
  • raw_offer_type: type.
  • title_*: title.
  • description_*: description.
  • developer_name: developer.title.
  • developer_logo_url: developer.logo.
  • city/address/coordinates: city, address, latitude, longitude.
  • districts: districts.district.
  • construction_status: status.en.
  • sales_status: sales_status.en.
  • price_min / price_max: price.
  • price_on_request: price_on_request.
  • galleries: photo, album, albums.
  • payment_plans: payment_plans.
  • eoi: eoi.
  • stocks: stocks.
  • source_updated_at: updated_at.

Layout field → Source

  • external_layout_id: layouts.id.
  • external_project_id: layouts.project_id.
  • title_*: layouts.title.
  • building_name_*: building_name.
  • unit_type: type.en.
  • rooms_count: rooms_count.en.
  • sale_units_count: sale_units_count.
  • area_min / area_max: area_min, area_max.
  • balcony_min / balcony_max: area_balcony_min, area_balcony_max.
  • floors_count: floors_count.
  • price_min / price_max: price.
  • layout_gallery: album.
  • levels_photos: levels_photos.
  • is_limited_publication: is_limited_publication.