تخطّي إلى المحتوى

للأعمال

وثائق واجهة البيانات البرمجية

كل ما تحتاجه لاستخدام واجهة بيانات GCC Car Deals: المصادقة، ونقاط النهاية مع معلماتها واستجاباتها، والأخطاء والحدود.

مجانًا لمدة 14 يومًا: بحد 50 طلبًا شهريًا، في سوق واحد. يصلح أي بريد إلكتروني وتلزم بطاقة دفع، وإذا ألغيت قبل انتهاء التجربة فلن تدفع شيئًا.

البدء السريع

ابدأ تجربة مجانية أو اشترك لتحصل على مفتاح، واحفظه في متغير بيئة، وأرسله رمزَ وصول من نوع Bearer. يستعلم هذا الطلب عن القيمة السوقية لسيارة تويوتا كامري اليوم.

العنوان الأساسي: https://gcccardeals.com/api/b2b/v1

curl -s "https://gcccardeals.com/api/b2b/v1/valuation?make=Toyota&model=Camry&year=2019&km=90000" \
  -H "Authorization: Bearer $GCC_API_KEY"

المصادقة

أرسل مفتاحك في ترويسة Authorization رمزَ وصول من نوع Bearer، أو في ترويسة X-API-Key. ولا تضعه أبدًا في عنوان URL، فالعناوين تُسجَّل. المفاتيح سرّية وتُصدر لكل سوق، فلا يمكن استخدام مفتاح سوق للاستعلام عن سوق آخر. تتضمن باقتا Starter وDataset مفتاحًا للسوق الذي تختاره، وتتضمن باقتا Pro وBusiness مفتاحًا لكل سوق. وتنشئ مفاتيحك من لوحة واجهة البيانات، ويظهر المفتاح كاملًا مرة واحدة فقط.

الأمان

تُقدَّم الواجهة عبر HTTPS. لا نحتفظ بمفتاحك نفسه، بل ببصمة رقمية منه (hash) لا يمكن استرجاع المفتاح منها. لا يحتاج التقييم إلى أي بيانات شخصية: الماركة والطراز وسنة الصنع والفئة والمسافة المقطوعة والتاريخ فقط. تتولى Stripe مدفوعات البطاقات، فلا يصل رقم بطاقتك إلينا. أرسل لنا استبيان تقييم الموردين أو استبيان الأمن لدى شركتك وسنجيب عنه.

جرّبها بمفتاحك

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

ليس لديك مفتاح بعد؟ مفتاح التجربة المجانية يعمل هنا أيضًا:احصل على مفتاح

الصق المفتاح كاملًا كما حفظته حين ظهر لك، فهو لا يظهر كاملًا إلا مرة واحدة. وإذا لم يعد لديك، فاستخدم «تجديد المفتاح» في لوحة واجهة البيانات لتحصل على مفتاح جديد.

مثل Toyota.

مثل Camry أو Land Cruiser.

من 1950 إلى السنة القادمة.

اختياري. قراءة عداد المسافة بالكيلومتر.

اختياري. كما هي مكتوبة على السيارة، مثل GXR.

يقيّم هذا النموذج السيارة على أنها مستعملة. ولتقييم سيارة جديدة أرسل condition=new من برنامجك. تُحتسب كل محاولة طلبًا واحدًا من حصتك في هذا السوق، حتى حين لا تُعاد قيمة، وكذلك حين تأتي الإجابة بأن الماركة أو الطراز غير مدرج بسبب خطأ في الكتابة. أما ما يطلب منك هذا النموذج تصحيحه قبل الإرسال فلا يُحتسب، وتبيّن الإجابة متى لم تُحتسب المحاولة.

التقييم

متاح في جميع الباقات

GET https://gcccardeals.com/api/b2b/v1/valuation

القيمة السوقية لسيارة واحدة في تاريخ معين: تقديرنا المبني على إعلانات مماثلة يُعدَّل كل منها بحسب سنة صنع السيارة ومسافتها المقطوعة، مع الخطأ المعتاد لتقديرات كهذه ونطاقها، والإعلانات التي بُنيت عليها.

المعلمات

التقييم: المعلمات
المعلمةإلزاميةالوصف
makeنعمالماركة كما تكتبها، مثل Toyota. نتعرّف على الأسماء وصيغ كتابتها الشائعة.
modelنعمالطراز، مثل Camry.
yearنعمسنة الصنع، من 1950 إلى السنة القادمة.
trimلافئة التجهيز كما هي مكتوبة على السيارة، مثل GXR. تُضيّق نطاق المقارنة، ولا تغيّر السيارة التي يجري تقييمها.
kmلاقراءة عداد المسافة بالكيلومتر. عند إدخالها تتبع القيمة المسافة المقطوعة للسيارة.
as_ofلاتاريخ التقييم بصيغة YYYY-MM-DD وبالتوقيت العالمي. الافتراضي هو اليوم. ويجب أن يقع بين بداية سجل أسعار السوق واليوم، وضمن نطاق سجل باقتك.
conditionلاused (الافتراضي) أو new.
window_daysلاعدد الأيام التي يُرجَع إليها لجمع السيارات المماثلة، وتُحسب من تاريخ التقييم (ومن اليوم لجدول الأسعار)، من 30 إلى 180. الافتراضي 90.
comparablesلاعدد الإعلانات المماثلة التي تعيدها الواجهة بوصفها أدلة، من 0 إلى 25. الافتراضي 10.
marketلااختيارية. يجب أن يطابق السوق سوق مفتاحك، وأي اختلاف يُعدّ خطأ.

