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.
| Field | Location | Required | Notes |
|---|---|---|---|
| content | Top level | Required in examples | Post text |
| platforms | Top level | Required in examples | Array of platform targets |
| platforms[].platform | Platform target | Required in examples | Use googlebusiness for Google Business Profile |
| platforms[].accountId | Platform target | Required in examples | Connected location id |
| platforms[].platformSpecificData | Platform target | Optional | Google Business Profile specific fields |
| mediaItems | Top level | Optional | Array of media objects, e.g. type image with url |
| publishNow | Top level | Used for immediate publish | Set true to publish now |
| scheduledFor | Top level | Alternative to publishNow | ISO timestamp for scheduling |
| timezone | Top level | Optional | Timezone for scheduledFor, e.g. America/New_York |
Requiredness reflects the fields shown in the source examples; no additional schema was supplied.
| Field | Values or format | Required when | Notes |
|---|---|---|---|
| topicType | EVENT or OFFER | Event or offer post | Discriminator for event and offer shapes |
| callToActionType | BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL, GET_OFFER | Button post | Button type |
| callToActionUrl | URL | Every callToActionType except CALL | Required except for CALL |
| eventTitle | String | topicType EVENT | Event title |
| eventStartDate | Date, e.g. 2026-09-18 | topicType EVENT | Event start date |
| eventStartTime | Time, e.g. 18:00 | topicType EVENT | Event start time |
| eventEndDate | Date, e.g. 2026-09-18 | topicType EVENT | Event end date |
| eventEndTime | Time, e.g. 21:00 | topicType EVENT | Event end time |
| offerCouponCode | String | topicType OFFER | Coupon code |
| offerRedeemOnlineUrl | URL | topicType OFFER | Online redemption URL |
| offerTermsConditions | String | topicType OFFER | Offer terms |
Enums and conditions are exactly as stated in the source; no additional values supplied.
| Check | Failure to avoid | How to verify |
|---|---|---|
| Authentication | Missing or incorrect x-access-key header | Confirm the header is present on every request |
| Location | accountId does not match a connected location | List integrations and compare ids before posting |
| Call-to-action | callToActionUrl omitted for a non-CALL callToActionType | Check the CALL exception before sending |
| Event fields | topicType EVENT without event title or date/time fields | Confirm all event fields are present |
| Offer fields | topicType OFFER without coupon, redeem URL, or terms | Confirm all offer fields are present |
| Scheduling | scheduledFor not a valid ISO timestamp or timezone mismatch | Review 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.
curl {{API_BASE_URL}}/v1/connect/googlebusiness \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"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
}'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
}'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
}'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
}'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
}'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"
}'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
}'