21 5月

プロジェクトとレイアウトのXMLフィード

1. フィードの目的

XMLフィードは、不動産プロジェクトと代表的な間取りに関する構造化データを送信します。受信側システムが、プロジェクトカードの自動作成・更新、価格、ステータス、ギャラリー、設備、支払い条件、EOI、デベロッパー提供のマーケティングプロモーション素材を表示できるようにすることが目的です。

このフィードは、間取りを集約形式で送信します。1つの間取りレコードで代表的な間取りと、そのタイプの利用可能なユニット数を表します。特定のアパート、オフィス、区画の一覧ではありません。

realty-feed: XMLフィード全体のルートコンテナ。メインID: —
offers: 1つのプロジェクトまたは複合施設。メインID: complex-id
layouts: プロジェクト内の代表的な間取り。メインID: id
payment_plans: 1つのプロジェクトの支払いオプション。メインID: id
eoi_item: 1つのEOI条件。メインID: —
stock: デベロッパーによるマーケティングキャンペーン、ニュース、またはプロモーションメッセージ。メインID: —

1.1 XMLフィードとは

XMLフィードは、不動産プロジェクトと代表的な間取りに関するデータを含む構造化ファイルです。物件を仲介サイトやカタログに表示するために必要な、説明文、写真、価格、住所、ステータス、仕様、設備などのデータを含みます。

簡単に言うと、XMLフィードは不動産に関するデータストリームであり、受信側システムが定期的にダウンロード・読み込みを行い、物件カードを自動更新するために利用します。

Alnairはデータを提供します。Webサイト開発、カタログ開発、CRM連携、インポートロジックは、クライアントまたはクライアントの技術チームが担当します。

1.2 仲介会社に必要なもの

XMLフィードを利用するには、XMLを定期的にダウンロードし、構造を解析し、自社システム内のデータを更新できる技術基盤が必要です。

Webサイトまたは物件カタログ: フィード内のプロジェクトと間取りを表示する場所。
技術チームまたは開発者: XMLのダウンロード、解析、インポート設定。
XMLパーサー: XML構造を読み取り、内部データモデルに変換する機能。
インポートモジュール: プロジェクトと間取りの作成、更新、無効化。
タスクスケジューラ: cronやschedulerなどによる定期インポート実行。
エラーログ: 未知のenum値、空欄、読み込みエラーの監視。

1.3 仲介会社でのXMLフィードの使い方

一般的なワークフローは次のとおりです。

仲介会社のシステムが、個別のWebリンクからXMLをダウンロードします。
XMLは、診断や再処理のために生データとして保存されます。
パーサーが realty-feed、offers、layouts の構造とネストされたブロックを読み取ります。
インポートモジュールが新規プロジェクトと間取りを作成、または既存データを更新します。
新しいフィードから消えた物件は非アクティブとしてマークされます。
仲介会社のWebサイトに、最新のプロジェクトカード、価格、ギャラリー、ステータスが表示されます。

主な連携機能:

自動更新: プロジェクトと間取りが手動操作なしで更新されます。
物件ページ作成: フィードデータをプロジェクトカードや間取りカードに使用します。
最新の価格とステータス: Webサイトはスケジュールに従ってXML更新を受信します。
絞り込みと検索: 地区、価格、物件タイプ、部屋数、面積で検索フィルターを設定できます。
メディアギャラリー: プロジェクト写真、テーマ別ギャラリー、間取り画像を表示できます。

2. XMLの基本構造

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

realty-feed: オブジェクト。ルートフィードブロック。
generation-date: datetime。XML生成日時。データの新しさ確認に使用します。
offers: object[]。プロジェクトまたは複合施設の一覧。各 offers ブロックにはプロジェクトデータとその間取りが含まれます。

2.1 フィードのアクセスとダウンロード制限

フィードは、個別のWebリンクを通じてクライアントに提供されます。このリンクはクライアント専用で、受信側システムがXMLを自動ダウンロードするために使用します。

個別リンクは、Alnairアカウントの管理者に提供されます。管理者は、このリンクをクライアントの技術チームに渡してインポート設定を行えます。

アクセス方式: 個別Webリンク。クライアント専用のXMLフィードURL。
リンクの取得先: Alnairアカウント。リンクはクライアント管理者が利用できます。
フィード更新頻度: 4時間ごと。XMLデータはAlnair側で4時間ごとに更新されます。
最小ダウンロード間隔: 1時間に1回以内。受信側システムは1時間に1回を超えてフィードにアクセスしてはいけません。
制限超過: アクセスブロック。リクエストが頻繁すぎる場合、フィードアクセスが一時的にブロックされることがあります。