لا يُطلب إلا make وmodel وyear، وكل ما عداها من المعلمات اختياري. وأرسل أيضًا km وtrim إن كانتا معروفتين لديك: فعندها تراعي القيمة المسافة المقطوعة للسيارة متى ذكرت الإعلانات المماثلة مسافاتها، وتُضيّق فئة التجهيز نطاق المقارنة.

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

curl -s "https://gcccardeals.com/api/b2b/v1/valuation?make=Toyota&model=Camry&year=2019&km=90000" \
  -H "Authorization: Bearer $GCC_API_KEY"

مثال على الاستجابة

قيم توضيحية لشرح الصيغة. ليست أسعارًا حالية، والإعلان مثال.

{
  "version": 1,
  "method": "adjusted-comparables-v2",
  "market": "ae",
  "currency": "AED",
  "as_of": "2026-09-15",
  "window_days": 90,
  "history_since": "2026-06-12",
  "subject": {
    "make": "toyota",
    "model": "camry",
    "model_year": 2019,
    "trim": null,
    "trim_label": null,
    "km": 90000,
    "condition": "used"
  },
  "valuation": {
    "value": 52000,
    "low": 47500,
    "high": 56000,
    "confidence": "high",
    "indicative": false,
    "typical_error_pct": 8.1,
    "range_low": 43900,
    "range_high": 61000,
    "basis": "model_year",
    "premium_trim_group": null,
    "mileage_matched": true
  },
  "counts": {
    "candidates_total": 31,
    "truncated": false,
    "candidates": 31,
    "distinct_cars": 27,
    "outliers_dropped": 1,
    "pool": 26,
    "used": 26,
    "same_trim": 0,
    "same_year": 22
  },
  "year_counts": {
    "2018": 4,
    "2019": 22
  },
  "pool": {
    "median_price": 53000,
    "p25": 48000,
    "p75": 57000,
    "median_km": 96000,
    "sources": 4
  },
  "comparables": [
    {
      "source": "Example marketplace",
      "url": "https://www.example.com/listing/12345",
      "model_year": 2019,
      "trim": null,
      "km": 88000,
      "asking_price": 51500,
      "price_date": "2026-09-10",
      "adjusted_price": 51400,
      "first_seen": "2026-08-30",
      "last_seen": "2026-09-16",
      "still_listed": true,
      "listed_on_as_of": true,
      "city": "dubai"
    }
  ],
  "reason": null,
  "quota": {
    "monthly": 3000,
    "used_month": 12,
    "daily": 3000,
    "used_today": 3
  },
  "notes": [
    "Prices are asking prices from the listings we observe, not transaction prices."
  ]
}

عن الإعلانات المماثلة

قائمة comparables أدلة، لا المقارنة كلها. فهي تضم من الإعلانات حتى العدد الذي تطلبه بالمعلمة comparables (من 0 إلى 25، و10 إذا لم ترسلها)، مختارةً من السيارات التي تستند إليها القيمة، الأقرب شبهًا أولًا، ويبيّن counts.pool عدد تلك السيارات كلها. وقد تكون الإعلانات لسنوات صنع قريبة: إذ يبيّن adjusted_price سعر كل إعلان بعد تعديله بحسب سنة صنع سيارتك ومسافتها المقطوعة. وقد لا يكون كثير منها معروضًا بعد الآن، لأن المقارنة تعود إلى الوراء عدد الأيام المحدد في window_days، ولذلك تكون قيمة still_listed في الغالب false. وهذا أمر طبيعي: فالإعلان الذي أُزيل يظل محسوبًا بالسعر الذي كان مطلوبًا فيه.

مثال على استجابة دون قيمة

قيم توضيحية. حين نُدرج الماركة والطراز ولا توجد سيارة مماثلة قريبة بما يكفي من سنة الصنع ضمن النافذة الزمنية، تبقى الإجابة ناجحة لا خطأ: تكون value والأرقام المرتبطة بها null، وتكون comparables فارغة، ويبيّن reason ما ينقص. وتُحتسب هذه الإجابة طلبًا.

{
  "version": 1,
  "method": "adjusted-comparables-v2",
  "market": "ae",
  "currency": "AED",
  "as_of": "2026-09-15",
  "window_days": 90,
  "history_since": "2026-06-12",
  "subject": {
    "make": "toyota",
    "model": "camry",
    "model_year": 1988,
    "trim": null,
    "trim_label": null,
    "km": 240000,
    "condition": "used"
  },
  "valuation": {
    "value": null,
    "low": null,
    "high": null,
    "confidence": null,
    "indicative": false,
    "typical_error_pct": null,
    "range_low": null,
    "range_high": null,
    "basis": null,
    "premium_trim_group": null,
    "mileage_matched": false
  },
  "counts": {
    "candidates_total": 0,
    "truncated": false,
    "candidates": 0,
    "distinct_cars": 0,
    "outliers_dropped": 0,
    "pool": 0,
    "used": 0,
    "same_trim": 0,
    "same_year": 0
  },
  "year_counts": {},
  "pool": {
    "median_price": null,
    "p25": null,
    "p75": null,
    "median_km": null,
    "sources": 0
  },
  "comparables": [],
  "reason": "no comparable car close enough to model year 1988 in the window",
  "quota": {
    "monthly": 3000,
    "used_month": 13,
    "daily": 3000,
    "used_today": 4
  },
  "notes": [
    "Prices are asking prices from the listings we observe, not transaction prices."
  ]
}

