للأعمال
وثائق واجهة البيانات البرمجية
كل ما تحتاجه لاستخدام واجهة بيانات 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 مدفوعات البطاقات، فلا يصل رقم بطاقتك إلينا. أرسل لنا استبيان تقييم الموردين أو استبيان الأمن لدى شركتك وسنجيب عنه.
جرّبها بمفتاحك
قيّم سيارة تختارها بمفتاحك الخاص في هذه الصفحة نفسها، واطّلع على ما تجيب به الواجهة: القيمة ونطاقها ومستوى الثقة بها، والإعلانات المماثلة التي بُنيت عليها. لا يُرسَل مفتاحك إلا مع هذا الطلب إلى واجهتنا، ولا يُحفظ أبدًا، ويُمسح حين تغادر الصفحة أو تضغط «مسح المفتاح».
ليس لديك مفتاح بعد؟ مفتاح التجربة المجانية يعمل هنا أيضًا:احصل على مفتاح
التقييم
متاح في جميع الباقات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 وDatasetGET https://gcccardeals.com/api/b2b/v1/market-prices.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 بالدفع السنوي، ويُحتسب التنزيل طلبًا واحدًا.
المعلمات
| المعلمة | إلزامية | الوصف |
|---|---|---|
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 يتضمن رمز خطأ يمكنك التصرف بناءً عليه ورسالة واضحة يقرؤها الإنسان.
| الحالة | الرمز | المعنى |
|---|---|---|
400 | bad_request | إحدى المعلمات مفقودة أو غير صالحة، وتبيّن الرسالة أيّها. ولا يُخصم الطلب من حصتك. |
401 | unauthorized | المفتاح غير موجود أو غير صحيح الصيغة أو منتهي الصلاحية أو ملغى. |
403 | plan_limit | باقتك لا تشمل هذا الطلب، مثل الجدول الكامل في باقة Starter، أو الملف على مستوى الإعلانات في باقة لا تتضمنه، أو تاريخ أبعد من نطاق سجل باقتك. تبيّن الرسالة ما ينقص. |
422 | unknown_vehicle | لا نتعرّف على الماركة أو الطراز، ويسرد الحقل error.known_models بعض الطرازات التي نعرفها. أما الطراز المدرج لدينا الذي لا تتوفر له سيارات مماثلة ضمن النافذة الزمنية فلا يُعدّ خطأ، بل تأتي الإجابة دون قيمة مع بيان السبب. |
429 | rate_limited | طلبات كثيرة في وقت قصير. انتظر عدد الثواني الوارد في الترويسة Retry-After. |
429 | busy | ما زال هناك طلب آخر من حسابك قيد التنفيذ. أرسل طلبًا واحدًا في كل مرة. |
429 | quota_exceeded | استُنفدت حصتك الشهرية لهذا السوق، أو استُنفد الحد اليومي للمفتاح. تتجدد الحصة الشهرية مع بداية الشهر الميلادي التالي (بالتوقيت العالمي)، ويتجدد الحد اليومي عند منتصف الليل بالتوقيت العالمي. |
503 | unavailable | تعذّرت قراءة البيانات الآن. أعد المحاولة بعد عدد الثواني الوارد في الترويسة 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 يومًا | غير مشمول | غير مشمول |
| Starter | 300 | سوق واحد تختاره | آخر 90 يومًا | غير مشمول | غير مشمول |
| Pro | 3,000 | جميع الأسواق | السجل كاملًا (منذ 12 يونيو 2026) | مشمول | غير مشمول |
| Business | 15,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.
أسئلة عن باقة أو فاتورة أو البيانات؟ تواصل معنا مباشرة.