البحث عن الإعلانات (GET /listings) — Kite API
Kiteالمنصة
الاستخداماتالتوثيقالأدلةالباقات
تصفح نقاط النهاية
كل نقاط النهاية

البيانات المرجعية

  • قائمة المدن
  • قائمة الأحياء
  • قائمة جهات المدينة
  • قائمة قيم التعداد
  • حدود هذا المفتاح
  • ما يغطيه API

الإعلانات

  • البحث عن الإعلانات
  • عدّ الإعلانات
  • جلب الإعلانات بالمعرّف
  • جلب إعلان
  • سجل سعر إعلان

بيانات السوق

  • ملخص السوق
  • توزيع الأسعار
  • توزيع المساحات
  • المعروض الجديد
  • مؤشر الشغور
  • الأسعار بحسب الحي
  • الإيجار التجاري للمتر المربع بحسب الحي

البيانات الرسمية

  • الإيجارات المسجلة لدى الهيئة العامة للعقار
  • مؤشر كايت العقاري

التحليلات

  • جلب الإعلانات المقارنة
  • موقع سعر الإعلان في السوق
  • نطاق أسعار العرض القريبة لإعلان
  • إعلانات أقل من أسعار السوق
  • إعلانات أقل من أسعار السوق (المسار القديم)
  • العائد الإيجاري الإجمالي
  • اتجاهات الأسعار
  • مقارنة الأحياء

الصفقات المسجلة

  • البحث في الصفقات المسجلة
  • إحصاءات الصفقات المسجلة
  • أسعار الأراضي لكل م²

المشاريع على الخارطة

  • البحث في المشاريع العقارية
  • جلب مشروع عقاري
  • قائمة وحدات مشروع
  • البحث في وحدات المشاريع
  • قائمة المطورين

التصدير

  • إنشاء تصدير
  • قائمة الصادرات
  • جلب تصدير

الإدارة

  • جلب مؤسستك
  • قائمة مفاتيح البيانات
  • إنشاء مفتاح بيانات
  • إلغاء مفتاح
  • قائمة مشاريع المؤسسة
  • الاستخدام اليومي
  • قائمة الأعضاء والدعوات
  • قائمة أحداث التدقيق
  • قائمة سجلات الطلبات
  • إنشاء نقطة Webhook
  • قائمة نقاط Webhook
  • حذف نقطة Webhook
  • قائمة عمليات التسليم
  • إعادة تشغيل تسليم

المرجع التفاعلي

كل نقاط النهاية

البيانات المرجعية

  • قائمة المدن
  • قائمة الأحياء
  • قائمة جهات المدينة
  • قائمة قيم التعداد
  • حدود هذا المفتاح
  • ما يغطيه API

الإعلانات

  • البحث عن الإعلانات
  • عدّ الإعلانات
  • جلب الإعلانات بالمعرّف
  • جلب إعلان
  • سجل سعر إعلان

بيانات السوق

  • ملخص السوق
  • توزيع الأسعار
  • توزيع المساحات
  • المعروض الجديد
  • مؤشر الشغور
  • الأسعار بحسب الحي

الإعلانات

البحث عن الإعلانات

GET/listings

إعلانات نشطة منزوعة التكرار في مدينة، بتصفية الجودة نفسها في kite.sa. تصفح بـcursor. تحد الخطة عمق كل استعلام؛ لنسخ المعروض رتّب بـupdated_asc وحرّك updated_since.

تراقب الإعلانات الجديدة؟ اشترك بدل الاستعلام المتكرر. يرسل الويبهوك (POST /organization/webhooks) listing.created وlisting.price_changed وlisting.delisted إلى عنوانك للمرشّحات نفسها في هذه النقطة، فلا تعيد هذا الاستعلام مع sort=newest على مؤقت. لا تُحتسب عمليات التسليم بالوحدات: تدفع فقط مقابل الإعلانات التي تجلبها بعدها. راجع دليل الويبهوك.

الأسعار أسعار عرض: يبين price.price_basis في كل إعلان هل price.yearly_sar إيجار سنوي أم سعر بيع إجمالي.

المصادقة
أرسل مفتاح بيانات (dk_live_… أو dk_test_…) بصيغة Bearer.
النطاق
listings
التكلفة
ليس رقمًا وحدة لكل طلب

المعاملات

الاسمالنوعالوصف
cityمطلوبالاستعلامstring

اسم المدينة المختصر من GET /cities. تُقبل بلدة داخل منطقة مغطاة وتُحوَّل إلى مدينتها (dammam وkhobar وdhahran وjubail وqatif إلى eastern_province؛ وburaydah و إلى ؛ و إلى )، وكذلك أسماء المدن بالعربية. يبين في الاستجابة وترويسة الاسم المختصر المستخدم.