حقول الاستجابة

version
إصدار صيغة الاستجابة. تُضاف الحقول داخل الإصدار الواحد ولا تُحذف ولا يُغيَّر اسمها.
method
اسم الطريقة التي أنتجت الإجابة وإصدارها.
market
السوق الذي تخصه الإجابة: qa أو ae أو sa.
currency
عملة جميع الأسعار في الإجابة.
as_of
التاريخ الذي تخصه الإجابة، بالتوقيت العالمي.
window_days
عدد الأيام السابقة للتاريخ as_of التي أُخذت منها السيارات المماثلة.
history_since
أول تاريخ يتوفر منه سجل أسعار لهذا السوق.
subject
السيارة كما فهمناها: make وmodel وmodel_year وtrim وtrim_label وkm وcondition.
valuation.value
القيمة السوقية: تقديرنا للسعر المطلوب للسيارة في السوق بتاريخ as_of، مبنيًا على إعلانات مماثلة يُعدَّل كل منها بحسب سنة صنع السيارة ومسافتها المقطوعة. تكون null حين لا نجد أي سيارة مماثلة، ويبيّن reason السبب.
valuation.low
الحد الأدنى للنطاق الذي يقع فيه النصف الأوسط من الأسعار المعدَّلة للسيارات المماثلة.
valuation.high
الحد الأعلى لذلك النطاق.
valuation.confidence
مقدار الأدلة التي تستند إليها القيمة: high أو medium أو low.
valuation.indicative
تكون true حين تكون القيمة إرشادية فقط: الأدلة التي تستند إليها قليلة جدًا، أو المسافة التي أرسلتها بعيدة عن مسافات السيارات المماثلة، ويكون مستوى الثقة منخفضًا عندها. وإلا فهي false.
valuation.typical_error_pct
مدى قرب قيم كهذه من الأسعار المطلوبة لكل سيارة على حدة، مقيسًا على بياناتنا: نصف السيارات المشابهة يُطلب لها سعر يقع ضمن هذه النسبة المئوية من القيمة. تكون null إذا لم يُقَس بعد.
valuation.range_low
الحد الأدنى للنطاق الذي يقع فيه السعر المطلوب لمعظم السيارات المشابهة، مقيسًا على بياناتنا. تكون null عندما يكون typical_error_pct نفسه null.
valuation.range_high
الحد الأعلى لذلك النطاق.
valuation.basis
ما تستند إليه القيمة بالدرجة الأولى: trim (سيارات تذكر فئة تجهيز سيارتك) أو trim_group (سيارات من مجموعة فئتك المؤثرة في السعر) أو model_year (سيارات من سنة صنع سيارتك) أو adjusted_years (عدد قليل جدًا من سيارات سنة صنع سيارتك، فاستُعين بسيارات من سنوات صنع قريبة بعد تعديل أسعارها).
valuation.premium_trim_group
مجموعة الفئات المؤثرة في السعر التي قُيّمت السيارة على أساسها، حين تنتمي فئتها إلى إحدى هذه المجموعات.
valuation.mileage_matched
تكون true حين تتبع القيمة المسافة المقطوعة لسيارتك: أدخلتَ km وذكرت الإعلانات المماثلة مسافاتها.
counts.candidates_total
جميع الإعلانات المطابقة التي رصدناها ضمن النافذة الزمنية.
counts.truncated
تكون true حين يزيد candidates_total على عدد الإعلانات المقروءة.
counts.candidates
الإعلانات المقروءة لهذا التقييم.
counts.distinct_cars
عدد السيارات التي تمثلها تلك الإعلانات.
counts.outliers_dropped
سيارات استُبعدت لأن سعرها غير معتاد في هذه المقارنة.
counts.pool
السيارات المتبقية في المقارنة بعد ذلك.
counts.used
السيارات التي أُخذت منها القيمة.
counts.same_trim
عدد السيارات من سنة صنع سيارتك التي تشترك في الفئة التي أدخلتها.
counts.same_year
عدد السيارات التي أُخذت منها القيمة وهي من سنة صنع سيارتك.
year_counts
عدد السيارات المماثلة لكل سنة صنع، ويبيّن سنوات الصنع التي تستند إليها القيمة.
pool.median_price
وسيط الأسعار المطلوبة في مجموعة المقارنة كلها.
pool.p25
الحد الأدنى للنصف الأوسط من الأسعار المطلوبة في تلك المجموعة.
pool.p75
الحد الأعلى للنصف الأوسط من الأسعار المطلوبة في تلك المجموعة.
pool.median_km
وسيط المسافة المقطوعة للمجموعة بالكيلومتر.
pool.sources
عدد المنصات التي جاءت منها المجموعة.
comparables[].source
المنصة التي وُجد فيها الإعلان.
comparables[].url
رابط الإعلان الأصلي، أو null في الحالات القليلة التي نحجب فيها الرابط حفاظًا على الخصوصية.
comparables[].model_year
سنة صنع السيارة في الإعلان.
comparables[].trim
فئة تجهيز السيارة في الإعلان، حين يذكرها.
comparables[].km
قراءة عداد المسافة في الإعلان بالكيلومتر، حين يذكرها.
comparables[].asking_price
السعر المطلوب في الإعلان بتاريخ price_date بعملة السوق.
comparables[].price_date
تاريخ السعر المطلوب الذي استُخدم في التقييم.
comparables[].adjusted_price
السعر المطلوب في الإعلان بعد تعديله بما يناسب سنة صنع سيارتك ومسافتها المقطوعة. وهو ما يسهم به هذا الإعلان في القيمة.
comparables[].first_seen
تاريخ أول رصد لنا للإعلان.
comparables[].last_seen
تاريخ آخر رصد لنا للإعلان.
comparables[].still_listed
ما إذا كان الإعلان لا يزال معروضًا اليوم.
comparables[].listed_on_as_of
ما إذا كان الإعلان معروضًا في تاريخ as_of نفسه.
comparables[].city
المدينة الواردة في الإعلان، حين يذكرها.
reason
حين يتعذّر إعطاء قيمة، سبب ذلك بلغة واضحة. وإلا فهو null.
quota
حصتك وما استهلكته منها: monthly وused_month وdaily وused_today.
notes
ملاحظات بلغة واضحة عن طريقة قراءة الأرقام.

