حزمة Python SDK

عميل Python الرسمي لـ Listings API، مع موارد محددة الأنواع، وترقيم صفحات بالمؤشر، وإعادة محاولات تلقائية، وأخطاء مسماة.

حزمة listingsapi هي عميل Python الرسمي لـ Listings API. وهي تغلّف طبقة REST بفئات موارد ذات أنواع محددة، وتقسيم النتائج إلى صفحات باستخدام المؤشرات، وإعادة المحاولة تلقائيًا عند حدوث أخطاء مؤقتة، واستثناء مسمّى لكل نوع من أنواع الفشل، بما في ذلك حمولات الأخطاء التي تعيدها المنصة مع HTTP 200.

التثبيت

pip install listingsapi

يتطلب Python 3.9 أو أحدث. الاعتمادية الوحيدة وقت التشغيل هي requests.

المصادقة

import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

احصل على مفتاح API من مفاتيح API → مفتاح جديد في لوحة التحكم للمطورين في Listings API.

يقبل العميل ثلاث وسائط اختيارية تُمرَّر بالاسم:

راجع الإعدادات للاطلاع على التفاصيل.

مثال سريع

import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

الموارد

كل مورد هو خاصية في العميل:

توجد أربع دوال مساعدة في العميل نفسه:

client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

تقسيم النتائج إلى صفحات

تستخدم الدوال التي تعيد قوائم تقسيم النتائج إلى صفحات باستخدام المؤشرات. تعيد كل دالة تدعم تقسيم النتائج إلى صفحات كائنًا من نوع SyncPage: قابلًا للتكرار، ويتضمن .has_more و.next_page() و.auto_paging_iter() و.total.

# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

كائنات الاستجابة

تعيد جميع الدوال APIObject (يدعم الوصول عبر السمات وبصيغة dict) أو SyncPage (قابل للتكرار ومقسّم إلى صفحات). يدعم APIObject أيضًا .get() و.to_dict().

loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

معالجة الأخطاء

يرث كل خطأ في SDK من listingsapi.ListingsAPIError. تؤدي حالات فشل API إلى إطلاق APIError أو إحدى فئاته الفرعية: AuthenticationError وPermissionDeniedError وNotFoundError وValidationError وRateLimitError (مع .retry_after) وInternalServerError. تؤدي حالات فشل الشبكة إلى إطلاق APIConnectionError.

يتضمن APIError كلًا من status_code وcode (أول رمز خطأ من المنصة، e.g. SY10005) وerrors (يُوحَّد تنسيق كل عنصر ليكون قاموسًا بصيغة {"code", "message", "context"}) وresponse_body.

تُبلغ المنصة عن بعض حالات الفشل داخل متن استجابة HTTP 200: حمولات errors[] في المستوى الأعلى (تُعاد الرموز غير الصالحة بصيغة SY90005)، واستجابات عمليات الكتابة التي تتضمن success=false. يطلق SDK استثناءات لهذه الحالات أيضًا، لذلك لا تحتاج أبدًا إلى فحص علامات success بنفسك.

import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

راجع معالجة الأخطاء للاطلاع على التسلسل الهرمي الكامل للاستثناءات.

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

• التثبيت: البيئات الافتراضية، وتثبيت إصدارات محددة
• البدء السريع: الاستدعاءات الأولى، وإنشاء موقع، والرد على تقييم
• الإعدادات: المهل الزمنية، وإعادة المحاولة، وعنوان URL الأساسي
• حالات الاستخدام: أمثلة تطبيقية من البداية إلى النهاية
• المواقع، التقييمات، إدراجات الأنشطة التجارية، التحليلات