Beiträge

Alle Beitragsendpunkte: cURL/Python/Node-Beispiele, Ankündigungen, Veranstaltungen, Angebote, Planung, Standort-/Massenkampagnen, Statusabfragen, Löschen.

Ein Beitrag ist eine kurze Mitteilung, die im Google Business Profile oder auf der Facebook-Seite eines Standorts veröffentlicht wird: eine Ankündigung, eine Veranstaltung mit Datum oder ein Angebot mit Gutschein. Eine Kampagne kann gleichzeitig viele Standorte und beide Plattformen ansprechen. Die Veröffentlichung erfolgt asynchron, sodass jeder Aufruf zum Erstellen sofort zurückkehrt und Sie das Ergebnis durch wiederholte Abfragen abrufen. Die drei GET-Endpunkte funktionieren mit einem Schlüssel mit Read (Lesezugriff); zum Erstellen und Löschen ist ein Schlüssel mit Write (Schreibzugriff) erforderlich.

Endpunkte im Überblick

Werte, die Sie überall verwenden

Alle vier folgenden Enums werden von jedem Endpunkt zum Erstellen gemeinsam verwendet.

Eine Ankündigung veröffentlichen

POST /posts

Eine Ankündigung enthält eine Nachricht und optional eine Schaltfläche und ein Bild pro Plattform. Geben Sie für jede in postSites aufgeführte Plattform einen postMessage-Eintrag an. Die Antwort gibt die neue Kampagne zurück, wobei status auf INPROGRESS gesetzt ist, da die Veröffentlichung im Hintergrund erfolgt.

Parameter

curl -X POST https://listingsapi.com/api/v4/posts \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "postName": "Grand Opening Announcement",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "ANNOUNCEMENT",    "postSites": ["GOOGLE"],    "postMessage": [      { "site": "GOOGLE", "message": "We are now open! Visit us this week for our grand opening." }    ],    "postCta": [      { "site": "GOOGLE", "type": "LEARN_MORE", "url": "https://jennyhome.example/opening" }    ],    "postMediaUrl": [      { "site": "GOOGLE", "url": "https://cdn.example.com/opening.jpg", "type": "IMAGE" }    ]  }}'

{  "data": {    "createSocialPost": {      "success": true,      "errors": [],      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyMg==",        "name": "Grand Opening Announcement",        "status": "INPROGRESS",        "type": "ANNOUNCEMENT",        "sites": ["GOOGLE"],        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHING", "createdDate": "2026-06-28", "submissionError": null }        ],        "postLinks": [],        "locationIds": [1800289]      }    }  }}

Bewahren Sie socialPost.id auf. Dies ist die base64-Beitrags-ID, die jeder andere hier aufgeführte Endpunkt benötigt. Beide SDK-Hilfsfunktionen nehmen eine einzelne message-Zeichenfolge entgegen und erweitern sie zu einem Eintrag pro Plattform, sodass Sie das postMessage-Array nur in cURL von Hand erstellen.

Eine Veranstaltung veröffentlichen

POST /posts

Eine Veranstaltung wird als Karte mit Datum angezeigt. Der Zeitplan der Veranstaltung selbst steht in postContextInfo. Das separate postScheduledDates-Objekt steuert, wann der Beitrag selbst erscheint und abläuft, was üblicherweise dem Zeitraum vor der Veranstaltung entspricht. Google lehnt eine Veranstaltung ohne Titel ab, und beide SDKs lösen vor dem Senden einen Validierungsfehler aus, wenn title fehlt.

Parameter

Alle Angaben aus der Tabelle für Ankündigungen gelten ebenfalls.

curl -X POST https://listingsapi.com/api/v4/posts \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "postName": "Summer Sale Kickoff Event",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "EVENT",    "postSites": ["GOOGLE"],    "postContextInfo": {      "title": "Summer Sale Kickoff",      "startDay": "2026-07-15",      "startTime": "10:00am",      "endDay": "2026-07-15",      "endTime": "06:00pm"    },    "postMessage": [      { "site": "GOOGLE", "message": "Join us for the Summer Sale kickoff, refreshments and up to 40 percent off in store." }    ]  }}'