أسعار السوق

متاح في جميع الباقات

GET https://gcccardeals.com/api/b2b/v1/market-prices

السعر المطلوب المعتاد ونطاقه لماركة وطراز واحد، بحسب سنة الصنع وعائلة الفئة وشريحة المسافة المقطوعة، إضافةً إلى تقديرنا للسعر في كل مجموعة، بما فيها المجموعات الأصغر من أن تُسعَّر.

المعلمات

أسعار السوق: المعلمات
المعلمةإلزاميةالوصف
makeنعمالماركة كما تكتبها، مثل Toyota. نتعرّف على الأسماء وصيغ كتابتها الشائعة.
modelنعمالطراز، مثل Camry.
conditionلاused (الافتراضي) أو new.
window_daysلاعدد الأيام التي يُرجَع إليها لجمع السيارات المماثلة، وتُحسب من تاريخ التقييم (ومن اليوم لجدول الأسعار)، من 30 إلى 180. الافتراضي 90.
marketلااختيارية. يجب أن يطابق السوق سوق مفتاحك، وأي اختلاف يُعدّ خطأ.

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

curl -s "https://gcccardeals.com/api/b2b/v1/market-prices?make=Toyota&model=Camry" \
  -H "Authorization: Bearer $GCC_API_KEY"

مثال على الاستجابة

قيم توضيحية لشرح الصيغة. ليست أسعارًا حالية، والإعلان مثال.

{
  "version": 1,
  "method": "market-prices-v1",
  "market": "ae",
  "currency": "AED",
  "as_of": "2026-09-29",
  "window_days": 90,
  "history_since": "2026-06-12",
  "make": "toyota",
  "model": "camry",
  "condition": "used",
  "cells": [
    {
      "model_year": 2019,
      "trim_family": "base",
      "mileage_band": "100-150k",
      "cars": 12,
      "median_price": 52000,
      "p25_price": 48000,
      "p75_price": 56000,
      "median_km": 128000,
      "estimated_price": 52300,
      "estimate_range_low": 44100,
      "estimate_range_high": 61400,
      "estimate_error_pct": 8.1,
      "estimate_confidence": "high"
    }
  ],
  "quota": {
    "monthly": 3000,
    "used_month": 12,
    "daily": 3000,
    "used_today": 3
  },
  "notes": [
    "Prices are asking prices from the listings we observe, not transaction prices."
  ]
}

حقول الاستجابة

version
إصدار صيغة الاستجابة. تُضاف الحقول داخل الإصدار الواحد ولا تُحذف ولا يُغيَّر اسمها.
method
اسم الطريقة التي أنتجت الإجابة وإصدارها.
market
السوق الذي تخصه الإجابة: qa أو ae أو sa.
currency
عملة جميع الأسعار في الإجابة.
as_of
التاريخ الذي تخصه الإجابة، بالتوقيت العالمي.
window_days
عدد الأيام السابقة للتاريخ as_of التي أُخذت منها السيارات المماثلة.
history_since
أول تاريخ يتوفر منه سجل أسعار لهذا السوق.
make
الماركة كما ندرجها.
model
الطراز كما ندرجه.
condition
used أو new.
cells
جدول الأسعار لهذه الماركة والطراز: عنصر لكل سنة صنع وعائلة فئة وشريحة مسافة مقطوعة.
cells[].model_year
سنة الصنع.
cells[].trim_family
عائلة الفئة: اسم الفئة المؤثرة في السعر، أو base للفئات الأساسية.
cells[].mileage_band
شريحة المسافة المقطوعة التي تقع فيها السيارات.
cells[].cars
عدد السيارات في المجموعة.
cells[].median_price
السعر المطلوب المعتاد للمجموعة. يكون null إذا كانت المجموعة أصغر من أن تُسعَّر.
cells[].p25_price
الحد الأدنى للنصف الأوسط من الأسعار المطلوبة، أو null.
cells[].p75_price
الحد الأعلى للنصف الأوسط من الأسعار المطلوبة، أو null.
cells[].median_km
وسيط المسافة المقطوعة للمجموعة بالكيلومتر.
cells[].estimated_price
تقديرنا للسعر المطلوب للمجموعة. وخلافًا للسعر المعتاد، يُعطى كذلك للمجموعة الأصغر من أن تُسعَّر. يكون null حين لا يتوفر لدينا تقدير لها.
cells[].estimate_range_low
الحد الأدنى للنطاق الذي يقع فيه السعر المطلوب لمعظم السيارات المشابهة، مقيسًا على بياناتنا. يكون null إذا لم يُقَس بعد.
cells[].estimate_range_high
الحد الأعلى لذلك النطاق.
cells[].estimate_error_pct
مدى قرب تقديرات كهذه من الأسعار المطلوبة لكل سيارة على حدة، مقيسًا على بياناتنا: نصف السيارات المشابهة يُطلب لها سعر يقع ضمن هذه النسبة المئوية من التقدير. يكون null إذا لم يُقَس بعد.
cells[].estimate_confidence
مقدار الأدلة التي يستند إليها التقدير: high أو medium أو low أو indicative (أدلة قليلة جدًا).
quota
حصتك وما استهلكته منها: monthly وused_month وdaily وused_today.
notes
ملاحظات بلغة واضحة عن طريقة قراءة الأرقام.

