/api/v4/locations/{locationId}/listings/premiumجلب إدراجات النشاط التجاري المميزة لموقع
يعيد حالة المزامنة لكل دليل تابع لمنصة نشر ضمن خطة الموقع.
المعلمات
المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| locationId | string | مطلوب | Location to read. Accepts a base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
الاستجابات
200Array of listings with per-directory sync status.
{ "data": { "listingsForLocation": [ { "id": "TGlzdGluZzoxMDQ0Njg3MjM=", "databaseId": "104468723", "site": { "id": "U2l0ZTox", "databaseId": "1", "name": "Google Maps", "url": "maps.google.com", "syScore": "100" }, "syncStatus": "REQUIRING_ACTION", "displayStatus": "Connect your account to sync the listing", "actionRequired": true, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:28Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MTQ=", "databaseId": "104468714", "site": { "id": "U2l0ZToxODA=", "databaseId": "180", "name": "Bing", "url": "www.bing.com", "syScore": "97" }, "syncStatus": "IN_PROGRESS", "displayStatus": "Information submitted to partner; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:35Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3Mjc=", "databaseId": "104468727", "site": { "id": "U2l0ZTozODc=", "databaseId": "387", "name": "BeLocalFocussed", "url": "belocalfocussed.com", "syScore": "80" }, "syncStatus": "SYNCED", "displayStatus": "Synced", "actionRequired": false, "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e", "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:30Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MDk=", "databaseId": "104468709", "site": { "id": "U2l0ZTozMDE=", "databaseId": "301", "name": "Local Mint", "url": "localmint.com", "syScore": "69" }, "syncStatus": "FAILED", "displayStatus": "Partner experiencing issues; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:34:03Z", "indexStatus": false, "syncIssue": "Publisher requires website URL", "verified": false } ] }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
يعيد حالة المزامنة لكل دليل تابع لمنصة نشر ومشمول في خطة الموقع. يقرن كل سجل site (البيانات الوصفية للدليل) بكل من syncStatus وdisplayStatus بصيغة مقروءة للبشر. المثال أعلاه مقتطع من الاستجابة الفعلية لـ Jenny Home (التي تعيد أكثر من 30 دليلًا) لعرض سجل واحد لكل حالة من الحالات الشائعة.
فئة إدراج النشاط التجاري جزء من المسار: يعيد /listings/premium الأدلة المميزة ضمن الخطة (المعروضة هنا)، ويعيد /listings/additional إدراجات النشاط التجاري الإضافية/المجانية. لا يوجد معامل استعلام باسم listingType؛ وتُتجاهل أي قيمة تُرسل فيه.
حالة استخدام: لوحة لمتابعة حالة إدراجات النشاط التجاري
اجلب إدراجات النشاط التجاري المميزة لموقع وجمّعها حسب syncStatus لإظهار التغطية بنظرة سريعة، وعدد الأدلة المنشورة أو قيد المعالجة أو المتوقفة بسبب عوائق. اعرض listingUrl للصفوف ذات الحالة SYNCED ليتمكن المستخدمون من النقر للانتقال إلى إدراج النشاط التجاري المنشور، واقرأ displayStatus/syncIssue لأي عنصر لم يُزامَن (مثل Publisher requires website URL).
حالة استخدام: عرض العوائق التي تتطلب "ربط حسابك"
صفِّ النتائج بحسب actionRequired: true لإنشاء قائمة المهام المطلوبة من المالك. في البيانات الفعلية، تُعاد Google Maps وFacebook وWaze بالحالة REQUIRING_ACTION مع displayStatus: "Connect your account to sync the listing"، وتتطلب هذه المنصات اتصالًا عبر OAuth قبل أن تتمكن من المزامنة. وجّه المالك إلى خطوات الربط المناسبة، ثم كرر الاستعلام عن نقطة النهاية هذه لمتابعة تقدم الحالة.
قيم syncStatus: AVAILABLE (جاهز للمزامنة، ولم تبدأ بعد)، IN_PROGRESS (أُرسل إلى الشريك، وبانتظار الرد)، PENDING_APPROVAL (بانتظار موافقة الشريك)، SYNCED / COMPLETED (منشور؛ listingUrl معبّأ)، REQUIRING_ACTION (يلزم إجراء من المالك، انظر displayStatus)، FAILED (فشلت المزامنة؛ انظر syncIssue)، CANNOT_SUBMIT (الإرسال غير ممكن).
هذه قائمة خاصة بكل موقع وتخضع لحد معدل الطلبات على مستوى الحساب؛ عند تلقي 429، أعد المحاولة بعد انقضاء المدة المحددة في ترويسة Retry-After بدلًا من تكرار الاستعلام فورًا.
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/listings/premium' \ -H "Authorization: API $LISTINGSAPI_KEY"