{  "data": {    "createSocialPost": {      "success": true,      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyMw==",        "status": "INPROGRESS",        "type": "EVENT",        "scheduledStartDate": "2026-07-15",        "scheduledEndDate": "2026-07-15",        "contextInfo": {          "title": "Summer Sale Kickoff",          "startDay": "2026-07-15",          "startTime": "10:00am",          "endDay": "2026-07-15",          "endTime": "06:00pm"        }      }    }  }}

Der zurückgegebene Wert contextInfo ist der Veranstaltungszeitraum. scheduledStartDate und scheduledEndDate beschreiben den Zeitplan des Beitrags selbst, der hier mit den Veranstaltungsdaten übereinstimmt, da kein postScheduledDates gesendet wurde.

Ein Angebot veröffentlichen

POST /posts

Ein Angebot ist eine Aktionskarte mit einem Gutscheincode, einem Rabatt, einem Link zum Einlösen und Bedingungen. All das gehört in postContextInfo, und startDay und endDay begrenzen die Gültigkeit des Angebots statt die des Beitrags.

Parameter

curl -X POST https://listingsapi.com/api/v4/posts \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "postName": "Festive 25 Percent Off",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="],    "postType": "OFFER",    "postSites": ["GOOGLE"],    "postContextInfo": {      "title": "25% off storewide",      "couponCode": "FESTIVE25",      "discount": "25%",      "redeemUrl": "https://jennyhome.example/festive",      "termsConditions": "Valid in-store only through July 6.",      "startDay": "2026-06-22",      "endDay": "2026-07-06"    },    "postMessage": [      { "site": "GOOGLE", "message": "Celebrate with us, 25 percent off everything in store this week." }    ],    "postCta": [      { "site": "GOOGLE", "type": "GET_OFFER", "url": "https://jennyhome.example/festive" }    ]  }}'

{  "data": {    "createSocialPost": {      "success": true,      "socialPost": {        "id": "U29jaWFsUG9zdDo0NDEyNA==",        "status": "INPROGRESS",        "type": "OFFER",        "contextInfo": {          "title": "25% off storewide",          "couponCode": "FESTIVE25",          "discount": "25%",          "startDay": "2026-06-22",          "endDay": "2026-07-06"        }      }    }  }}

Google akzeptiert ORDER und Facebook akzeptiert GET_OFFER für Angebotsschaltflächen. Wenn eine Aktion vorzeitig endet, löschen Sie die Kampagne, statt sie zu bearbeiten.

Einen Beitrag und seinen Status abrufen

GET /posts/{postId}

Gibt das veröffentlichte Ergebnis einer angenommenen Kampagne zurück. Die Antwort enthält unter data.socialPostView den Kampagneninhalt, einen publishDetails-Eintrag pro Website, Interaktionszähler und nach erfolgreicher Veröffentlichung die Links zu den veröffentlichten Beiträgen.

Parameter

curl https://listingsapi.com/api/v4/posts/U29jaWFsUG9zdDo0NDEyMg== \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "socialPostView": {      "socialPostId": "U29jaWFsUG9zdDo0NDEyMg==",      "socialPostInfo": {        "status": "SUCCESS",        "type": "ANNOUNCEMENT",        "views": 128,        "clicks": 14,        "publishDetails": [          { "site": "GOOGLE", "status": "PUBLISHED", "publishedDate": "2026-06-28", "submissionError": null }        ],        "postLinks": [          { "site": "GOOGLE", "link": "https://www.google.com/maps/place/?post=44122" }        ]      },      "publishedLocationsCount": 1,      "socialPostAnalyticsBySite": [        { "site": "GOOGLE", "views": 128, "clicks": 14, "reactions": 3, "shares": 0, "comments": 1 }      ]    }  }}

Zwei Statusfelder sind relevant, und sie beantworten unterschiedliche Fragen.

Eine Kampagne kann den Status SUCCESS haben, während eine darin enthaltene Website den Status ERROR aufweist. Prüfen Sie daher immer publishDetails, statt sich allein auf den Status auf oberster Ebene zu verlassen.

Die Beiträge eines Standorts auflisten

GET /locations/{locationId}/posts

Ein per Offset paginierter Verlauf aller Kampagnen, die einen bestimmten Standort einschließen, unter data.postsByLocation. Prüfen Sie damit, was bereits online ist, bevor Sie etwas Neues planen.

Parameter

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/posts?page=1&perPage=10" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "postsByLocation": {      "records": [        {          "id": "U29jaWFsUG9zdDo0NDEyMg==",          "name": "Summer Hours Update",          "status": "SUCCESS",          "type": "ANNOUNCEMENT",          "createdAt": "2026-06-28",          "views": 128,          "clicks": 14,          "sites": ["GOOGLE"]        }      ],      "pageInfo": { "totalPages": 1, "hasNextPage": false, "totalRecords": 1 }    }  }}

Diese Route bietet keinen serverseitigen Filter. Sie akzeptiert nur page und perPage und ignoriert alles andere. Lesen Sie daher type und status in jedem Datensatz und filtern Sie in Ihrem eigenen Code. Verwenden Sie stattdessen den unten beschriebenen Endpunkt zur Massenauflistung, um serverseitig zu sortieren und zu filtern.

Einen Beitrag löschen

DELETE /posts/{postId}

Die Löschung ist endgültig und entfernt den Beitrag von jeder Website, auf der er veröffentlicht wurde. Es gibt weder eine Möglichkeit zum Rückgängigmachen noch einen Endpunkt zum Bearbeiten. Um einen veröffentlichten Beitrag zu korrigieren, müssen Sie ihn daher löschen und einen Ersatz veröffentlichen.

Parameter

curl -X DELETE https://listingsapi.com/api/v4/posts/U29jaWFsUG9zdDo0NDEyMg== \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "clientMutationId": "delete-44122-req-1" }'

{  "data": {    "deleteSocialPost": {      "success": true,      "socialPostId": "U29jaWFsUG9zdDo0NDEyMg=="    }  }}

Beim Löschen eines unbekannten oder bereits gelöschten Beitrags wird eine Fehlerantwort zurückgegeben, in der data auf null statt auf success: false gesetzt ist.

Eine Kampagne für viele Standorte veröffentlichen

POST /bulk-posts

Dieselben Schnittstellenvorgaben wie bei POST /posts, ausgelegt auf große Standortbestände: Listen Sie jeden Standort in locationIds auf, und eine Kampagne deckt sie alle ab. Die Antwort steht unter dem Schlüssel createSocialPost, genau wie bei POST /posts.

Parameter

curl -X POST https://listingsapi.com/api/v4/bulk-posts \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "postName": "July Reopening Announcement",    "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="],    "postType": "ANNOUNCEMENT",    "postSites": ["GOOGLE", "FACEBOOK"],    "postMessage": [      { "site": "GOOGLE", "message": "We are back. Visit us this week for our summer menu." },      { "site": "FACEBOOK", "message": "We are back. Swing by for the new summer menu." }    ],    "postScheduledDates": {      "startDatetime": "2026-07-10T09:00:00Z",      "endDatetime": "2026-07-24T23:59:00Z"    }  }}'

{  "data": {    "createSocialPost": {      "success": true,      "errors": null,      "socialPost": {        "id": "U29jaWFsUG9zdDo5OTIwMQ==",        "name": "July Reopening Announcement",        "status": "SCHEDULED",        "type": "ANNOUNCEMENT",        "scheduledStartDate": "2026-07-10",        "scheduledEndDate": "2026-07-24",        "sites": ["GOOGLE", "FACEBOOK"],        "locationIds": [1800289, 1800290]      }    }  }}

Beide SDK-Hilfsfunktionen setzen sites standardmäßig auf Google und Facebook, lösen für Sie eine Zuordnung von Nachrichten zu Websites auf und kodieren numerische Standort-IDs, sodass eine Massenveröffentlichung in beiden SDKs meist mit dem kürzesten Aufruf möglich ist.

Eine Sammelkampagne abrufen

GET /bulk-posts/{postId}

Das Gegenstück zu GET /posts/{postId} für Sammelkampagnen. Es gibt dieselbe Struktur zurück, wobei publishedLocationsCount größer als 1 ist und socialPostAnalyticsByLocationId eine Aufschlüsselung der Analysedaten pro Filiale enthält.

Parameter

curl https://listingsapi.com/api/v4/bulk-posts/U29jaWFsUG9zdDo1MTA4OA== \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "socialPostView": {      "socialPostId": "U29jaWFsUG9zdDo1MTA4OA==",      "socialPostInfo": {        "name": "Festive Offer - All Stores",        "status": "SUCCESS",        "type": "OFFER",        "views": 4210,        "clicks": 318,        "sites": ["GOOGLE", "FACEBOOK"]      },      "socialPostAnalyticsByLocationId": [        {          "locationId": 1800289,          "siteStats": [            { "site": "GOOGLE", "status": "PUBLISHED", "views": 1040, "clicks": 80 },            { "site": "FACEBOOK", "status": "PUBLISHED", "views": 360, "clicks": 26 }          ]        }      ]    }  }}

socialPostAnalyticsBySite summiert die Kampagnenwerte über alle Filialen, während socialPostAnalyticsByLocationId dieselben Zahlen pro Filiale aufschlüsselt. Prüfen Sie die status-Werte pro Filiale, um alle Standorte zu finden, bei denen ein Fehler auf einer Website aufgetreten ist.

Sammelkampagnen an einem Standort auflisten

GET /locations/{locationId}/bulk-posts

Unter data.rollupSocialPosts mit Offset-Paginierung. Im Gegensatz zur Liste pro Standort unterstützt diese Route Filter und Sortierung und ist damit der passende Endpunkt für ein Kampagnen-Dashboard.

Parameter

Sortierbare Felder sind name, type, status, created_at, schedule_start_date, schedule_end_date, client_name, clicks, views und shares.

curl -G https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bulk-posts \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'page=1' \--data-urlencode 'perPage=10' \--data-urlencode 'sortFields={"field":"created_at","order":"Descending"}'

{  "data": {    "rollupSocialPosts": {      "records": [        {          "id": "U29jaWFsUG9zdDo1MTA4OA==",          "name": "Festive Offer - All Stores",          "status": "SUCCESS",          "type": "OFFER",          "createdAt": "2026-06-20",          "views": 4210,          "clicks": 318        }      ],      "pageInfo": { "totalPages": 1, "hasNextPage": false, "totalRecords": 1 }    }  }}

Beide SDKs übernehmen die JSON-Kodierung der Objekte filters und sortFields für Sie. Übergeben Sie diese daher als native Dictionaries oder Objekte.

Fehler, die auftreten können

Die vollständige Liste finden Sie unter Fehlercodes.

Nächste Schritte

• Beiträge veröffentlichen: die aufgabenorientierte Version dieser Seite, die eine geplante Kampagne von Anfang bis Ende durchgeht.
• Eintragsstatus und Live-Links prüfen: Vergewissern Sie sich, dass ein Standort auf Google veröffentlicht ist, bevor Sie einen Beitrag dafür veröffentlichen.
• Google verbinden und Standorte importieren: Ein Standort benötigt ein verbundenes Konto, bevor eine Website einen Beitrag akzeptiert.
• Mit Webhooks auf Ereignisse reagieren: Die local_post-Ereignisse ersetzen das wiederholte Abfragen der Veröffentlichungsergebnisse.
• Beitragsreferenz mit der vollständigen Feldliste für jeden der oben genannten Endpunkte.