جدول السوق الكامل (CSV)

متاح في باقات Pro وBusiness وDataset

GET https://gcccardeals.com/api/b2b/v1/market-prices.csv

جدول أسعار السوق كاملًا، مع تقديرنا لكل مجموعة، في ملف CSV واحد، يُحدَّث يوميًا. ويُحتسب التنزيل طلبًا واحدًا.

المعلمات

جدول السوق الكامل (CSV): المعلمات
المعلمةإلزاميةالوصف
marketلااختيارية. يجب أن يطابق السوق سوق مفتاحك، وأي اختلاف يُعدّ خطأ.

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

curl -s "https://gcccardeals.com/api/b2b/v1/market-prices.csv" \
  -H "Authorization: Bearer $GCC_API_KEY" \
  -o market-prices.csv

يُرسَل الملف تدريجيًا. وإذا انقطع الاتصال قبل اكتماله فاحذفه ولا تعتمد عليه: تبيّن لك ترويسة X-Total-Rows عدد الصفوف المتوقع. الملف بترميز UTF-8 مع علامة ترتيب البايت (BOM) ليفتحه Excel بشكل صحيح، وتنتهي أسطره بـ CRLF؛ فاقرأه بترميز UTF-8 مع BOM (أي utf-8-sig في Python).

الأعمدة

make
الماركة كما ندرجها.
model
الطراز كما ندرجه.
model_year
سنة الصنع.
trim_family
عائلة الفئة: اسم الفئة المؤثرة في السعر، أو base للفئات الأساسية.
condition
used أو new.
mileage_band
شريحة المسافة المقطوعة التي تقع فيها السيارات.
cars
عدد السيارات في المجموعة.
median_price
السعر المطلوب المعتاد للمجموعة. يكون null إذا كانت المجموعة أصغر من أن تُسعَّر.
p25_price
الحد الأدنى للنصف الأوسط من الأسعار المطلوبة، أو null.
p75_price
الحد الأعلى للنصف الأوسط من الأسعار المطلوبة، أو null.
median_km
وسيط المسافة المقطوعة للمجموعة بالكيلومتر.
currency
عملة جميع الأسعار في الإجابة.
computed_on
تاريخ حساب الجدول أو الملف بالتوقيت العالمي.
estimated_price
تقديرنا للسعر المطلوب للمجموعة. وخلافًا للسعر المعتاد، يُعطى كذلك للمجموعة الأصغر من أن تُسعَّر. يكون null حين لا يتوفر لدينا تقدير لها.
estimate_range_low
الحد الأدنى للنطاق الذي يقع فيه السعر المطلوب لمعظم السيارات المشابهة، مقيسًا على بياناتنا. يكون null إذا لم يُقَس بعد.
estimate_range_high
الحد الأعلى لذلك النطاق.
estimate_error_pct
مدى قرب تقديرات كهذه من الأسعار المطلوبة لكل سيارة على حدة، مقيسًا على بياناتنا: نصف السيارات المشابهة يُطلب لها سعر يقع ضمن هذه النسبة المئوية من التقدير. يكون null إذا لم يُقَس بعد.
estimate_confidence
مقدار الأدلة التي يستند إليها التقدير: high أو medium أو low أو indicative (أدلة قليلة جدًا).

ملف على مستوى الإعلانات (CSV)

باقة Dataset، وباقة Business بالدفع السنوي

GET https://gcccardeals.com/api/b2b/v1/listings.csv

صف واحد لكل سيارة مسعّرة من السيارات التي تُبنى عليها جداول أسعار السوق، بالوقائع المستمدة من إعلانها العام، في ملف CSV واحد يُعاد بناؤه يوميًا. يأتي مع باقة Dataset ومع باقة Business بالدفع السنوي، ويُحتسب التنزيل طلبًا واحدًا.

المعلمات

ملف على مستوى الإعلانات (CSV): المعلمات
المعلمةإلزاميةالوصف
marketلااختيارية. يجب أن يطابق السوق سوق مفتاحك، وأي اختلاف يُعدّ خطأ.

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

curl -s "https://gcccardeals.com/api/b2b/v1/listings.csv" \
  -H "Authorization: Bearer $GCC_API_KEY" \
  -o listings.csv

مثال على الاستجابة

قيم توضيحية لشرح الصيغة. ليست أسعارًا حالية، والإعلان مثال.

