Google Business Profile create post API
The Google Business Profile create post API lets developers send location updates, dated events, promotions, calls to action, and a single image for display alongside a business on Google Search and Maps. This guide walks through connecting a location, resolving its accountId, and submitting a post whose platformSpecificData, mediaItems, and publishNow values match the contract exactly.
Overview: updates, events, offers, CTAs, and images on Search and Maps
A Google Business Profile post is a location-scoped announcement rather than a general social feed item. Developers can use it for everyday news, a dated event, or a promotion, optionally pairing the text with a button and one picture. Because each variant needs different details, decide the variant first and assemble only the fields that variant calls for. That ordering prevents most validation failures before the request is sent.
Quick Start contract
Begin with the connection request shown in Connect Google Business Profile, then send the person to the OAuth address it returns. Every location they pick becomes its own integration. After that, query the integrations list for googlebusiness as shown in List integrations to find the location account ID, and copy the matching integration id into accountId. Finally, submit the payload illustrated in Publish a Google Business Profile update, supplying content, the platforms entry, mediaItems, and publishNow. Double-check the accountId against the intended location, since using another location's id would publish to the wrong place.
Add an image
Pictures belong at the top level of the request, inside mediaItems, with type set to image and url pointing at a file anyone can retrieve. Retrieval must work without any session cookies, auth headers, or sign-in step, so test the address in a clean browser session before publishing. Keep the address out of platformSpecificData entirely. When the file lives on a private or local system, upload it first and then reuse the publicUrl it returns, as illustrated in Attach one public image via mediaItems. Only a single picture is allowed, and moving pictures in GIF or video form are not accepted for this destination.
Post types STANDARD, EVENT, OFFER and CTA URL rule
The STANDARD variant covers ordinary announcements and applies when topicType is omitted. Choosing EVENT means the request must carry an event title plus start and end dates, and the field map also marks start and end times as required for that variant, using YYYY-MM-DD for dates and HH:MM in 24-hour form for times. The OFFER variant is for promotions and may carry a coupon code, an online redemption address, and terms text. For buttons, every callToActionType except CALL needs a callToActionUrl; run that check before sending and stop if the address is missing.
Platform-specific data field map
Google-specific settings travel inside platformSpecificData on the platforms entry. The Platform-specific data field map table lists every supported key with its type, whether it is required, allowed values, and any conditional rule. Use the exact spellings there, including topicType, callToActionType, callToActionUrl, eventStartDate, and offerCouponCode, because altered names will not be recognised. Once accepted, the finished post is shown on Google Search and Maps next to the location.
Limits and failure matrix
Body text must be present and stay within 1,500 characters. Attach no more than one picture, and avoid video or GIF media altogether. The Limits and failure matrix table turns those rules into a checklist covering a missing CTA address, incomplete event details, an image address that needs sign-in, extra pictures, unsupported media kinds, and text that is absent or too long. Fix the payload for the failing row and send a corrected request instead of repeating the same one.
| Field | Type | Required | Values and constraints | Description |
|---|---|---|---|---|
| topicType | string | No | STANDARD, EVENT, OFFER | Post type. Defaults to STANDARD. Use EVENT for event posts, OFFER for promotional offer posts. |
| callToActionType | string | No | BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL, GET_OFFER | Call-to-action button shown on the post. |
| callToActionUrl | string | No | Format: uri | URL for the call-to-action. Required for all CTA types except CALL. |
| eventTitle | string | No | — | Event title. Required when topicType is EVENT. |
| eventStartDate | string | No | — | Event start date in YYYY-MM-DD format. Required when topicType is EVENT. |
| eventStartTime | string | No | — | Event start time in HH:MM (24-hour) format. Required when topicType is EVENT. |
| eventEndDate | string | No | — | Event end date in YYYY-MM-DD format. Required when topicType is EVENT. |
| eventEndTime | string | No | — | Event end time in HH:MM (24-hour) format. Required when topicType is EVENT. |
| offerCouponCode | string | No | — | Coupon code for OFFER posts. |
| offerRedeemOnlineUrl | string | No | Format: uri | Online redemption URL for OFFER posts. |
| offerTermsConditions | string | No | — | Terms and conditions text for OFFER posts. |
Requiredness is as listed in the source table; conditional requirements in Description apply when topicType or callToActionType triggers them.
| Failure case | Check | Fix |
|---|---|---|
| Missing callToActionUrl | callToActionType is set and is not CALL, but callToActionUrl is absent | Add callToActionUrl as a uri, or remove the CTA type |
| Missing EVENT fields | topicType is EVENT but eventTitle, eventStartDate, eventStartTime, eventEndDate, or eventEndTime is absent | Add eventTitle, eventStartDate (YYYY-MM-DD), eventStartTime (HH:MM), eventEndDate (YYYY-MM-DD), and eventEndTime (HH:MM) |
| Private image URL | mediaItems image URL requires cookies, authorization headers, or login | Upload the image and use the returned publicUrl |
| Multiple images | mediaItems contains more than one image | Keep at most one image per post |
| Video or GIF | mediaItems type is video or GIF | Remove video/GIF; Google Business Profile does not support them |
| Over-length text | content exceeds 1,500 characters or is missing | Shorten content to at most 1,500 characters and ensure text is present |
Checks are derived from source-stated limits and conditional requirements; no error response contract was supplied.
curl "{{API_BASE_URL}}/v1/connect/googlebusiness" \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/connect/integrations?platform=googlebusiness" \
-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": "gbp_123",
"platformSpecificData": {
"topicType": "STANDARD",
"callToActionType": "LEARN_MORE",
"callToActionUrl": "https://example.com/friday-hours"
}
}
],
"mediaItems": [
{
"type": "image",
"url": "https://cdn.example.com/friday-hours.jpg"
}
],
"publishNow": true
}'{
"mediaItems": [
{
"type": "image",
"url": "https://cdn.example.com/uploads/photo.png"
}
]
}curl {{API_BASE_URL}}/v1/connect/googlebusiness \
-H "x-access-key: YOUR_API_KEY"{
"mediaItems": [
{
"type": "image",
"url": "{{MEDIA_BASE_URL}}/uploads/example/photo.png"
}
]
}