جلب منشورات موقع

المعلمات

المسار

الاسم	النوع	مطلوب	الوصف
locationId	string	مطلوب	Base64-encoded location cursor / global ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`). Pass it unchanged, do not URL-encode it. The base64 cursor always resolves; the raw numeric database ID also works on this endpoint, but the base64 form is the portable choice across the API.

الاستعلام

الاسم	النوع	مطلوب	الوصف	الافتراضي
page	integer	اختياري	1-based page number for offset pagination.	1
perPage	integer	اختياري	Number of records per page. Must not exceed 50.	10

الاستجابات

200A page of post campaigns for the location, under `data.postsByLocation`. `records` is empty when the location has no posts yet.

Response

{  "data": {    "postsByLocation": {      "records": [        {          "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],          "clientName": "Jenny Home"        }      ],      "locationDetails": [        {          "id": "TG9jYXRpb246MTgwMDI4OQ==",          "name": "Jenny Home",          "street": "600 Congress Ave, Suite 200",          "city": "Austin",          "postalCode": "78701",          "countryIso": "US",          "stateIso": "TX",          "stateName": "Texas",          "storeId": null        }      ],      "pageInfo": {        "totalPages": 1,        "hasNextPage": false,        "hasPreviousPage": false,        "totalRecords": 1      }    }  }}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

استخدم نقطة النهاية هذه لاسترداد سجل المنشورات لفرع واحد، بما يشمل كل حملة إعلان أو فعالية أو عرض تتضمن الموقع، مع status الخاص بدورة حياتها وعدّادات التفاعل لكل منشور (views، clicks، reactions).

حالة استخدام: تدقيق ما قبل الحملة. قبل جدولة منشور جديد على Google لصالح Jenny Home، استدعِ GET /locations/TG9jYXRpb246MTgwMDI4OQ==/posts لمعرفة المنشورات المنشورة بالفعل، والمنشورات التي لا تزال في حالة SCHEDULED، وأداء الإعلان الأخير. اقرأ type في كل سجل لتحديد العروض؛ لا توفر نقطة النهاية هذه عامل تصفية حسب النوع على جانب الخادم.

تنبيهات.

الوسيطتان الوحيدتان اللتان تقبلهما نقطة النهاية هذه هما page وperPage. لا يوجد هنا أي معامل باسم filters أو sortFields أو locationIds أو componentIdentifier (فهذه تخص نقطة نهاية المنشورات الجماعية)، ويُتجاهل إرسال أي منها بدلًا من رفضه. صفِّ records المُرجَع ورتّبه في شيفرتك.
يُرفض tag مباشرةً في هذا المسار، مع tag is not a supported parameter for this query. استخدم نقطة نهاية المنشورات الجماعية عندما تحتاج إلى تحديد مجموعة مواقع بناءً على وسم.
الحد الأقصى لـ perPage هو 50؛ وتؤدي أي قيمة أكبر إلى فشل الطلب مع per_page must not exceed 50.
مرِّر locationId بوصفه مؤشرًا بترميز base64 ‏(مثل TG9jYXRpb246MTgwMDI4OQ==) تمامًا كما تُرجعه نقاط نهاية السرد/البحث، ولا تُخضعه لترميز URL.
يعتمد تقسيم النتائج إلى صفحات على الإزاحة: استخدم page وperPage (القيمة الافتراضية 10)، واقرأ pageInfo.totalPages / pageInfo.totalRecords لمعرفة متى تتوقف.
قد يؤدي الاستعلام الدوري المستمر إلى بلوغ حد معدل الطلبات للحساب (HTTP 429)؛ التزم بترويسة Retry-After.

مصفوفة records في المثال أعلاه توضيحية. لا يحتوي الموقع الفعلي المُعدّ مسبقًا (Jenny Home) حاليًا على أي منشورات اجتماعية، لذا يُرجع الاستدعاء الفعلي records: [] مع pageInfo.totalRecords: 0.

ذو صلة: أنشئ منشورات باستخدام POST /posts، أو اجلب حملة واحدة باستخدام GET /posts/{postId}، أو اسرد الحملات الجماعية (متعددة المواقع) باستخدام GET /locations/{locationId}/bulk-posts، التي تقبل بالفعل filters وsortFields وتُرجع الاستجابة ضمن rollupSocialPosts.