make,model,model_year,trim,condition,mileage_km,asking_price,price_date,first_price,price_changes,first_seen,last_seen,status,city,source,url,currency,computed_on
toyota,camry,2019,GXR,used,88000,51500,2026-09-10,53000,1,2026-08-30,2026-09-16,listed,dubai,Example marketplace,https://www.example.com/listing/12345,AED,2026-09-29

يحمل الملف المنزَّل الاسم gcc-car-deals-<market>-listings-<date>.csv، أي رمز السوق وتاريخ بناء الملف. ويُرسَل الملف تدريجيًا: فإذا انقطع الاتصال قبل اكتماله فاحذفه ولا تعتمد عليه، إذ تبيّن لك ترويسة X-Total-Rows عدد الصفوف المتوقع. الملف بترميز UTF-8 مع علامة ترتيب البايت (BOM) ليفتحه Excel بشكل صحيح، وتنتهي أسطره بـ CRLF؛ فاقرأه بترميز UTF-8 مع BOM (أي utf-8-sig في Python). أما المفتاح الذي لا تشمل باقته الملف فيتلقى الخطأ plan_limit.

الأعمدة

make
الماركة كما ندرجها.
model
الطراز كما ندرجه.
model_year
سنة الصنع.
trim
فئة التجهيز التي يذكرها الإعلان، أو فارغ حين لا يذكر فئة.
condition
used أو new.
mileage_km
قراءة عداد المسافة بالكيلومتر، أو فارغ حين لا يذكرها الإعلان.
asking_price
آخر سعر مطلوب رصدناه للسيارة، بعملة السوق.
price_date
تاريخ ذلك السعر المطلوب الأخير.
first_price
أول سعر مطلوب رأيناه للسيارة.
price_changes
عدد المرات التي تغيّر فيها السعر المطلوب أثناء متابعتنا للسيارة.
first_seen
تاريخ أول رصد لنا للإعلان.
last_seen
تاريخ آخر رصد لنا للإعلان.
status
listed إذا كان الإعلان لا يزال قائمًا، وremoved إذا لم يعد قائمًا.
city
المدينة الواردة في الإعلان، باسم بحروف لاتينية صغيرة، أو فارغ حين لا يذكرها.
source
المنصة التي وُجد فيها الإعلان.
url
رابط الإعلان الأصلي، أو فارغ في الحالات القليلة التي نحجب فيها الرابط حفاظًا على الخصوصية.
currency
عملة جميع الأسعار في الإجابة.
computed_on
تاريخ حساب الجدول أو الملف بالتوقيت العالمي.

مؤشر الأسعار

متاح في جميع الباقات

GET https://gcccardeals.com/api/b2b/v1/price-index

مؤشر GCC Car Deals لأسعار السيارات المستعملة: مقدار تغيّر السعر المطلوب لنوع السيارة المستعملة نفسه من شهر إلى آخر في سوقك، مع النطاق الذي يرجَّح أن يقع فيه كل تغيّر. يُنشر المؤشر العام للسوق كله مجانًا، وتمنحك هذه الواجهة كل التفصيلات بحسب عمر السيارة وأصل الماركة والماركة نفسها منذ أول شهر في المؤشر. وهي متاحة في جميع الباقات، ويُحتسب كل طلب طلبًا واحدًا.

المعلمات

مؤشر الأسعار: المعلمات
المعلمةإلزاميةالوصف
segmentلااختيارية. التفصيل المطلوب إعادته من القيم المدرجة هنا؛ اتركها لتحصل على كل التفصيلات. تُكتب الماركة على صورة make: متبوعة باسمها بحروف صغيرة، مثل make:toyota. وفي الرابط، اكتب علامة الزائد الخاصة بأكبر فئة عمرية بصيغتها المرمّزة (percent-encoded).allage:0-3age:4-7age:8+origin:chineseorigin:japaneseorigin:germanorigin:koreanorigin:americanmake:<make>
marketلااختيارية. يجب أن يطابق السوق سوق مفتاحك، وأي اختلاف يُعدّ خطأ.

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

curl -s "https://gcccardeals.com/api/b2b/v1/price-index?segment=origin:japanese" \
  -H "Authorization: Bearer $GCC_API_KEY"

مثال على الاستجابة

قيم توضيحية لشرح الصيغة. ليست أسعارًا حالية، والإعلان مثال.

{
  "version": 1,
  "index": "GCC Car Deals Used-Car Price Index",
  "market": "ae",
  "method": "new-listings-v2",
  "base_month": "2026-07",
  "rows": [
    {
      "segment": "origin:japanese",
      "month": "2026-07",
      "level": 100,
      "change_pct": null,
      "change_low_pct": null,
      "change_high_pct": null,
      "same_year_change_pct": null,
      "cars": null,
      "prev_cars": null,
      "cohorts": null
    },
    {
      "segment": "origin:japanese",
      "month": "2026-08",
      "level": 100.3,
      "change_pct": 0.3,
      "change_low_pct": 0,
      "change_high_pct": 0.6,
      "same_year_change_pct": -0.4,
      "cars": 4390,
      "prev_cars": 4180,
      "cohorts": 902
    },
    {
      "segment": "origin:japanese",
      "month": "2026-09",
      "level": 99.8,
      "change_pct": -0.5,
      "change_low_pct": -0.8,
      "change_high_pct": -0.2,
      "same_year_change_pct": -1.2,
      "cars": 4460,
      "prev_cars": 4325,
      "cohorts": 915
    }
  ],
  "quota": {
    "monthly": 3000,
    "used_month": 12,
    "daily": 3000,
    "used_today": 3
  },
  "notes": [
    "The index follows the asking prices of used cars newly listed each month, comparing like with like. These are asking prices, not transaction prices. The base month is 100."
  ]
}