推奨される連携ロジック: cronやschedulerによる定期ダウンロードを設定し、最後に受信したXMLを保存し、Webサイトのページ読み込みごとにフィードを取得しないことです。最適な運用は、約4時間ごとに新しいデータが反映される点を踏まえつつ、フィードの取得を1時間に1回以内に抑える方法です。

3. プロジェクト: <offers>

offers はフィードの主要エンティティです。プロジェクトの説明、デベロッパー、所在地、建設・販売ステータス、価格、メディア、設備、支払いプラン、EOI、マーケティングプロモーション、代表的な間取りを含みます。

<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: 整数。Alnair内の一意なプロジェクトID。upsert用の外部プロジェクトIDとして使用します。
type: enum。トップレベルのエンティティタイプ: project または compound。生の値を保存し、トップレベルのプロジェクトとしてインポートします。
logo: url。プロジェクトロゴ。ブランディングに表示し、カバー画像としては使用しません。
photo: url。プロジェクトのメイン画像／カバー。カバー画像およびヒーロー画像として使用します。
title: localized object。en/ru/ar のプロジェクト名。インターフェース言語に応じて表示します。
description: localized HTML。en/ru/ar のプロジェクト説明。安全にレンダリングし、HTMLはCDATA内にあります。
price_on_request: 0/1。価格非表示フラグ。1の場合は「Price on request」を表示します。
status: object。建設ステータス。sales_status と混同しないでください。
construction_start_at: datetime。建設開始日。入っていれば表示します。
construction_progress: decimal。建設進捗率。パーセンテージで表示します。
planned_completion_at: datetime。予定完成日。引き渡し日として使用します。
predicted_completion_at: datetime。予測完成日。更新後の完成日として使用できます。
amenities: object。設備・特徴。キーでマッピングします。
developer: object。デベロッパー。名称とロゴを保存します。
city / address: string。プロジェクトの都市と住所。所在地データに使用します。
latitude / longitude: decimal。座標。地図表示に使用します。
districts: object。プロジェクトの地区。フィルターとカード表示に使用します。
album: object。未分類のメインギャラリー。一般ギャラリーとして表示します。
albums: object。テーマ別ギャラリー。タイトルごとにグループ化します。
for_sale_count: integer。プロジェクト内の販売可能ユニット数。在庫数として表示できます。
price: object。プロジェクト全体の価格帯。price_on_request=1 の場合は非表示にします。
br_prices: object[]。ベッド数またはカテゴリ別価格。フィルターや一覧表示に使用します。
updated_at: datetime。プロジェクト更新日。同期に使用します。
is_sold_out: 0/1。完売フラグ。sales_status と併用します。
payment_plans: object[]。デベロッパーの支払いオプション。支払い方法として表示します。
sales_status: localized object。プロジェクトの販売ステータス。販売段階を定義します。
stocks: object。デベロッパーによるマーケティングキャンペーンやプロモーションメッセージ。プロモーションブロックとして表示します。
eoi: object。Expression of Interest。Presale (EOI) の場合のみ表示します。
service_charge: object。管理費。値が入っていれば表示します。
assignment: decimal。譲渡条件。空欄は未指定を意味します。
is_limited_publication: 0/1。公開制限。1の場合は許可なく公開しません。
layouts: object[]。プロジェクトの代表的な間取り。子エンティティとしてインポートします。

4. ローカライズフィールド

ローカライズフィールドは同じ構造で、タグ内に英語・ロシア語・アラビア語の値が入ります。

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

en: 英語の値。推奨フォールバック。
ru: ロシア語の値。
ar: アラビア語の値。

フォールバック規則:

表示言語に値があれば、それを使用します。
必要な言語が空の場合は en を使用します。
en が空の場合は ru を使用します。
ru が空の場合は ar を使用します。
すべて空の場合はフィールドを表示しません。

5. ステータス

5.1 建設ステータス: <status>

建設ステータスは、プロジェクトの物理的な進行状況を示します。販売可否は示しません。

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

Scheduled: 予定中のプロジェクトです。
In Progress: 建設中です。
Ready: 完成済みです。
Stopped: 建設が停止しています。

5.2 販売ステータス: <sales_status>

販売ステータスは、告知、プレセール、ローンチ、販売中、完売など、プロジェクトの商業段階を示します。

Preliminary Info: 初期情報です。
Announcement: プロジェクトが発表されました。
Presale (EOI): EOI受付中です。
Launch: 販売開始です。
On Sale: 購入可能です。
Sold Out: 完売しています。
Pending: ステータス更新待ちです。

6. デベロッパーと所在地

これらのブロックは、デベロッパーブランドとプロジェクトの地理的位置を表示するために必要です。

