Posts

Publish announcements, events, and offers to Google and Facebook with the listingsapi-js SDK.

Post methods publish content to Google Business Profile and Facebook, then let you monitor per-site publish status and analytics. All post methods live directly on the ListingsAPI client instance.

Publishing is asynchronous: create calls return status: 'INPROGRESS', and the post publishes in the background. Poll fetchPost until the status is SUCCESS, and check publishDetails[].submissionError for per-site failures.

bulkPublish

Publish one post to Google and Facebook across many locations in a single call. sites defaults to both. The message (or per-site map) expands to one entry per site, location IDs are encoded automatically, and the payload is validated client-side before any network call (an invalid payload throws ValidationError immediately).

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

Pass an object as message for per-site copy:

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!',
},
});

Options

createAnnouncement

Create an ANNOUNCEMENT post: a plain message with optional CTA and media. Takes the same options as bulkPublish minus postType and contextInfo; here sites defaults to ['GOOGLE'].

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

Create an EVENT post with a title and a start/end window. title is required (Google requires it); startDay and endDay are YYYY-MM-DD dates, and startTime/endTime are optional display times. sites defaults to ['GOOGLE'].

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

Create an OFFER post with a coupon, discount, and terms. title is required; all other offer fields are optional. sites defaults to ['GOOGLE'].

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

Offer options

createPost

Create a post from a raw body (flat fields, not input-wrapped), sent to the API as-is with no client-side validation. Prefer createAnnouncement, createEvent, or createOffer, which build and validate this body for you.

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

fetchPost

Get a post with its content, per-site publish status, and analytics. Use it to poll an INPROGRESS post until it publishes.

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

Delete a post and remove it from every site it was published to.

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

fetchLocationPosts

List post campaigns targeting a location. Uses offset pagination (page and perPage); tag defaults to 'all' because the API errors when it is omitted.

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

Options

fetchBulkPost

Get a bulk campaign with per-location publish status and analytics.

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

fetchLocationBulkPosts

List bulk (multi-location) campaigns that include a location. Takes the same options as fetchLocationPosts.

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

Related resources

• Locations, look up location IDs
• Error handling, ValidationError and platform error codes