حقول الاستجابة

version
إصدار صيغة الاستجابة. تُضاف الحقول داخل الإصدار الواحد ولا تُحذف ولا يُغيَّر اسمها.
index
اسم المؤشر.
market
السوق الذي تخصه الإجابة: qa أو ae أو sa.
method
اسم الطريقة التي أنتجت الإجابة وإصدارها.
base_month
أول شهر في المؤشر، بصيغة YYYY-MM. يُضبط مستواه عند مئة، ويُقاس كل مستوى لاحق انطلاقًا منه.
rows
السلسلة: صف لكل تفصيل وشهر، يبدأ بالسوق كله ثم التفصيلات بترتيب أبجدي، ولكل منها شهورها بالترتيب الزمني.
rows[].segment
التفصيل الذي ينتمي إليه الصف: all للسوق كله، أو الفئة العمرية أو أصل الماركة أو الماركة التي يغطيها.
rows[].month
الشهر الذي يخصه الصف، بصيغة YYYY-MM.
rows[].level
مستوى المؤشر: مئة في شهر الأساس، ثم المستوى السابق بعد تطبيق تغيّر كل شهر. وحين يكون شهر أصغر من أن يُنشر، تُمرَّر السلسلة عبره بالمقارنة المباشرة مع آخر شهر له مستوى. ويكون null حيث يتعذّر ذلك.
rows[].change_pct
مقدار تغيّر السعر المطلوب للسيارات المستعملة المعروضة حديثًا هذا الشهر عن الشهر السابق، بالنسبة المئوية، بمقارنة المثيل بالمثيل ومع مراعاة المسافة المقطوعة وكون السيارات أكبر بشهر. يكون null في شهر الأساس، وحين يكون الشهر أصغر من أن يُنشر.
rows[].change_low_pct
الحد الأدنى للنطاق الذي يرجَّح أن يقع فيه التغيّر. يكون null حين تكون قيمة change_pct هي null.
rows[].change_high_pct
الحد الأعلى لهذا النطاق.
rows[].same_year_change_pct
المقارنة نفسها دون مراعاة كون السيارات أكبر بشهر، أي كيف تغيّر السعر المطلوب لسنوات الصنع نفسها. يكون null حين تكون قيمة change_pct هي null.
rows[].cars
السيارات المعروضة حديثًا التي جرت مقارنتها هذا الشهر. يكون null في شهر الأساس، وحيث تعذّرت المقارنة.
rows[].prev_cars
السيارات المعروضة حديثًا التي جرت مقارنتها من الشهر السابق. يكون null في شهر الأساس، وحيث تعذّرت المقارنة.
rows[].cohorts
المجموعات المتماثلة التي جرت مقارنتها: سيارات من الماركة والطراز وسنة الصنع وعائلة الفئة نفسها في السوق الإلكتروني نفسه. يكون null في شهر الأساس، وحيث تعذّرت المقارنة.
quota
حصتك وما استهلكته منها: monthly وused_month وdaily وused_today.
notes
ملاحظات بلغة واضحة عن طريقة قراءة الأرقام.

الأخطاء

عند رفض الطلب تعيد الواجهة رمز حالة HTTP المناسب ومتنًا بصيغة JSON يتضمن رمز خطأ يمكنك التصرف بناءً عليه ورسالة واضحة يقرؤها الإنسان.

الأخطاء
الحالةالرمزالمعنى
400bad_requestإحدى المعلمات مفقودة أو غير صالحة، وتبيّن الرسالة أيّها. ولا يُخصم الطلب من حصتك.
401unauthorizedالمفتاح غير موجود أو غير صحيح الصيغة أو منتهي الصلاحية أو ملغى.
403plan_limitباقتك لا تشمل هذا الطلب، مثل الجدول الكامل في باقة Starter، أو الملف على مستوى الإعلانات في باقة لا تتضمنه، أو تاريخ أبعد من نطاق سجل باقتك. تبيّن الرسالة ما ينقص.
422unknown_vehicleلا نتعرّف على الماركة أو الطراز، ويسرد الحقل error.known_models بعض الطرازات التي نعرفها. أما الطراز المدرج لدينا الذي لا تتوفر له سيارات مماثلة ضمن النافذة الزمنية فلا يُعدّ خطأ، بل تأتي الإجابة دون قيمة مع بيان السبب.
429rate_limitedطلبات كثيرة في وقت قصير. انتظر عدد الثواني الوارد في الترويسة Retry-After.
429busyما زال هناك طلب آخر من حسابك قيد التنفيذ. أرسل طلبًا واحدًا في كل مرة.
429quota_exceededاستُنفدت حصتك الشهرية لهذا السوق، أو استُنفد الحد اليومي للمفتاح. تتجدد الحصة الشهرية مع بداية الشهر الميلادي التالي (بالتوقيت العالمي)، ويتجدد الحد اليومي عند منتصف الليل بالتوقيت العالمي.
503unavailableتعذّرت قراءة البيانات الآن. أعد المحاولة بعد عدد الثواني الوارد في الترويسة Retry-After. وليست هذه إجابة عن السيارة.

