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 });