Listings APIListings API
تسجيل الدخول

البدء

أنشئ حسابك، وأضف وسيلة دفع، واحصل على مفتاح API، وأجرِ أول استدعاء لك إلى Listings API.

يشرح هذا الدليل كيفية إنشاء حساب، والحصول على أول مفتاح API لك، وإرسال طلب إلى Listings API.

1. أنشئ حسابك

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

2. أضف وسيلة دفع

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

3. عيّن كلمة مرورك وسجّل الدخول

بمجرد إتمام إجراءات الدفع، نرسل إليك عبر البريد الإلكتروني رابطًا لتعيين كلمة مرورك وتفعيل حسابك. بعد تعيين كلمة مرورك، سجّل الدخول باستخدام بريدك الإلكتروني وكلمة مرورك، أو اختر Email me a sign-in link (إرسال رابط تسجيل الدخول إلى بريدي الإلكتروني) لتلقّي رابط دخول (magic link) صالح لمرة واحدة بدلًا من ذلك.

4. احصل على مفتاح API

يُصدَر أول مفتاح API لك تلقائيًا عند إنشاء حسابك، ويمكنك العثور عليه في لوحة التحكم ضمن API Keys. لإنشاء مفتاح آخر، اختر New key (مفتاح جديد)، وامنحه اسمًا، واختر مستوى الوصول الخاص به (Read (قراءة) أو Write (كتابة)).

5. أرسل طلبك الأول

استخدم في كل طلب ترويسة Authorization للمصادقة، على أن تكون قيمتها السلسلة النصية الحرفية API (لاحظ المسافة في نهايتها)، متبوعةً بمفتاحك:

Shell
curl https://listingsapi.com/api/v4/locations \  -H "Authorization: API $LISTINGSAPI_KEY"

تأتي الاستجابة ببنية متداخلة وليست مجرد مصفوفة: توجد النتائج ضمن data.allLocations، وكل سجل هو edges[].node، ويحتوي pageInfo على مؤشر ترقيم الصفحات والإجماليات.

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "countryIso": "US"          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "total": 1      }    }  }}

للانتقال إلى الصفحة التالية، أعد تمرير pageInfo.endCursor بوصفه ?after=… ما دامت قيمة pageInfo.hasNextPage هي true، وتوقف أيضًا إذا أُعيدت صفحة تحتوي على مصفوفة edges فارغة. يحتوي كل عنصر edge أيضًا على cursor الخاص به، وتكون قيمة cursor لآخر عنصر edge هي endCursor لتلك الصفحة، لذا يمكن استخدام أيٍّ من القيمتين بوصفها ?after=.

لا تستخدم جميع نقاط نهاية القوائم الطريقة نفسها لتقسيم النتائج إلى صفحات

البنية edges / node / pageInfo أعلاه تتبع أسلوب Relay القائم على المؤشر، وهي واحدة فقط من ثلاث طرق:

  • صفحات قائمة على المؤشر (first، after → edges[].node بالإضافة إلى pageInfo مع endCursor / hasNextPage): المواقع، والبحث عن المواقع، ونقاط نهاية التقييمات (التفاعلات لكل موقع والتجميع على مستوى الحساب).
  • صفحات قائمة على الإزاحة (page، perPage → مصفوفة records بالإضافة إلى pageInfo مع totalRecords، totalPages، hasNextPage، hasPreviousPage): الحسابات المتصلة، واقتراحات الاتصال، والمنشورات لموقع، والمنشورات الجماعية لموقع، وتجميع إدراجات الأنشطة التجارية المكررة على مستوى الحساب بأكمله.
  • مصفوفات بسيطة، دون أي تقسيم إلى صفحات: نقاط نهاية الكتالوج (الفئات الفرعية، والبلدان والولايات، ومنصات النشر المشمولة في الخطة) وصور موقع.

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

الخطوات التالية

  • تصريح ليوم واحد لبيئة الاختبار: جرّب المواقع وإدراجات الأنشطة التجارية دون الحاجة إلى بطاقة. يمكنك أنت أو وكيل الذكاء الاصطناعي الخاص بك تفعيله.
  • المصادقة: ترويسات مفتاح API وتدوير المفاتيح.
  • رموز الأخطاء: رموز حالة HTTP وبنية استجابة الخطأ.
  • حزم SDK: مكتبات عميل لـ Python وNode مزودة بتعريفات الأنواع.