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

البدء السريع

اتصل بـ Listings API، واستعرض مواقعك، وأنشئ موقعًا باستدعاء واحد، وردّ على تقييم.

1. عيّن مفتاح API

احصل على مفتاحك من مفاتيح API → مفتاح جديد في لوحة التحكم للمطورين في Listings API. تقرأ حزمة SDK المفتاح تلقائيًا من متغير البيئة LISTINGSAPI_KEY.

bash
export LISTINGSAPI_KEY="your-api-key"

2. اعرض قائمة مواقعك

quickstart.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")
bash
python quickstart.py

المخرجات المتوقعة:

bash
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=False

لطلب جميع الصفحات تلقائيًا، استخدم client.locations.list(first=100).auto_paging_iter()؛ فهو يتتبع الصفحات باستخدام مؤشرات التصفح، فلا تحتاج أبدًا إلى إدارة هذه المؤشرات يدويًا.

3. أنشئ موقعًا باستدعاء واحد

يقبل locations.add() كل حقل إلزامي كوسيطة مسمّاة ويتحقق من صحة هذه الحقول على جانب العميل (طول الاسم، والحد الأدنى للوصف البالغ 200 حرف، والفئة، والبلد، والمدينة) قبل أي استدعاء عبر الشبكة، لذلك تفشل العملية فورًا إذا كانت حمولة الطلب غير صالحة، مع ValidationError واضح.

Python
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add(  name="Acme Dental Uptown",  description=(      "Acme Dental Uptown is a family-owned dental practice on the Upper "      "West Side of New York offering preventive care, cosmetic dentistry, "      "orthodontics, and emergency appointments. Our board-certified team "      "combines modern equipment with a gentle, patient-first approach."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="482 Columbus Ave",  state_iso="NY",  postal_code="10024",  phone="6443859313",) print(result.location.id)print(result.location.name)

تستخدم منصات النشر الوصف بوصفه النص الأساسي لإدراج النشاط التجاري، ولهذا تشترط API ألا يقل طوله عن 200 حرف. احصل على قيم صالحة للحقل sub_category_id من client.subcategories().

يُعاد المعرّف الجديد كسلسلة نصية بترميز base64 مثل TG9jYXRpb246MTY4MDg=. يمكن استخدام المعرّفات الرقمية والمعرّفات بترميز base64 بالتبادل في كل موضع تقبل فيه حزمة SDK معرّف موقع، لذا يجلب كل من client.locations.retrieve(16808) وclient.locations.retrieve("TG9jYXRpb246MTY4MDg=") الموقع نفسه.

4. رُدّ على تقييم

اعرض قائمة التقييمات لموقع، ثم رُدّ باستخدام interactionId الخاص بالتقييم:

Python
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews:  print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable:  print("nothing to reply to")else:  client.reviews.respond(      interaction_id=repliable[0].interactionId,      content="Thank you for the kind review! We look forward to seeing you again soon.",  )

تحقق من canRespond قبل الرد، ولا تصل أبدًا إلى عنصر في صفحة باستخدام فهرسه دون التأكد أولًا من أنها غير فارغة: يؤدي reviews[0] على صفحة فارغة إلى إطلاق IndexError، ويفشل الرد على تقييم أغلقته المنصة المصدر لدى منصة النشر، وليس لدى API.

إذا رفضت المنصة الرد، تُطلق حزمة SDK الاستثناء ValidationError حتى عندما تكون حالة HTTP هي 200؛ ولا تحتاج أبدًا إلى التحقق من علامات success بنفسك.

5. عالج الأخطاء

Python
import listingsapi try:  client = listingsapi.ListingsAPI(api_key="bad-key")  client.locations.list()except listingsapi.AuthenticationError as e:  print("Invalid key:", e.code)

عند استخدام مفاتيح غير صالحة، تكون الاستجابة HTTP 401 مع رمز المنصة SY90005؛ وتُطلق حزمة SDK الاستثناء AuthenticationError. وتتعامل أيضًا احترازيًا مع رمز الخطأ نفسه إذا ورد داخل جسم 200. راجع معالجة الأخطاء للاطلاع على التسلسل الهرمي الكامل للاستثناءات، ومرجع رموز الأخطاء للاطلاع على مصفوفة حالات HTTP.

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