Listings APIListings API
登入

貼文

使用 listingsapi-js SDK，將公告、活動和優惠發布至 Google 和 Facebook。

貼文方法會將內容發布至 Google Business Profile 和 Facebook，並讓您監控各網站的發布狀態與分析資料。所有貼文方法都直接位於 ListingsAPI 用戶端實例上。

發布作業以非同步方式進行：建立呼叫會傳回 status: 'INPROGRESS'，貼文則在背景發布。請輪詢 fetchPost，直到狀態為 SUCCESS，並查看 publishDetails[].submissionError，確認各網站的發布失敗情況。

bulkPublish

只需呼叫一次，即可將同一篇貼文發布至多個地點的 Google 和 Facebook。sites 預設包含這兩個網站。訊息（或各網站的對應表）會展開為每個網站各一筆項目，地點 ID 會自動編碼，且酬載會在發出任何網路呼叫前於用戶端驗證（無效的酬載會立即擲回 ValidationError）。

TypeScript
const result = await client.bulkPublish({name: 'Holiday hours',locationIds: [16808, 16809, 16810],message: 'Open until 10pm through the holidays!',mediaUrl: 'https://cdn.example.com/holiday.jpg',ctaType: 'LEARN_MORE',ctaUrl: 'https://example.com/holiday-hours',});console.log(result.socialPost.id, result.socialPost.status); // INPROGRESS, publishes async

若要為各網站設定不同文案，請將物件傳入 message：

TypeScript
await client.bulkPublish({name: 'Holiday hours',locationIds: [16808, 16809],message: {  GOOGLE: 'Open until 10pm through the holidays. Book online!',  FACEBOOK: 'We are staying open late for the holidays. See you soon!',},});

選項

參數型別說明
namestring內部行銷活動名稱（不會顯示給客戶）。必填。
locationIdsArray<string | number>要發布至的地點（數字或 base64 ID）。必填。
messagestring 或各網站的對應表所有網站共用的貼文內文，或 { GOOGLE, FACEBOOK } 對應表。必填。
sitesPostSite[]目標網站；預設為 ['GOOGLE', 'FACEBOOK']。
postTypePostTypeANNOUNCEMENT（預設值）、EVENT、OFFER、COVID19 或 PRODUCT。
ctaTypePostCtaTypeBOOK、ORDER、SHOP、LEARN_MORE、SIGN_UP 或 GET_OFFER。必須搭配 ctaUrl。
ctaUrlstringCTA 按鈕的連結目標。必須搭配 ctaType。
mediaUrlstring在每個網站附加的公開圖片 URL。
scheduledDatesobject用於排定發布／到期時間的 { startDatetime, endDatetime, removalSites }。
contextInfoobject當 postType 需要時提供的活動或優惠詳細資訊。
additionalFieldsobject額外的扁平 camelCase 欄位，會原樣合併至請求主體。

createAnnouncement

建立 ANNOUNCEMENT 貼文：純文字訊息，可選擇附加 CTA 和媒體。接受的選項與 bulkPublish 相同，但不包含 postType 和 contextInfo；此處的 sites 預設為 ['GOOGLE']。

TypeScript
await client.createAnnouncement({name: 'Grand Opening',locationIds: [16808],message: 'Acme Dental is now open in the Mission!',sites: ['GOOGLE'],ctaType: 'LEARN_MORE',ctaUrl: 'https://example.com/opening',});

createEvent

建立包含標題與起訖期間的 EVENT 貼文。title 為必填（Google 要求提供）；startDay 和 endDay 是 YYYY-MM-DD 日期，startTime／endTime 則是選填的顯示時間。sites 預設為 ['GOOGLE']。

TypeScript
await client.createEvent({name: 'Live music',locationIds: [16808],message: 'Join us Friday for live jazz!',title: 'Jazz Night',startDay: '2026-08-01',endDay: '2026-08-01',startTime: '7:00pm',endTime: '10:00pm',});

createOffer

建立包含優惠券、折扣與條款的 OFFER 貼文。title 為必填；其餘優惠欄位皆為選填。sites 預設為 ['GOOGLE']。

TypeScript
await client.createOffer({name: 'Summer sale',locationIds: [16808],message: '20% off whitening all week!',title: 'Summer Sale',couponCode: 'SUMMER20',discount: '20%',redeemUrl: 'https://example.com/sale',termsConditions: 'One per customer.',startDay: '2026-08-01',endDay: '2026-08-07',});

優惠選項

參數型別說明
titlestring優惠標題。必填。
couponCodestring客戶兌換時使用的代碼。
discountstring折扣說明，例如 '20%'。
redeemUrlstring線上兌換連結。
termsConditionsstring條款與條件文字。
startDaystring優惠有效期間的開始日期，YYYY-MM-DD。
endDaystring優惠有效期間的結束日期，YYYY-MM-DD。

createPost

使用由扁平欄位組成的原始主體建立貼文，不進行用戶端驗證。此方法會將您傳入的內容包裝在 API 要求的 input 物件中，因此實際傳送的主體為 {"input": {...}}；完全扁平的主體會遭到拒絕，並傳回 HTTP 400。建議優先使用 createAnnouncement、createEvent 或 createOffer，這些方法會為您建構並驗證此主體。

TypeScript
await client.createPost({postName: 'Grand Opening',locationIds: ['TG9jYXRpb246MTY4MDg='],postType: 'ANNOUNCEMENT',postSites: ['GOOGLE'],postMessage: [{ site: 'GOOGLE', message: 'We are now open!' }],});

fetchPost

取得貼文及其內容、各網站的發布狀態與分析資料。使用此方法輪詢 INPROGRESS 貼文，直到發布完成。

TypeScript
let post = await client.fetchPost('U29jaWFsUG9zdDo0NDEyMg=='); while (post.status === 'INPROGRESS') {await new Promise((resolve) => setTimeout(resolve, 5000));post = await client.fetchPost('U29jaWFsUG9zdDo0NDEyMg==');} for (const detail of post.publishDetails ?? []) {if (detail.submissionError) {  console.log('failed:', detail.submissionError);}}

deletePost

刪除貼文，並從所有已發布該貼文的網站移除。

TypeScript
await client.deletePost('U29jaWFsUG9zdDo0NDEyMg==');

fetchLocationPosts

列出以某個地點為目標的貼文行銷活動。使用位移分頁（page 和 perPage），並解析為 postsByLocation。

此路由會拒絕 tag，因此自 0.3.2 起，SDK 為了向下相容而接受此選項，但絕不會將其傳送出去。需要依標籤篩選時，請使用 fetchLocationBulkPosts。

TypeScript
const posts = await client.fetchLocationPosts(16808, { page: 1, perPage: 10 });

選項

參數型別說明
tagstring接受此選項，但不會在此路由的請求中傳送。請參閱上方說明。
pagenumber頁碼（從 1 開始）。
perPagenumber每頁結果數。
filtersobject貼文篩選欄位（自動編碼為 JSON）。
sortFieldsobject排序物件，例如 { field: 'created_at', order: 'Descending' }。

fetchBulkPost

取得批次行銷活動，以及各地點的發布狀態與分析資料。

TypeScript
const bulk = await client.fetchBulkPost('QnVsa1Bvc3Q6OTk=');

fetchLocationBulkPosts

列出包含某個地點的批次（多地點）行銷活動。接受的選項與 fetchLocationPosts 相同。

TypeScript
const campaigns = await client.fetchLocationBulkPosts(16808, { page: 1, perPage: 10 });