Kite API

بيانات العقارات السعودية للمطوّرين.

المنتج
  • مرجع API
  • تغطية البيانات
  • الباقات
  • فحوصات التقييم
  • سجل التحديثات
  • حالة الخدمة
الشركة
  • kite.sa
  • تواصل معنا
  • الأمان
الشؤون القانونية
  • الشروط
  • جهات المعالجة الفرعية
© Kite
الإيجار التجاري للمتر المربع بحسب الحي

البيانات الرسمية

  • الإيجارات المسجلة لدى الهيئة العامة للعقار
  • مؤشر كايت العقاري

التحليلات

  • جلب الإعلانات المقارنة
  • موقع سعر الإعلان في السوق
  • نطاق أسعار العرض القريبة لإعلان
  • إعلانات أقل من أسعار السوق
  • إعلانات أقل من أسعار السوق (المسار القديم)
  • العائد الإيجاري الإجمالي
  • اتجاهات الأسعار
  • مقارنة الأحياء

الصفقات المسجلة

  • البحث في الصفقات المسجلة
  • إحصاءات الصفقات المسجلة
  • أسعار الأراضي لكل م²

المشاريع على الخارطة

  • البحث في المشاريع العقارية
  • جلب مشروع عقاري
  • قائمة وحدات مشروع
  • البحث في وحدات المشاريع
  • قائمة المطورين

التصدير

  • إنشاء تصدير
  • قائمة الصادرات
  • جلب تصدير

الإدارة

  • جلب مؤسستك
  • قائمة مفاتيح البيانات
  • إنشاء مفتاح بيانات
  • إلغاء مفتاح
  • قائمة مشاريع المؤسسة
  • الاستخدام اليومي
  • قائمة الأعضاء والدعوات
  • قائمة أحداث التدقيق
  • قائمة سجلات الطلبات
  • إنشاء نقطة Webhook
  • قائمة نقاط Webhook
  • حذف نقطة Webhook
  • قائمة عمليات التسليم
  • إعادة تشغيل تسليم

المرجع التفاعلي

unaizah
qassim
hofuf
al_ahsa
filters.city
X-Resolved-City
listing_typeمطلوبالاستعلامstring

إحدى القيم: rent, sale

listing_categoryالاستعلامstring

احذفه لتضمين النوعين.

إحدى القيم: residential, commercial

property_typeالاستعلامstring[]

قيمة أو أكثر، مفصولة بفواصل.

إحدى القيم: apartment, villa, floor, duplex, office, shop, warehouse, land, building

neighborhood_idالاستعلامinteger[]

معرّفات الأحياء من GET /cities/{city}/neighborhoods.

bedsالاستعلامinteger

عدد غرف النوم المطابق تمامًا لكل قيمة بما فيها 5. يعامل مرشّح kite.sa الرقم 5 كخمس غرف أو أكثر، فتختلف مجموعات النتائج هنا. استخدم beds_min للنطاق.

beds_minالاستعلامinteger

أقل عدد لغرف النوم.

beds_maxالاستعلامinteger

أكبر عدد لغرف النوم.

bathrooms_minالاستعلامinteger

أقل عدد لدورات المياه.

price_minالاستعلامinteger

بالريال السعودي. سنوي للإيجار؛ راجع price.yearly_sar.

price_maxالاستعلامinteger

بالريال السعودي. سنوي للإيجار؛ راجع price.yearly_sar.

area_minالاستعلامnumber

أمتار مربعة.

area_maxالاستعلامnumber

أمتار مربعة.

furnishedالاستعلامstring

هل العقار مفروش؟ احذفه لتضمين الإعلانات التي لم تحدد ذلك.

إحدى القيم: true, false

sourceالاستعلامstring[]

منصات المصادر، راجع GET /enums. لا تُفحص القيم مقابل القائمة، لذا يعيد المصدر المكتوب خطأ نتائج فارغة بدل خطأ.

bboxالاستعلامstring

مستطيل الإحاطة west,south,east,north بالدرجات وبترتيب GeoJSON.

updated_sinceالاستعلامstring (date-time)

إعلانات updated_at فيها عند وقت ISO 8601 هذا أو بعده فقط. ادمجه مع sort=updated_asc للمزامنة.

bathroomsالاستعلامinteger

عدد دورات المياه المطابق تمامًا.

bathrooms_maxالاستعلامinteger

أكبر عدد لدورات المياه.

livings_minالاستعلامinteger

أقل عدد لغرف المعيشة.

neighborhood_id_excludeالاستعلامinteger[]

استبعد هذه الأحياء بمعرّفات GET /cities/{city}/neighborhoods. تبقى الإعلانات التي تعذر تعيين حيّها، بخلاف neighborhood_id الذي يستبعدها.

