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

تحقّق من حالة إدراج النشاط التجاري واحصل على روابطه المنشورة

تابع مزامنة كل منصة نشر لموقع، واجمع روابط إدراجات الأنشطة التجارية المنشورة، ولخّص التغطية، وافحص المساعدات الصوتية، وتلقّ إشعارات webhook بدل الاستقصاء.

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

1. اجلب إدراجات الأنشطة التجارية المميزة لموقع معيّن

تُرجع GET /locations/{locationId}/listings/premium سجلًا واحدًا لكل منصة نشر مميزة ضمن الخطة. والنتيجة مصفوفة عادية، وليست قائمة مقسّمة إلى صفحات. يُرجع المسار المقابل /listings/additional الأدلة المجانية بالبنية نفسها؛ ولا يوجد معامل استعلام باسم listingType.

Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

يجمع كل صف بين site وsyncStatus قابل للقراءة آليًا وdisplayStatus قابل للقراءة البشرية. يوضّح lastUpdate وقت آخر تغيير في الصف، وهو ما يساعد على رصد طلب إرسال توقّفت معالجته.

2. اطّلع على حالة كل منصة نشر

syncStatus هو الحقل الذي تحدّد على أساسه مسار التنفيذ. displayStatus هو النص الذي يُعرض للمستخدم، ويتضمن syncIssue السبب الذي تقدّمه منصة النشر، إن وُجد.

syncStatusالمعنىالإجراء المطلوب
AVAILABLEجاهز للإرسال، ولم يبدأ الإرسال بعد.لا يلزم أي إجراء. ينتقل إلى المرحلة التالية تلقائيًا.
IN_PROGRESSأُرسل إلى منصة النشر، وفي انتظار ردّها.انتظر. تحقّق من lastUpdate إذا مرّت أسابيع.
PENDING_APPROVALاستلمته منصة النشر وتجري مراجعته.انتظر.
SYNCED أو COMPLETEDمنشور. يتضمن listingUrl قيمة.اجمع الرابط (الخطوة 3).
REQUIRING_ACTIONمتوقف بانتظار إجراء منك. قيمة actionRequired هي true.اقرأ displayStatus، ثم راجع العثور على أخطاء إدراجات الأنشطة التجارية وإصلاحها.
FAILEDرفضته منصة النشر أو تعذّرت عليها معالجته.اقرأ syncIssue، وصحّح بيانات الموقع، ثم أعد الاستقصاء.
CANNOT_SUBMITلا تستطيع منصة النشر هذه قبول هذا الموقع مطلقًا.عادةً ما يكون السبب بلدًا أو فئة لا تدعمها منصة النشر.

تظل حالة Google Maps وFacebook هي REQUIRING_ACTION حتى يُربط الحساب الخاص بمنصة النشر المعنية: ملف Google Business Profile لخدمة Google Maps وصفحة Facebook لخدمة Facebook. وهذا متوقع لموقع جديد، ولا يُعدّ خللًا.

لا تتطلب Apple Maps ربط حساب. إذا لم يربط المالك حساب مؤسسة موثّقًا في Apple Business، فإن ListingsAPI تُرسل الموقع عبر حسابها الخاص في Apple Business Connect، وتتحقّق Apple من طلب الإرسال قبل نشره. راجع ربط Apple Business Connect.

لا تُضبط قيمة listingUrl إلا في صفوف الإدراجات المنشورة. صفِّ النتائج للاحتفاظ بصفوف SYNCED (وCOMPLETED)، واحتفظ بعنوان URL مع اسم الموقع الإلكتروني لتتمكن من عرض قائمة «عرض الإدراج المنشور» أو تخزينه ضمن سجلك الخاص.

Live links
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

قد يظهر فعلًا صف بالحالة SYNCED تكون فيه قيمة listingUrl هي null: فبعض الأدلة لا تتيح عنوان URL لصفحة عامة. اعتمد على الحالة بوصفها المرجع الحاسم، واعتبر الرابط اختياريًا.

4. أنشئ ملخصًا للتغطية

يمنحك عدّ الصفوف بحسب syncStatus رقمًا موجزًا في سطر واحد لحالة كل موقع: عدد منصات النشر التي نُشرت عليها الإدراجات، وعدد المنصات التي لا تزال إدراجاتها قيد المعالجة، وعدد المنصات التي توقّفت إدراجاتها بسبب عائق. هذا هو العدد الذي ينبغي عرضه في لوحة التحكم.

Coverage
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

نفّذ ذلك على مواقع عديدة بالتنقّل بين صفحات GET /locations واستدعاء نقطة النهاية الخاصة بالإدراجات المميزة مرة واحدة لكل موقع. يُحتسب كل استدعاء ضمن حد معدل الطلبات المسموح لك به، لذا اترك فاصلًا زمنيًا بين الاستدعاءات والتزم بـ Retry-After عند تلقّي 429. يوضّح دليل العثور على أخطاء إدراجات الأنشطة التجارية وإصلاحها هذه الحلقة بوصفها فحصًا شاملًا على مستوى الحساب.

5. تحقق من المساعدات الصوتية

للمساعدات الصوتية (Google Assistant وAlexa وSiri وCortana وBixby) نقطة نهاية خاصة بها، GET /locations/{locationId}/voice-assistants، تضم مجموعة أصغر من الحالات. يعتمد Google Assistant على الاتصال بـGoogle، لذا فإن أي موقع غير متصل به يحتاج إلى الاهتمام هنا أيضًا. تأتي نتائج Siri من إدراج النشاط التجاري الخاص بالموقع على Apple Maps.

Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}
syncStatusالمعنى
NOT_SUBMITTEDلم يُرسَل إلى المساعد بعد.
IN_PROGRESSجارٍ الإرسال.
REQUIRING_ACTIONمتوقف بانتظار إجراء منك؛ اقرأ syncIssue.
LIVEتم النشر.

لا يوجد رابط منشور للمساعد الصوتي؛ LIVE هي الحالة النهائية.

6. تلقَّ أحداث webhook بدلًا من الاستقصاء الدوري

إذا كان لديك عنوان URL لـwebhook مُعدّ في /dashboard/webhooks، فسيُطلَق الحدث listing.submission في كل مرة تصل فيها عملية إرسال إلى منصة نشر لموقع واحد إلى حالة نهائية. يتضمن الحدث status (success أو incomplete أو canceled)، والموقع، وlive_link عند النجاح، وهو عنوان URL نفسه الذي جمعته في الخطوة 3.

Route listing.submission
import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

أرسل استجابة تتضمن 200 خلال 5 ثوانٍ ونفّذ العمل بعد ذلك؛ إذ لا تُعاد محاولة الإرسال. للاطلاع على الهيكل الأساسي للمستقبِل والتحقق من التوقيع، راجع الاستجابة للأحداث باستخدام webhooks.

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