المعلنون بحسب الإعلانات المطابقة
GET/advertisers
المعلنون أصحاب الإعلانات التي يطابقها البحث: صف لكل معلن، فيه عدد إعلاناته المطابقة ونطاق أسعاره وأين يعلن. يقبل كل فلاتر GET /listings، فسؤال مثل «الوسطاء الذين لديهم شقق فوق 40,000 ريال سنويًا في شمال الرياض» طلب واحد بدل تصفّح الإعلانات وتجميعها بنفسك.
أي الإعلانات تُحتسب. الإعلانات النشطة نفسها، بعد إزالة التكرار وفلترة الجودة، التي يعيدها GET /listings لهذه الفلاتر، ومنها فقط ما يذكر GET /listings اسم معلنه: إعلان يحمل ترخيصًا من الهيئة العامة للعقار (ترخيص إعلان أو رخصة فال للوساطة) ولا يشمله طلب إزالة أو حجب. تُستبعد إعلانات المعلنين غير المرخصين أو غير المسمَّين، لذلك يكون totals.listings غالبًا أقل من GET /listings/count للفلاتر نفسها.
من هو المعلن الواحد. تُجمع الإعلانات بحسب اسم المكتب الظاهر في الإعلان (الشركة، أو اسم الشخص إن لم يذكر الإعلان شركة) دون تمييز بين الأحرف الكبيرة والصغيرة. لا يدمج كايت اختلافات الكتابة، فالمكتب الذي ينشر باسم عربي في مصدر وباسم إنجليزي في مصدر آخر يظهر مرتين. fal_number هو رخصة فال الأكثر ورودًا في إعلاناته المطابقة؛ والمكتب الذي يحمل كل وسيط فيه رخصته الخاصة له عدة رخص، وعددها في fal_licences.
فوق الوسيط. مرّر above_median_pct لاحتساب الإعلانات التي يزيد سعرها بأكثر من هذه النسبة على وسيط السعر المطلوب للإعلانات المماثلة فقط: المدينة ونوع الإعلان والحي ونوع العقار وعدد غرف النوم نفسها، حيث يوجد 5 إعلانات مماثلة على الأقل. القيمة 0 تعني أي زيادة. الإعلان الذي لا مجموعة مماثلة له (بلا حي، أو قلّ ما يماثله) لا يطابق أبدًا. يُحسب الوسيط على كل إعلانات المدينة ونوع الإعلان بعد فلترة الجودة، لا على ما يطابق فلاترك الأخرى فقط.
بلا أرقام هواتف. بيانات الاتصال ليست جزءًا من هذه الاستجابة. sample_listing_ids هي أعلى إعلانات المعلن المطابقة سعرًا؛ مرّر أحدها إلى GET /listings/{id}/contact (ويتطلب الصلاحية listings:contact) أو إلى GET /listings/batch.
الأسعار أسعار مطلوبة لإعلانات نشطة، بالريال؛ والإيجارات سنوية.
- المصادقة
- أرسل مفتاح بيانات (dk_live_… أو dk_test_…) بصيغة Bearer.
- النطاق
analytics- التكلفة
- 50 وحدة لكل طلب
المعاملات
| الاسم | الوصف |
|---|---|
cityمطلوبالنوع: string · الاستعلام | اسم المدينة المختصر من GET /cities. تُقبل بلدة داخل منطقة مغطاة وتُحوَّل إلى مدينتها ( |
listing_typeمطلوبالنوع: string · الاستعلام | إحدى القيم: |
listing_categoryالنوع: string · الاستعلام | احذفه لتضمين النوعين. إحدى القيم: |
property_typeالنوع: string[] · الاستعلام | قيمة أو أكثر، مفصولة بفواصل. إحدى القيم: |
neighborhood_idالنوع: integer[] · الاستعلام | معرّفات الأحياء من GET /cities/{city}/neighborhoods. |
bedsالنوع: integer · الاستعلام | عدد غرف النوم المطابق تمامًا لكل قيمة بما فيها 5. يعامل مرشّح kite.sa الرقم 5 كخمس غرف أو أكثر، فتختلف مجموعات النتائج هنا. استخدم |
beds_minالنوع: integer · الاستعلام | أقل عدد لغرف النوم. |
beds_maxالنوع: integer · الاستعلام | أكبر عدد لغرف النوم. |
bathrooms_minالنوع: integer · الاستعلام | أقل عدد لدورات المياه. |
price_minالنوع: integer · الاستعلام | بالريال السعودي. سنوي للإيجار؛ راجع |
price_maxالنوع: integer · الاستعلام | بالريال السعودي. سنوي للإيجار؛ راجع |
area_minالنوع: number · الاستعلام | أمتار مربعة. |
area_maxالنوع: number · الاستعلام | أمتار مربعة. |
furnishedالنوع: string · الاستعلام |
إحدى القيم: |
sourceالنوع: string[] · الاستعلام | منصات المصادر، راجع GET /enums. لا تُفحص القيم مقابل القائمة، لذا يعيد المصدر المكتوب خطأ نتائج فارغة بدل خطأ. |
bboxالنوع: string · الاستعلام | مستطيل الإحاطة |
updated_sinceالنوع: string (date-time) · الاستعلام | إعلانات |
bathroomsالنوع: integer · الاستعلام | عدد دورات المياه المطابق تمامًا. |
bathrooms_maxالنوع: integer · الاستعلام | أكبر عدد لدورات المياه. |
livings_minالنوع: integer · الاستعلام | أقل عدد لغرف المعيشة. |
neighborhood_id_excludeالنوع: integer[] · الاستعلام | استبعد هذه الأحياء بمعرّفات GET /cities/{city}/neighborhoods. تبقى الإعلانات التي تعذر تعيين حيّها، بخلاف |
qالنوع: string · الاستعلام | مطابقة نص حر في عنوان المعلن ووصفه كما نشرهما، لا |
amenitiesالنوع: string[] · الاستعلام | إعلانات تحتوي كل هذه المرافق فقط. راجع GET /enums. إحدى القيم: |
amenities_excludeالنوع: string[] · الاستعلام | استبعد الإعلانات التي تحتوي أيًا منها. إحدى القيم: |
photo_featuresالنوع: string[] · الاستعلام | فقط الإعلانات التي تُظهر صورها كل ما يلي: إحدى القيم: |
floorالنوع: string · الاستعلام |
إحدى القيم: |
source_excludeالنوع: string[] · الاستعلام | استبعد منصات المصادر هذه؛ راجع GET /enums. |
max_ageالنوع: integer · الاستعلام | أقصى عمر للعقار بالسنوات. في الرياض يُطابَق العمر مع رخص البناء البلدية الصادرة منذ 2018: إذا ذكر الإعلان أن المبنى أحدث بأربع سنوات أو أكثر مما تسمح به أحدث رخصة، يُستخدم عمر الرخصة (سنة الرخصة مضافًا إليها سنة للبناء). ولا تجعل الرخصة المبنى أحدث مما يذكره إعلانه. ويسجّل عقار عمرًا يساوي 0 حين يترك المعلن الحقل فارغًا، لذا لا يُعدّ إعلان عقار بعمر 0 جديدًا إلا إذا دعمته رخصة في الرياض أو نص الإعلان نفسه (أول ساكن، لم يُسكن، حديث البناء)؛ وإلا فعمره غير معروف ولا يطابق الفلتر. وإذا ذكر وصف الإعلان نفسه عمر المبنى («العمر 8 سنوات») وكان أكبر بثلاث سنوات أو أكثر من حقل العمر، أو كان الحقل فارغًا، يُستخدم العمر الوارد في الوصف. |
verifiedالنوع: string · الاستعلام |
إحدى القيم: |
advertiser_typeالنوع: string · الاستعلام | الجهة التي نشرت الإعلان، حيث يذكرها المصدر. إحدى القيم: |
compoundالنوع: string · الاستعلام | اسم المجمع، بمطابقة جزئية. |
in_compoundالنوع: string · الاستعلام | الإعلانات التابعة لأي مجمع فقط. إحدى القيم: |
rent_frequencyالنوع: string · الاستعلام | فترة الإيجار في الإعلان. يبقى إحدى القيم: |
days_on_market_minالنوع: integer · الاستعلام | الأيام منذ رصد كايت للإعلان أول مرة. |
days_on_market_maxالنوع: integer · الاستعلام | الأيام منذ رصد كايت للإعلان أول مرة. |
zoningالنوع: string[] · الاستعلام | الإعلانات التي تقع قطعتها ضمن أيٍّ من هذه التصنيفات ( إحدى القيم: |
cornerالنوع: string · الاستعلام |
إحدى القيم: |
street_width_minالنوع: number · الاستعلام | أدنى عرض بالأمتار لأعرض شارع تطل عليه القطعة ( |
white_land_feeالنوع: string · الاستعلام |
إحدى القيم: |
last_sale_within_monthsالنوع: integer · الاستعلام | الإعلانات التي لا يزيد عمر آخر صفقة مسجلة على قطعتها ( |
ask_to_last_sale_maxالنوع: number · الاستعلام | إعلانات البيع فقط: لا يزيد السعر المطلوب على هذا المضاعف من آخر صفقة مسجلة على القطعة، بين الإعلانات التي تتفق مساحتها مع مساحة الصك ( |
plot_soldالنوع: string · الاستعلام |
إحدى القيم: |
above_median_pctالنوع: number · الاستعلام | احتساب الإعلانات التي يزيد سعرها بأكثر من هذه النسبة على وسيط الإعلانات المماثلة فقط (الحي ونوع العقار وغرف النوم نفسها، 5 إعلانات على الأقل). |
min_listingsالنوع: integer · الاستعلام | المعلنون الذين لديهم هذا العدد من الإعلانات المطابقة على الأقل فقط. |
sortالنوع: string · الاستعلام |
إحدى القيم: |
limitالنوع: integer · الاستعلام | |
cursorالنوع: string · الاستعلام |
الاستجابة
الحقل data كائن بهذه الحقول.
| الاسم | الوصف |
|---|---|
price_basisمطلوبالنوع: string | معنى حقول السعر إحدى القيم: |
price_sourceمطلوبالنوع: string | مصدر السعر: إحدى القيم: |
totalsمطلوبالنوع: object | على مستوى كل الصفحات: المعلنون الذين لديهم |
advertisersمطلوبالنوع: object[] |
نقاط نهاية ذات صلة
- جلب الإعلانات المقارنة
GET /listings/{id}/comparables - موقع سعر الإعلان في السوق
GET /listings/{id}/market-position - نطاق أسعار العرض القريبة لإعلان
GET /listings/{id}/price-band - إعلانات أقل من أسعار السوق
GET /market/below-market - إعلانات أقل من أسعار السوق (المسار القديم)
GET /market/deals - العائد الإيجاري الإجمالي
GET /market/rental-yield - اتجاهات الأسعار
GET /market/trends - مقارنة الأحياء
GET /market/neighborhoods/compare - تحقق من السعر المطلوب لأي منزل
GET /valuations/asking-range