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

البدء السريع

اشترك لتحصل على مفتاح، واحفظه في متغير بيئة، وأرسله رمزَ وصول من نوع 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 مفتاحًا للسوق الذي تختاره، وتتضمن باقتا Pro وBusiness مفتاحًا لكل سوق. وتنشئ مفاتيحك من لوحة واجهة البيانات، ويظهر المفتاح كاملًا مرة واحدة فقط.

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

القيمة السوقية لسيارة واحدة في تاريخ معين، مع الإعلانات المماثلة التي بُنيت عليها.

المعلمات

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

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": "comparable-median-v1",
  "market": "sa",
  "currency": "SAR",
  "as_of": "2026-09-15",
  "window_days": 90,
  "history_since": "2026-06-14",
  "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",
    "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": 13,
    "same_trim": 0
  },
  "year_counts": {
    "2019": 26
  },
  "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",
      "first_seen": "2026-08-30",
      "last_seen": "2026-09-16",
      "still_listed": true,
      "listed_on_as_of": true,
      "city": "riyadh"
    }
  ],
  "reason": null,
  "quota": {
    "monthly": 3000,
    "used_month": 12,
    "daily": null,
    "used_today": null
  },
  "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

القيمة السوقية: السعر المطلوب المعتاد للسيارات المماثلة. تكون null حين لا تتوفر سيارات مماثلة كافية، ويبيّن reason السبب.

valuation.low

الحد الأدنى للنطاق الذي يقع فيه النصف الأوسط من الأسعار المطلوبة للسيارات المماثلة.

valuation.high

الحد الأعلى لذلك النطاق.

valuation.confidence

مقدار الأدلة التي تستند إليها القيمة: high أو medium أو low.

valuation.basis

ما قورنت به السيارة: فئة تجهيزها أو مجموعة فئتها أو سنة صنعها أو نطاق من سنوات الصنع المجاورة.

valuation.premium_trim_group

مجموعة الفئات المؤثرة في السعر التي قُيّمت السيارة على أساسها، حين تنتمي فئتها إلى إحدى هذه المجموعات.

valuation.mileage_matched

تكون true حين تستند القيمة بدرجة أكبر إلى سيارات ذات مسافة مقطوعة مقاربة لمسافة سيارتك.

counts.candidates_total

جميع الإعلانات المطابقة التي رصدناها ضمن النافذة الزمنية.

counts.truncated

تكون true حين يزيد candidates_total على عدد الإعلانات المقروءة.

counts.candidates

الإعلانات المقروءة لهذا التقييم.

counts.distinct_cars

عدد السيارات المختلفة التي تمثلها تلك الإعلانات؛ فالسيارة المعلن عنها أكثر من مرة تُحتسب مرة واحدة.

counts.outliers_dropped

سيارات استُبعدت لأن سعرها غير معتاد في هذه المقارنة.

counts.pool

السيارات المتبقية في المقارنة بعد ذلك.

counts.used

السيارات التي أُخذت منها القيمة.

counts.same_trim

عدد السيارات التي أُخذت منها القيمة وتشترك في الفئة التي أدخلتها.

year_counts

عدد السيارات المماثلة لكل سنة صنع، ويبيّن إلى أي جهة يميل نطاق السنوات.

pool.median_price

وسيط الأسعار المطلوبة في مجموعة المقارنة كلها.

pool.p25

الحد الأدنى للنصف الأوسط من الأسعار المطلوبة في تلك المجموعة.

pool.p75

الحد الأعلى للنصف الأوسط من الأسعار المطلوبة في تلك المجموعة.

pool.median_km

وسيط المسافة المقطوعة للمجموعة بالكيلومتر.

pool.sources

عدد المنصات التي جاءت منها المجموعة.

comparables[].source

المنصة التي وُجد فيها الإعلان.

comparables[].url

رابط الإعلان الأصلي.

comparables[].model_year

سنة صنع السيارة في الإعلان.

comparables[].trim

فئة تجهيز السيارة في الإعلان، حين يذكرها.

comparables[].km

قراءة عداد المسافة في الإعلان بالكيلومتر، حين يذكرها.

comparables[].asking_price

السعر المطلوب في الإعلان بتاريخ price_date بعملة السوق.

comparables[].price_date

تاريخ السعر المطلوب الذي استُخدم في التقييم.

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

السعر المطلوب المعتاد ونطاقه لماركة وطراز واحد، بحسب سنة الصنع وعائلة الفئة وشريحة المسافة المقطوعة.

المعلمات

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

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": "sa",
  "currency": "SAR",
  "as_of": "2026-09-29",
  "window_days": 90,
  "history_since": "2026-06-14",
  "make": "toyota",
  "model": "camry",
  "condition": "used",
  "cells": [
    {
      "model_year": 2019,
      "trim_family": null,
      "mileage_band": "100-150k",
      "cars": 12,
      "median_price": 52000,
      "p25_price": 48000,
      "p75_price": 56000,
      "median_km": 128000
    }
  ],
  "quota": {
    "monthly": 3000,
    "used_month": 12,
    "daily": null,
    "used_today": null
  },
  "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

عائلة الفئة، أو null للفئات الأساسية.

cells[].mileage_band

شريحة المسافة المقطوعة التي تقع فيها السيارات.

cells[].cars

عدد السيارات المختلفة في المجموعة.

cells[].median_price

السعر المطلوب المعتاد للمجموعة. يكون null إذا كانت المجموعة أصغر من أن تُسعَّر.

cells[].p25_price

الحد الأدنى للنصف الأوسط من الأسعار المطلوبة، أو null.

cells[].p75_price

الحد الأعلى للنصف الأوسط من الأسعار المطلوبة، أو null.

cells[].median_km

وسيط المسافة المقطوعة للمجموعة بالكيلومتر.

quota

حصتك وما استهلكته منها: monthly وused_month وdaily وused_today.

notes

ملاحظات بلغة واضحة عن طريقة قراءة الأرقام.

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

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

المعلمات

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

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

يُرسَل الملف تدريجيًا. وإذا انقطع الاتصال قبل اكتماله فاحذفه ولا تعتمد عليه: تبيّن لك ترويسة X-Total-Rows عدد الصفوف المتوقع.

الأعمدة

make

الماركة كما ندرجها.

model

الطراز كما ندرجه.

model_year

سنة الصنع.

trim_family

عائلة الفئة، أو null للفئات الأساسية.

condition

used أو new.

mileage_band

شريحة المسافة المقطوعة التي تقع فيها السيارات.

cars

عدد السيارات المختلفة في المجموعة.

median_price

السعر المطلوب المعتاد للمجموعة. يكون null إذا كانت المجموعة أصغر من أن تُسعَّر.

p25_price

الحد الأدنى للنصف الأوسط من الأسعار المطلوبة، أو null.

p75_price

الحد الأعلى للنصف الأوسط من الأسعار المطلوبة، أو null.

median_km

وسيط المسافة المقطوعة للمجموعة بالكيلومتر.

currency

عملة جميع الأسعار في الإجابة.

computed_on

تاريخ حساب الجدول بالتوقيت العالمي.

الأخطاء

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

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

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

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

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

سجل الأسعار

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