qالاستعلامstring

مطابقة نص حر في عنوان المعلن ووصفه كما نشرهما، لا headline الذي يصوغه كايت للاستجابة. يجب ظهور كل الكلمات؛ استخدم "quote a phrase" لمطابقة عبارة كاملة و| بين الكلمات لقبول أي منها. المصادر بلا عنوان، ومنها عقار، تُطابق الوصف فقط.

amenitiesالاستعلامstring[]

إعلانات تحتوي كل هذه المرافق فقط. راجع GET /enums.

إحدى القيم: ac, kitchen, maid_room, parking, private_roof, lift, pool, gym, balcony, garden, laundry_room

amenities_excludeالاستعلامstring[]

استبعد الإعلانات التي تحتوي أيًا منها.

إحدى القيم: ac, kitchen, maid_room, parking, private_roof, lift, pool, gym, balcony, garden, laundry_room

photo_featuresالاستعلامstring[]

فقط الإعلانات التي تُظهر صورها كل ما يلي: real_photos (صور العقار نفسه لا التصاميم ولا الصور الجاهزة)، kitchen_installed (مطبخ راكب)، ac_split، pool، roof_terrace، balcony، large_windows (صالة أو غرفة نوم بنوافذ كبيرة). تُقرأ هذه من صور الإعلان بنموذج رؤية آلي، ولا تُنشر إلا للمميزات التي يتعرّف عليها بدقة عالية. لذلك هذا مرشّح «يجب أن تتوفر» فقط: الإعلان الذي لا تُظهر صوره الميزة، أو الذي لم يُحلَّل بعد، لا يطابق، ولا توجد طريقة لطلب إعلانات بلا ميزة معيّنة. التغطية تشمل المنازل التي لها صور، وقد لا تكون الإعلانات المضافة حديثًا قد حُلّلت بعد.

إحدى القيم: real_photos, kitchen_installed, ac_split, pool, roof_terrace, balcony, large_windows

floorالاستعلامstring

ground للأرضي وupper لأي طابق معلن فوقه. لا يقسمان كل النتائج: الإعلان بلا طابق محدد لا يدخل أيًا منهما.

إحدى القيم: ground, upper

source_excludeالاستعلامstring[]

استبعد منصات المصادر هذه؛ راجع GET /enums.

max_ageالاستعلامinteger

أقصى عمر للعقار بالسنوات. في الرياض يُطابَق العمر مع رخص البناء البلدية الصادرة منذ 2018: إذا ذكر الإعلان أن المبنى أحدث بأربع سنوات أو أكثر مما تسمح به أحدث رخصة، يُستخدم عمر الرخصة (سنة الرخصة مضافًا إليها سنة للبناء). ولا تجعل الرخصة المبنى أحدث مما يذكره إعلانه. ويسجّل عقار عمرًا يساوي 0 حين يترك المعلن الحقل فارغًا، لذا لا يُعدّ إعلان عقار بعمر 0 جديدًا إلا إذا دعمته رخصة في الرياض أو نص الإعلان نفسه (أول ساكن، لم يُسكن، حديث البناء)؛ وإلا فعمره غير معروف ولا يطابق الفلتر. وإذا ذكر وصف الإعلان نفسه عمر المبنى («العمر 8 سنوات») وكان أكبر بثلاث سنوات أو أكثر من حقل العمر، أو كان الحقل فارغًا، يُستخدم العمر الوارد في الوصف.

verifiedالاستعلامstring

true لما يعلّمه المصدر كمتحقق. تعني false البقية: غير المتحقق وما لم يذكر المصدر حالة تحققه.

إحدى القيم: true, false

advertiser_typeالاستعلامstring

الجهة التي نشرت الإعلان. يحتوي العمود ثماني قيم بحسب المصدر تجمعها هاتان الفئتان. الوسيط الذي لا يذكر هل هو شركة أم فرد لا يطابق أيًا منهما.

إحدى القيم: company, individual

compoundالاستعلامstring

اسم المجمع، بمطابقة جزئية.

in_compoundالاستعلامstring

الإعلانات التابعة لأي مجمع فقط.

إحدى القيم: true, false

rent_frequencyالاستعلامstring

فترة الإيجار في الإعلان. يبقى price.yearly_sar سنويًا؛ راجع price.as_posted.

إحدى القيم: monthly, yearly

days_on_market_minالاستعلامinteger

الأيام منذ رصد كايت للإعلان أول مرة.

days_on_market_maxالاستعلامinteger

الأيام منذ رصد كايت للإعلان أول مرة.

sortالاستعلامstring