<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.logo: url。デベロッパーロゴ。
city: string。都市。
address: string。住所。
latitude / longitude: decimal。地図用座標。
districts.district: string[]。プロジェクトの地区。

7. 価格

7.1 プロジェクト価格: <price>

プロジェクトレベルの価格は、プロジェクト内の利用可能な物件の一般的な価格帯を示します。

min: decimal。最低価格。
max: decimal。最高価格。
min_usd: decimal。USD建て最低価格。
max_usd: decimal。USD建て最高価格。
currency: enum。基準通貨。通常は AED です。

price_on_request = 1 の場合、price が入っていても正確な価格は公開表示されません。

7.2 カテゴリ別価格: <br_prices>

br_prices は、ベッド数または物件タイプごとに価格と面積をまとめます。フィルターや簡易カード表示に便利です。

<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: スタジオ。
1-6: ベッドルーム数。
villa: ヴィラ。
townhouse: タウンハウス。
n: 該当なし／非住宅カテゴリ／その他。

8. メディア

フィード内のメディアはいくつかの種類に分かれています。用途を考慮せずに1つのギャラリーへまとめないでください。1枚はカバー、1枚はロゴ、1枚はプロモーション画像、1枚は間取り図である場合があります。

logo: offers.logo。プロジェクトロゴ。ブランディングに表示し、カバーには使用しません。
photo: offers.photo。プロジェクトのメイン画像／カバー。カードのカバー画像とプロジェクトページのヒーロー画像として使用します。
album.image: offers.album.image。未分類のメインギャラリー。一般プロジェクトギャラリーに表示します。
albums.album.images.image: offers.albums.album.images.image。テーマ別プロジェクトギャラリー。albums.album.title ごとにグループ化します。
developer.logo: offers.developer.logo。デベロッパーロゴ。デベロッパーブロックに表示します。
stocks.stock.logo: offers.stocks.stock.logo。マーケティングキャンペーン画像。プロモーションブロック内に表示します。
layouts.album.image: offers.layouts.album.image。特定の代表的間取りのギャラリー。間取りレベルで表示します。
levels_photos.level_photo.image: offers.layouts.levels_photos.level_photo.image。階層別の間取り画像。間取り図として使用します。

<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: プロジェクト紹介画像。
Construction progress: 建設進捗写真。
Finishing examples: 内装仕上げ例。
Infrastructure: プロジェクトのインフラ。
View: 眺望と周辺環境。

すべてのプロジェクトにすべてのカテゴリが必要なわけではありません。カテゴリタイトルが空の場合、画像は未分類としてインポートするか、一般ギャラリーに配置できます。

現行構造には、history/story に相当する独立したXMLタグはありません。ニュース、プロモーションメッセージ、プロジェクトのマーケティング素材は stocks 経由で送信されます。建設履歴については、albums に含まれている場合は Construction progress カテゴリを使用できます。

9. 設備

amenities は、プロジェクトの設備や特徴を表します。連携では key を使用し、表示にはローカライズ値を使用するのが最適です。

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

amenities: object。設備コンテナ。
amenity: object。1つの設備。
key: enum。技術キー。
en / ru / ar: string。3言語の設備名。

key projecet_hotel_license には টাইポがありますが、Hotel License としてマッピングする必要があります。エイリアスをサポートし、インポートを壊さないことを推奨します。

10. マーケティングプロモーション: <stocks>

stocks は、デベロッパーによるマーケティングキャンペーン、ニュース、プロモーションメッセージです。特別価格、割引、ローンチ条件、EOI告知、期間限定の支払いオファー、広告素材などが含まれる場合があります。このブロックは在庫数ではなく、ユニットの利用可能数を定義しません。

<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。マーケティングメッセージのコンテナ。
stock: object。1つのキャンペーン、ニュース項目、またはプロモーション告知。
title: localized object。プロモーションタイトル。
description: localized HTML。プロモーション説明。
start_at: datetime。開始日。
end_at: datetime。終了日。空欄も可。
logo: url。プロモーション画像。

物件の在庫状況には stocks ではなく、for_sale_count、layouts.sale_units_count、sales_status を使用してください。

11. EOI

EOI は Expression of Interest を意味します。このブロックは、Presale (EOI) ステータスのプロジェクトにおける事前申込やデポジット条件を示します。

<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/空欄。0 = 返金不可、1 = 返金可、空欄 = 未指定。
eoi_items: object。EOI条件コンテナ。
eoi_item: object。1つのEOI条件。
price: decimal。固定EOI金額。
percent: decimal。必要に応じてEOIの割合。
description: localized object。条件説明。

sales_status.en = Presale (EOI) かつ eoi_items が入力済み: EOIを表示します。
それ以外の sales_status: EOIを非表示にします。

12. 管理費と譲渡条件

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

