Skip to content

Google Business Profile posting API

The Google Business Profile posting API described here publishes updates, events, offers, photos, and scheduled posts to a Google Business Profile location through a single POST /v1/posts request. You authenticate with the x-access-key header, connect a location to obtain its accountId, and then send content with platform-specific fields for call-to-action buttons, mediaItems, topicType, publishNow, scheduledFor, and timezone. The examples below preserve the exact request contract so you can adapt them to your own application.

Overview: what the API posts and where it appears

A Google Business Profile post can be an update, an event, or an offer, and it can carry a photo and a call-to-action button. The single-endpoint approach in this guide sends all of those shapes through POST /v1/posts, with the Google Business Profile target identified by platform googlebusiness and a location accountId. A published post appears on the location's Google Search and Maps listing. This differs from working directly with a native local-post model, where updates, events, and offers each have their own shape and access typically involves an allowlist request and OAuth setup. Use the comparison as a decision aid: choose the single-endpoint contract when you want one payload shape for publishing and scheduling, and verify native API requirements separately if you need first-party access.

Prerequisites and authentication with x-access-key

You need an API key, a Google account that manages at least one Google Business Profile location, and the location accountId you will post to. Every request uses the x-access-key header, shown in the authentication example. Keep the key secret and treat it like a password, because anyone holding it can act with your connected locations. Before posting, confirm that the location you intend to target is connected and that you have copied its id correctly, since a wrong accountId sends the post to the wrong location or fails validation.

Connect a Google Business Profile location and retrieve accountId

Call the connect endpoint for googlebusiness to obtain an authorization URL, open that URL, authorize access, and select the locations you want to manage. Each connected location becomes an integration, and listing integrations returns the id for each location. Use that id as the accountId in the platforms array of POST /v1/posts. If a location does not appear in the list, re-check the authorization step and the selected locations before attempting to post, because posting requires a valid accountId for the target location.

Create a post: POST /v1/posts contract and field map

A standard update is the default post type. Send content, a platforms array containing platform googlebusiness and the location accountId, and publishNow set to true to publish immediately. The field map table below distinguishes required and optional fields, and the worked examples that follow show the exact payloads for each post type. When you replace publishNow with scheduledFor, provide an ISO timestamp and an optional timezone to queue the post instead of publishing it immediately.

Post types: update, call-to-action, photo, event, and offer

Add callToActionType and callToActionUrl inside platformSpecificData to attach a button to an update. The complete set of permitted button values is enumerated in the platform-specific field table below, so check that table before choosing a value. One value in that set is treated differently for the URL field: the table states the exception explicitly, and omitting the URL for any other value is a validation failure you should check before sending. For a photo, add a mediaItems array with an object whose type is image and whose url points to the image; the request uploads that image to the profile as part of the post. For an event, set topicType to EVENT and provide eventTitle, eventStartDate, eventStartTime, eventEndDate, and eventEndTime. For an offer, set topicType to OFFER and provide offerCouponCode, offerRedeemOnlineUrl, and offerTermsConditions. Check each field against the tables below before sending, because the discriminator and its companion fields must match.

Scheduling with scheduledFor and timezone

To schedule instead of publishing immediately, replace publishNow with scheduledFor using an ISO timestamp, and add an optional timezone such as America/New_York. Confirm the timestamp and timezone together, since the timezone determines how the scheduled time is interpreted. After scheduling, verify that the queued post reflects the intended content, location accountId, and time before relying on it.

Cross-posting to multiple platforms in one request

Because every platform uses the same POST /v1/posts endpoint, you can include multiple entries in the platforms array to publish the same content to Google Business Profile, Facebook, and Instagram in one request. Each entry carries its own platform and accountId, and platform-specific formatting is applied per platform. Keep the shared content and mediaItems consistent across entries, and verify each accountId belongs to the intended account before sending a cross-post.

Validation matrix, limitations, and next steps

Before sending, run through the validation matrix: confirm the x-access-key header is present, the accountId matches a connected location, the URL field is present where the table requires it for your chosen button value, topicType matches the event or offer fields you supplied, and scheduledFor is a valid ISO timestamp when you are not using publishNow. No response bodies, status codes, or error contracts are documented in the material for this guide, so do not assume specific error shapes. For next steps, consult the field reference and platform documentation for locations and post types, and review the scheduling endpoints if you need to manage queued posts.

POST /v1/posts field map
FieldLocationRequiredNotes
contentTop levelRequired in examplesPost text
platformsTop levelRequired in examplesArray of platform targets
platforms[].platformPlatform targetRequired in examplesUse googlebusiness for Google Business Profile
platforms[].accountIdPlatform targetRequired in examplesConnected location id
platforms[].platformSpecificDataPlatform targetOptionalGoogle Business Profile specific fields
mediaItemsTop levelOptionalArray of media objects, e.g. type image with url
publishNowTop levelUsed for immediate publishSet true to publish now
scheduledForTop levelAlternative to publishNowISO timestamp for scheduling
timezoneTop levelOptionalTimezone for scheduledFor, e.g. America/New_York

