/api/v4/posts/{postId}جلب منشور
يُرجع حملة منشور واحدة على وسائل التواصل الاجتماعي مع محتواها وحالة النشر على كل منصة وتحليلات التفاعل.
المعلمات
المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| postId | string | مطلوب | Base64-encoded social post ID (e.g. from the `id` field of a posts list, or the `socialPost.id` returned by POST /posts). |
الاستجابات
200The post's content, publish details, and analytics.
{ "data": { "socialPostView": { "socialPostId": "U29jaWFsUG9zdDo0NDEyMg==", "socialPostInfo": { "id": "U29jaWFsUG9zdDo0NDEyMg==", "name": "Summer Hours Update", "status": "SUCCESS", "type": "ANNOUNCEMENT", "createdAt": "2026-06-28", "scheduledStartDate": "2026-06-28", "scheduledEndDate": "2026-07-28", "views": 128, "clicks": 14, "shares": 0, "reactions": 3, "comments": 1, "sites": ["GOOGLE"], "message": [ { "site": "GOOGLE", "message": "We have extended our summer hours! Open until 9pm on weekdays." } ], "cta": [ { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/hours", "site": "GOOGLE", "tinyUrl": "https://tiny.cc/jh-hours" } ], "contextInfo": null, "mediaUrl": [ { "url": "https://cdn.listingsapi.com/posts/44122/summer.jpg", "site": "GOOGLE", "type": "IMAGE" } ], "publishDetails": [ { "site": "GOOGLE", "status": "PUBLISHED", "createdDate": "2026-06-28", "publishedDate": "2026-06-28", "submissionError": null } ], "postLinks": [ { "site": "GOOGLE", "link": "https://www.google.com/maps/place/?post=44122" } ], "locationIds": [1800289] }, "publishedLocationsCount": 1, "socialPostAnalyticsBySite": [ { "site": "GOOGLE", "views": 128, "clicks": 14, "reactions": 3, "shares": 0, "comments": 1 } ], "socialPostAnalyticsByLocationId": [ { "locationId": 1800289, "siteStats": [ { "site": "GOOGLE", "status": "PUBLISHED", "views": 128, "clicks": 14, "reactions": 3, "shares": 0, "comments": 1 } ] } ] } }}401Unauthenticated, missing or invalid API key.
يجلب حملة منشور واحدة باستخدام معرّفها، بما في ذلك الرسالة والدعوة لاتخاذ إجراء (CTA) لكل منصة، والوسائط المرفقة، وحالة النشر الفعلية على كل منصة (publishDetails)، والتفاعل موزّعًا حسب المنصة (socialPostAnalyticsBySite) وحسب الموقع (socialPostAnalyticsByLocationId).
حالة استخدام: التحقق بعد النشر. مباشرةً بعد إنشاء إعلان باستخدام POST /posts، خذ socialPost.id المُعاد واستعلم دوريًا عن GET /posts/{postId} حتى تتغير قيمة socialPostInfo.status من INPROGRESS إلى SUCCESS. إذا فشل النشر على إحدى المنصات، فإن publishDetails[].submissionError يتضمن السبب ويعرض publishDetails[].status القيمة ERROR.
حالة استخدام: لوحة تحكم لعرض التفاعل. بالنسبة إلى منشور يخص موقعًا واحدًا، اقرأ socialPostAnalyticsBySite لعرض مقارنة بين Google وFacebook من حيث المشاهدات والنقرات دون إعادة جلب قائمة الموقع بالكامل.
ملاحظات.
postIdهو المعرّف المُرمّز باستخدام Base64 الذي يظهر باسمidفي قائمة المنشورات أو باسمsocialPost.idفي استجابة الإنشاء، وليس عددًا صحيحًا خامًا.- لجلب حملة متعددة المواقع (جماعية)، استخدم
GET /bulk-posts/{postId}، الذي يُرجع البنية نفسها معpublishedLocationsCount > 1.
أُنشئ هذا المثال استنادًا إلى مخطط API. لا يحتوي الحساب الفعلي المُعدّ بالبيانات الأولية (Jenny Home) على أي منشورات، لذلك لم يكن هناك معرّف منشور حقيقي لاستخدامه في الجلب؛ ويؤدي استخدام معرّف غير معروف أو غير صالح إلى إرجاع {"data":null,"errors":[{"message":"An error occurred processing your request."}]}.
curl -X GET 'https://listingsapi.com/api/v4/posts/<postId>' \ -H "Authorization: API $LISTINGSAPI_KEY"