newest بحسب أول رصد في كايت، وupdated_desc/updated_asc بحسب updated_at؛ استخدم updated_asc للمزامنة. وprice_asc/price_desc، وprice_drop للإعلانات التي انخفض سعرها فقط، الأكبر انخفاضًا أولًا، مع استبعاد الانخفاضات فوق 50% كتصحيحات محتملة، وdays_on_market_desc وrecommended. الأخير ترتيب كايت الذي يجمع السعر مقارنة بالنظائر ومدة الإعلان واكتماله والطلب على الحي، دون السماح لمصدر واحد بملء المقدمة. يُعاد ضبطه أحيانًا فتتغير نتائج الطلب بين الإصدارات. تصفح به بحرية لكن زامن بـupdated_asc.

إحدى القيم: newest, updated_desc, updated_asc, price_asc, price_desc, price_drop, days_on_market_desc, recommended

limitالاستعلامinteger
cursorالاستعلامstring

الاستجابة

الحقل data قائمة، ولكل عنصر فيها هذه الحقول.

الاسمالنوعالوصف
idمطلوبinteger
urlمطلوبstring

صفحة الإعلان في kite.sa.

titleمطلوبstring | null

عنوان المعلن كما نُشر. null للمصادر بلا عناوين، كعقار؛ استخدم headline للعرض.

headlineمطلوبstring

وصف إنجليزي قصير مبني من حقول الإعلان. موجود دائمًا.

descriptionمطلوبstring | null

كما نُشر، عادة بالعربية.

description_enمطلوبstring | null

الترجمة الإنجليزية حيث تتوفر.

listing_typeمطلوبstring
listing_categoryمطلوبstring | null
property_typeمطلوبstring
priceمطلوبobject
financingمطلوبobject
bedroomsمطلوبinteger | null
bathroomsمطلوبinteger | null
livingsمطلوبinteger | null

غرف المعيشة.

area_sqmمطلوبnumber | null
floorمطلوبstring | null
age_yearsمطلوبinteger | null
furnishedمطلوبboolean | null
amenitiesمطلوبstring[]
photo_featuresمطلوبobject[] | null

ما رآه نموذج رؤية في صور الإعلان، بقيم مرشّح photo_features نفسها. الأولوية للدقة: لا تُذكر الميزة إلا إذا ظهرت بوضوح، فغيابها يعني أنها لم تُرَ لا أنها غير موجودة. real_photos تعني أن صورة واحدة على الأقل صورة فوتوغرافية حقيقية (لا تصميم ثلاثي الأبعاد ولا مخطط ولا خريطة ولا تصميم إعلاني). null إذا لم تُحلَّل الصور بعد؛ تُحلَّل الإعلانات الجديدة خلال نحو ست ساعات، والسكنية فقط.

locationمطلوبobject
compound_nameمطلوبstring | null
project_idمطلوبinteger | null

مشروع على الخارطة تنتمي إليه الوحدة إن رُبطت.

imagesمطلوبstring[]

روابط الصور في CDN كايت.

image_countمطلوبinteger
advertiserمطلوبobject
verified_by_sourceمطلوبboolean | null

يعلّم المصدر الإعلان كمتحقق.

sourceمطلوبobject
also_listed_onمطلوبstring[]

مصادر أخرى للعقار نفسه. يعرض كايت إعلانًا واحدًا لكل عقار.

first_seen_atمطلوبstring (date-time) | null

وقت رصد كايت للإعلان أول مرة.

updated_atمطلوبstring (date-time) | null

آخر تحديث في المصدر أو آخر رصد لدى كايت إذا لم ينشر المصدر أوقات التحديث. يُستخدم في updated_since وترتيب updated_*.

last_seen_atمطلوبstring (date-time) | null

آخر تأكيد في كايت أن الإعلان نشط.

days_on_marketمطلوبinteger | null

مثال على الطلب

curl
curl "https://api.kite.sa/v1/listings?city=riyadh&listing_type=rent" \
  -H "Authorization: Bearer $KITE_API_KEY"
JavaScript (@kite-sa/sdk)
import { Kite } from "@kite-sa/sdk";

const kite = new Kite(); // reads KITE_API_KEY
const result = await kite.listings.search({ city: "riyadh", listing_type: "rent" });
Python (kite-sa)
from kite_sa import Kite

kite = Kite()  # reads KITE_API_KEY
result = kite.listings.search(city="riyadh", listing_type="rent")

افتح في المرجع التفاعلي

نقاط نهاية ذات صلة

  • عدّ الإعلانات GET /listings/count
  • جلب الإعلانات بالمعرّف GET /listings/batch
  • جلب إعلان GET /listings/{id}
  • سجل سعر إعلان GET /listings/{id}/price-history

الأدلة

  • البدء السريع
  • ما هو الإعلان العقاري؟
  • البحث والتصفية
  • مزامنة نسخة محلية
  • الحدود والحصص
  • تصفح الصفحات
  • الأخطاء