مثال على استجابة خطأ

لكل رفض هذا الجسم: رقم إصدار وحقل error فيه رمز يمكنك التصرف بناءً عليه ورسالة يقرؤها الإنسان. ويسرد خطأ unknown_vehicle أيضًا بعض الطرازات التي نعرفها في known_models.

{
  "version": 1,
  "error": {
    "code": "plan_limit",
    "message": "as_of is older than your plan's history window (90 days)"
  }
}
{
  "version": 1,
  "error": {
    "code": "unknown_vehicle",
    "message": "no model \"camri\" for toyota in this market",
    "known_models": [
      "camry",
      "corolla",
      "land cruiser",
      "hilux",
      "yaris"
    ]
  }
}

الحدود وترويسات الحصة

لكل باقة حصة شهرية من الطلبات في كل سوق تغطيه، تُحتسب من بداية الشهر الميلادي (بالتوقيت العالمي)، وينطبق ذلك على الباقات السنوية أيضًا. ويُحتسب كل تقييم أو استعلام عن أسعار السوق أو طلب مؤشر أسعار أو تنزيل للجدول الكامل أو للملف على مستوى الإعلانات طلبًا واحدًا. والحصة لحسابك في ذلك السوق: تُحتسب عليها جميع المفاتيح التي تملكها فيه معًا، فلا يعيدها مفتاح جديد إلى الصفر. وقد يحمل المفتاح أيضًا حدًّا يوميًا يتجدد عند منتصف الليل بالتوقيت العالمي. ويمكن لكل عنوان IP للعميل إرسال ما يصل إلى 120 طلبًا في الدقيقة، ولا يمكن أن يكون قيد التنفيذ سوى طلب واحد لكل حساب في السوق الواحد في الوقت نفسه.

تُبلغك الإجابة الناجحة بحصتك في ثلاث ترويسات. وهناك ترويستان أخريان تستحقان أن تعرفهما.

الحدود وترويسات الحصة
الترويسةالوصف
X-RateLimit-Limitحصتك لهذا السوق في الفترة الحالية.
X-RateLimit-Remainingالطلبات المتبقية في الفترة بعد هذا الطلب.
X-RateLimit-Resetموعد تجدد الحصة، بصيغة الطابع الزمني Unix بالثواني (بالتوقيت العالمي).
Retry-Afterعند خطأ تجاوز المعدل أو عدم التوفر: الثواني التي تنتظرها قبل إعادة المحاولة.
X-Total-Rowsعند تنزيل CSV: عدد صفوف البيانات في الملف، للتحقق من وصوله كاملًا.

الحدود بحسب الباقة

تبلغ تكلفة باقة Starter ‏499 د.إ.‏ شهريًا، بدون ضريبة القيمة المضافة. اطّلع على كل باقة وسعرها السنوي

الحدود بحسب الباقة
الباقةتقييم أو استعلام شهريًا لكل سوقالأسواقالتقييم بتاريخ سابقالجدول اليومي الكامل (CSV)ملف على مستوى الإعلانات (CSV)
تجربة مجانيةمدتها 14 يومًا50سوق واحد تختارهآخر 90 يومًاغير مشمولغير مشمول
Starter300سوق واحد تختارهآخر 90 يومًاغير مشمولغير مشمول
Pro3,000جميع الأسواقالسجل كاملًا (منذ 12 يونيو 2026)مشمولغير مشمول
Business15,000جميع الأسواقالسجل كاملًا (منذ 12 يونيو 2026)مشمولمشمول عند الدفع السنوي
Datasetبالدفع السنوي فقط300سوق واحد تختارهآخر 90 يومًامشمولمشمول

سجل الأسعار

يبدأ سجل أسعار كل سوق في تاريخ ثابت. ويمكن طلب تقييم لأي تاريخ (as_of) منذ ذلك اليوم، ضمن نطاق سجل باقتك.

سجل الأسعار
السوقالسجل منذ
قطر7 يونيو 2026
الإمارات12 يونيو 2026
السعودية14 يونيو 2026

احصل على مفتاح

التسجيل والدفع ومفاتيح الواجهة كلها عبر dealers.gcccardeals.com: اشترك، ثم أنشئ مفتاحًا لكل سوق من لوحة واجهة البيانات.

جرّب شكل البيانات قبل الاشتراك: ملف CSV مجاني من جداول الأسعار في الإمارات، بالأسعار المطلوبة وبعملة السوق. له أعمدة الملف المدفوع نفسها، وتُترك فيه أعمدة الفئة والحالة وشريحة المسافة المقطوعة والعداد والتقدير فارغة.

جرّب مجانًامجانًا لمدة 14 يومًا: بحد 50 طلبًا شهريًا، في سوق واحد. يصلح أي بريد إلكتروني وتلزم بطاقة دفع، وإذا ألغيت قبل انتهاء التجربة فلن تدفع شيئًا.

باقات واجهة البيانات وحسابكاقرأ شروط واجهة البيانات

الجهة التي تتعامل معها

تُباع الخدمة من قِبل Dealer's Cloud, Corp.‎ (فرجينيا، الولايات المتحدة، منذ 2010). عمليات الخليج: شركة البراق العربية المحدودة، جدة، سجل تجاري 7037935777.

أسئلة عن باقة أو فاتورة أو البيانات؟ تواصل معنا مباشرة.