Requiredness reflects the fields shown in the source examples; no additional schema was supplied.

Google Business Profile platformSpecificData fields
FieldValues or formatRequired whenNotes
topicTypeEVENT or OFFEREvent or offer postDiscriminator for event and offer shapes
callToActionTypeBOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL, GET_OFFERButton postButton type
callToActionUrlURLEvery callToActionType except CALLRequired except for CALL
eventTitleStringtopicType EVENTEvent title
eventStartDateDate, e.g. 2026-09-18topicType EVENTEvent start date
eventStartTimeTime, e.g. 18:00topicType EVENTEvent start time
eventEndDateDate, e.g. 2026-09-18topicType EVENTEvent end date
eventEndTimeTime, e.g. 21:00topicType EVENTEvent end time
offerCouponCodeStringtopicType OFFERCoupon code
offerRedeemOnlineUrlURLtopicType OFFEROnline redemption URL
offerTermsConditionsStringtopicType OFFEROffer terms

Enums and conditions are exactly as stated in the source; no additional values supplied.

Validation and failure checks
CheckFailure to avoidHow to verify
AuthenticationMissing or incorrect x-access-key headerConfirm the header is present on every request
LocationaccountId does not match a connected locationList integrations and compare ids before posting
Call-to-actioncallToActionUrl omitted for a non-CALL callToActionTypeCheck the CALL exception before sending
Event fieldstopicType EVENT without event title or date/time fieldsConfirm all event fields are present
Offer fieldstopicType OFFER without coupon, redeem URL, or termsConfirm all offer fields are present
SchedulingscheduledFor not a valid ISO timestamp or timezone mismatchReview timestamp and timezone together

Derived only from stated constraints; no status codes or error bodies were supplied.

Frequently asked questions

How do I publish a Google Business Profile update through POST /v1/posts?

Send POST /v1/posts with content, a platforms entry using platform googlebusiness and the location accountId, and publishNow set to true for immediate publication. Use scheduledFor with an ISO timestamp and an optional timezone instead when you want the post queued.

How do event and offer posts differ in the payload?

Set platformSpecificData.topicType to EVENT and provide eventTitle, eventStartDate, eventStartTime, eventEndDate, and eventEndTime. For an offer, set topicType to OFFER and provide offerCouponCode, offerRedeemOnlineUrl, and offerTermsConditions.

Which callToActionType values are supported and when is callToActionUrl required?

The supported values are listed in the platform-specific field table below. Provide callToActionUrl for every type except CALL, where that URL field is not required under the stated rule.

How do I attach a photo to a Google Business Profile post?

Add a mediaItems array containing an object with type image and a url pointing to the image. The same request can include content and the Google Business Profile platform target.

How do I find the accountId for a connected location?

Call the connect endpoint for googlebusiness, open the returned authorization URL, authorize access, and select the locations to manage. Then list integrations and use each location's id as the accountId when posting.

Connect a Google Business Profile location
curl {{API_BASE_URL}}/v1/connect/googlebusiness \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations to retrieve accountId
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
Post a standard update with publishNow
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "googlebusiness", "accountId": "your-location-id" }
    ],
    "publishNow": true
  }'
Post an update with a call-to-action button
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "googlebusiness",
        "accountId": "your-location-id",
        "platformSpecificData": {
          "callToActionType": "BOOK",
          "callToActionUrl": "https://yourshop.com/book"
        }
      }
    ],
    "publishNow": true
  }'
Post a photo using mediaItems
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "googlebusiness", "accountId": "your-location-id" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://your-cdn.com/croissants.jpg" }
    ],
    "publishNow": true
  }'
Post an event with topicType EVENT
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "googlebusiness",
        "accountId": "your-location-id",
        "platformSpecificData": {
          "topicType": "EVENT",
          "eventTitle": "Friday Tasting Night",
          "eventStartDate": "2026-09-18",
          "eventStartTime": "18:00",
          "eventEndDate": "2026-09-18",
          "eventEndTime": "21:00"
        }
      }
    ],
    "publishNow": true
  }'
Post an offer with topicType OFFER
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "googlebusiness",
        "accountId": "your-location-id",
        "platformSpecificData": {
          "topicType": "OFFER",
          "offerCouponCode": "SHINE20",
          "offerRedeemOnlineUrl": "https://yourshop.com/offer",
          "offerTermsConditions": "Valid through Sunday. One per customer."
        }
      }
    ],
    "publishNow": true
  }'
Schedule a post with scheduledFor and timezone
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "googlebusiness", "accountId": "your-location-id" }
    ],
    "scheduledFor": "2026-09-20T14:00:00Z",
    "timezone": "America/New_York"
  }'
Cross-post to multiple platforms in one request
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "googlebusiness", "accountId": "gbp-location-id" },
      { "platform": "facebook", "accountId": "fb-page-id" },
      { "platform": "instagram", "accountId": "ig-account-id" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://your-cdn.com/promo.jpg" }
    ],
    "publishNow": true
  }'