Gönderiler
Tüm Posts uç noktaları için cURL, Python ve Node örnekleri: duyuru, etkinlik, teklif, zamanlama, konum bazlı ve toplu kampanya, durum sorgulama ve silme.
Gönderi, bir konumun Google Business Profile veya Facebook sayfasında yayımlanan kısa bir güncellemedir: bir duyuru, tarihli bir etkinlik veya kupon içeren bir teklif. Tek bir kampanya, aynı anda birçok konumu ve her iki siteyi de hedefleyebilir. Yayımlama eşzamansızdır, bu nedenle her oluşturma çağrısı hemen döner ve sonucu düzenli aralıklarla sorgularsınız. Üç GET endpoint'i bir Read (okuma) anahtarıyla çalışır; oluşturma ve silme işlemleri için bir Write (yazma) anahtarı gerekir.
Endpoint'lere genel bakış
Her yerde kullanacağınız değerler
Aşağıdaki dört enum'un tümü, her oluşturma endpoint'inde ortak olarak kullanılır.
Duyuru yayımlayın
POST /posts
Bir duyuru, bir mesaj ve isteğe bağlı olarak site başına bir düğme ve bir görsel alır. postSites içinde listelenen her site için bir postMessage girdisi sağlayın. Yayımlama arka planda yürütüldüğünden, yanıt yeni kampanyayı status değeri INPROGRESS olarak ayarlanmış şekilde döndürür.
Parametreler
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] } } }}socialPost.id değerini saklayın. Bu, buradaki diğer tüm endpoint'lerin gerektirdiği base64 gönderi kimliğidir. Her iki SDK yardımcı işlevi de tek bir message dizesi alır ve bunu site başına bir girdiye dönüştürür; bu nedenle postMessage dizisini yalnızca cURL içinde elle oluşturmanız gerekir.
Etkinlik yayımlayın
POST /posts
Etkinlik, tarihli bir kart olarak görüntülenir. Etkinliğin kendi zamanlaması postContextInfo içindedir. Ayrı bir postScheduledDates nesnesi, gönderinin kendisinin ne zaman görüneceğini ve süresinin ne zaman dolacağını kontrol eder; bu aralık genellikle etkinlik öncesindeki dönemdir. Google, başlığı olmayan bir etkinliği reddeder ve title eksikse her iki SDK da göndermeden önce bir doğrulama hatası verir.
Parametreler
Duyuru tablosundaki her şey burada da geçerlidir.
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" } } } }}Döndürülen contextInfo, etkinliğin zaman aralığıdır. scheduledStartDate ve scheduledEndDate, gönderinin kendi zamanlamasını belirtir; burada postScheduledDates gönderilmediği için bu zamanlama etkinlik tarihleriyle eşleşir.
Bir teklif yayınlayın
POST /posts
Teklif; kupon kodu, indirim, yararlanma bağlantısı ve koşullar içeren bir promosyon kartıdır. Bunların tümü postContextInfo içinde yer alır; startDay ve endDay ise gönderinin değil, teklifin geçerlilik süresini sınırlar.
Parametreler
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" } } } }}Teklif düğmeleri için Google ORDER, Facebook ise GET_OFFER kabul eder. Bir promosyon erken sona ererse kampanyayı düzenlemek yerine silin.
Bir gönderiyi ve durumunu okuyun
GET /posts/{postId}
Kabul edilmiş bir kampanyanın yayınlanan sonucunu döndürür. data.socialPostView altında kampanya içeriğini, her site için bir publishDetails kaydını, etkileşim sayaçlarını ve yayınlama başarılı olduktan sonra yayındaki gönderilerin bağlantılarını içeren bir yanıt döndürür.
Parametreler
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 } ] } }}İki durum alanı önemlidir ve bunlar farklı soruları yanıtlar.
Bir kampanyanın durumu SUCCESS iken kampanyadaki bir sitenin durumu ERROR olabilir; bu nedenle her zaman yalnızca üst düzey durumu değil, publishDetails alanını da kontrol edin.
Bir konumdaki gönderileri listeleyin
GET /locations/{locationId}/posts
data.postsByLocation altında, belirli bir konumu içeren tüm kampanyaların ofset tabanlı sayfalama kullanan geçmişi bulunur. Yeni bir gönderi planlamadan önce hâlihazırda nelerin yayında olduğunu denetlemek için bunu kullanın.
Parametreler
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 } } }}Bu yol sunucu tarafında filtrelemeyi desteklemez. Yalnızca page ve perPage kabul edilir, diğer her şey yok sayılır; bu nedenle her kayıttaki type ve status alanlarını okuyup kendi kodunuzda filtreleyin. Sunucu tarafında sıralama ve filtreleme yapmak için bunun yerine aşağıdaki toplu listeleme uç noktasını kullanın.
Bir gönderiyi silin
DELETE /posts/{postId}
Bu işlem kalıcıdır ve gönderiyi ulaştığı tüm sitelerde yayından kaldırır. Geri alma işlemi ve düzenleme uç noktası bulunmadığından, yayındaki bir gönderiyi düzeltmek için onu silmeniz ve yerine yeni bir gönderi yayınlamanız gerekir.
Parametreler
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==" } }}Bilinmeyen veya zaten silinmiş bir gönderiyi silme işlemi, data alanı success: false yerine null olarak ayarlanmış bir hata yanıtı döndürür.
Bir kampanyayı çok sayıda konumda yayınlayın
POST /bulk-posts
POST /posts ile aynı sözleşmeyi kullanır ve çok sayıda konumu yönetmek için tasarlanmıştır: tüm konumları locationIds içinde listeleyin; tek bir kampanya hepsini kapsar. Yanıt, POST /posts ile aynı şekilde createSocialPost anahtarı altında yer alır.
Parametreler
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] } } }}Her iki SDK'nın yardımcı işlevi de sites için varsayılan olarak Google ve Facebook'u kullanır, site başına mesaj eşlemesini sizin için genişletir ve sayısal konum kimliklerini kodlar; dolayısıyla toplu yayınlama, her iki SDK'da da genellikle en kısa çağrıdır.
Tek bir toplu kampanyayı okuyun
GET /bulk-posts/{postId}
GET /posts/{postId} işleminin toplu karşılığıdır. Aynı yapıyı döndürür; publishedLocationsCount değeri 1'den büyüktür ve socialPostAnalyticsByLocationId içinde mağaza başına analiz dökümü bulunur.
Parametreler
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, kampanyanın tüm mağazalardaki toplamlarını verirken socialPostAnalyticsByLocationId aynı sayıların mağaza başına dökümünü sunar. Bir sitede işlemin başarısız olduğu konumları bulmak için mağaza başına status değerlerini tarayın.
Bir konumdaki toplu kampanyaları listeleyin
GET /locations/{locationId}/bulk-posts
data.rollupSocialPosts altında ofset tabanlı olarak sayfalanır. Konum başına listenin aksine bu uç nokta, filtreleri ve sıralamayı kabul eder; bu da onu bir kampanya kontrol paneli için uygun uç nokta yapar.
Parametreler
Sıralanabilir alanlar name, type, status, created_at, schedule_start_date, schedule_end_date, client_name, clicks, views ve shares alanlarıdır.
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 } } }}Her iki SDK da filters ve sortFields nesnelerini sizin için JSON biçiminde kodlar; bu nedenle bunları dilin yerel sözlük veya nesne türleriyle iletin.
Karşılaşacağınız hatalar
Tam liste Hata kodları bölümündedir.
Sonraki adımlar
- Gönderi yayınlayın: bu sayfanın, zamanlanmış bir kampanyanın baştan sona anlatıldığı görev odaklı sürümü.
- İşletme kaydı durumunu ve yayındaki bağlantıları kontrol edin: bir konuma gönderi yayınlamadan önce konumun Google'da yayında olduğunu doğrulayın.
- Google'ı bağlayın ve konumları içe aktarın: herhangi bir sitenin gönderiyi kabul edebilmesi için konuma bir hesabın bağlı olması gerekir.
- Webhook'larla olaylara tepki verin:
local_postolayları, yayınlama sonuçlarını düzenli aralıklarla sorgulamanın yerini alır. - Yukarıdaki her uç noktanın tam alan listesi için Gönderiler referansı.