service_charge.value: 管理費金額。空欄の場合はブロックを表示しません。
service_charge.unit: 計算単位。通常は sq. m。空欄可。
service_charge.currency: 通貨。通常は AED。空欄可。
assignment: 譲渡可能となる割合。空欄 = 未指定であり、制限ではありません。

13. 支払いプラン: <payment_plans>

payment_plans は、デベロッパーが提供する物件の支払いオプションを示します。1つのプロジェクトに複数の支払いプランがある場合があります。各プランは、予約、建設中、引き渡し時、引き渡し後の段階ごとに分かれます。手数料や追加費用は別途送信されるため、合計割合が100%を超えることがあります。たとえば、104% は物件価格の100% + DLD手数料4%を意味する場合があります。

Basic: id, title, currency。プラン識別子、タイトル、通貨。title は列挙値ではなく自由入力です。
Booking: on_booking_percent, on_booking_fix, on_booking_payments_count, on_booking_fees。予約時の支払いと手数料。
Construction: on_construction_percent, on_construction_fix, on_construction_payments_count, on_construction_fees。建設中の支払い。
Handover: on_handover_percent, on_handover_fix, on_handover_payments_count, on_handover_fees。引き渡し時の支払い。
Post-handover: post_handover_percent, post_handover_fix, on_post_handover_payments_count, on_post_handover_fees。引き渡し後の支払い。
ROI: roi_percent, roi_fix, roi_payments_count, roi_fees。ROIや保証収益スキーム向けの項目。
追加費用: additional, additional_percent, additional_fix, additional_fix_m2。DLD Fee などの追加支払い。
期間: period_after_handover, period_after_roi。定期支払いの頻度。
合計: price_total, fees_included_total。プラン全体の合計金額と含まれる手数料。

14. 間取り: <layouts>

layouts は、プロジェクト内の代表的な間取りを示します。特定のアパートやオフィスではなく、集約されたユニットタイプです。

id: integer。一意の間取りID。外部間取りIDとして使用します。
title: localized object。間取り名。インターフェース言語に応じて表示します。
project_id: integer。親プロジェクトID。offers.complex-id と連携します。
building_name: localized object。建物名。空欄の場合は表示しません。
price_on_request: 0/1。価格非表示フラグ。1の場合は価格を表示しません。
area_min / area_max: object。面積範囲。m2 と ft2。
area_balcony_min / area_balcony_max: object。バルコニー面積範囲。空欄の場合があります。
type: localized object。物件タイプ。Unit type reference を参照します。
sale_units_count: integer。このタイプで販売可能なユニット数。区画一覧ではありません。
album: object。間取りギャラリー。間取りレベルで表示します。
levels_photos: object。階層別画像。間取り図として使用します。
floors_count: integer。階数。1、2、3 など。
rooms_count: localized object。部屋数。Rooms count reference を参照します。
price: object。間取りの価格帯。price_on_request=1 の場合は非表示にします。
is_limited_publication: 0/1。公開制限。1の場合は公開しません。

15. enum値の参照

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; 一部のフィールドでは空欄も可。

フィードに参照リストにない値が含まれていても、インポートは失敗してはいけません。値は生値として保存し、unknown としてマッピングし、レビュー用に記録してください。

16. 空の値

空の値は「0」ではなく、「未指定」を意味します。空タグは <field/> または <field></field> の形で表されます。

assignment: 譲渡条件は未指定です。
service_charge.value: 管理費は未指定です。
eoi.is_eoi_return: EOIの返金可否は未指定です。
area_balcony_min.m2: バルコニー面積は未指定です。
description.en: 説明文がありません。

17. 表示ルール

価格非表示: price_on_request = 1。「Price on request」を表示します。
価格表示: price_on_request = 0。価格の最小／最大を表示します。
EOI: sales_status.en = Presale (EOI) かつ EOI が入力済み。EOIを表示します。
EOI不要: sales_status.en != Presale (EOI)。EOIを非表示にします。
完売: is_sold_out = 1 または sales_status.en = Sold Out。「Sold out」を表示するか、一覧から非表示にします。
公開制限: is_limited_publication = 1。公開しません。
assignment 空欄: assignment が空。assignment ブロックは表示しません。
service charge 空欄: service_charge.value が空。管理費は表示しません。

18. インポートルール

Project: complex-id で検索し、あれば更新、なければ作成します。
Layout: layouts.id で検索し、project_id でプロジェクトに紐付けます。
削除: 新しいフィードからオブジェクトが消えた場合、即削除せず非アクティブにします。
Unknown enum: 生値を保存し、unknown としてマップし、記録します。
空の値: フィールドごとの明示ルールがない限り、0 に変換しません。

19. 推奨データ構造

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.