Skip to content

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.

Platform-specific data field map
FieldTypeRequiredValues and constraintsDescription
topicTypestringNoSTANDARD, EVENT, OFFERPost type. Defaults to STANDARD. Use EVENT for event posts, OFFER for promotional offer posts.
callToActionTypestringNoBOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, CALL, GET_OFFERCall-to-action button shown on the post.
callToActionUrlstringNoFormat: uriURL for the call-to-action. Required for all CTA types except CALL.
eventTitlestringNo—Event title. Required when topicType is EVENT.
eventStartDatestringNo—Event start date in YYYY-MM-DD format. Required when topicType is EVENT.
eventStartTimestringNo—Event start time in HH:MM (24-hour) format. Required when topicType is EVENT.
eventEndDatestringNo—Event end date in YYYY-MM-DD format. Required when topicType is EVENT.
eventEndTimestringNo—Event end time in HH:MM (24-hour) format. Required when topicType is EVENT.
offerCouponCodestringNo—Coupon code for OFFER posts.
offerRedeemOnlineUrlstringNoFormat: uriOnline redemption URL for OFFER posts.
offerTermsConditionsstringNo—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.

Limits and failure matrix
Failure caseCheckFix
Missing callToActionUrlcallToActionType is set and is not CALL, but callToActionUrl is absentAdd callToActionUrl as a uri, or remove the CTA type
Missing EVENT fieldstopicType is EVENT but eventTitle, eventStartDate, eventStartTime, eventEndDate, or eventEndTime is absentAdd eventTitle, eventStartDate (YYYY-MM-DD), eventStartTime (HH:MM), eventEndDate (YYYY-MM-DD), and eventEndTime (HH:MM)
Private image URLmediaItems image URL requires cookies, authorization headers, or loginUpload the image and use the returned publicUrl
Multiple imagesmediaItems contains more than one imageKeep at most one image per post
Video or GIFmediaItems type is video or GIFRemove video/GIF; Google Business Profile does not support them
Over-length textcontent exceeds 1,500 characters or is missingShorten 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.

Connect Google Business Profile
curl "{{API_BASE_URL}}/v1/connect/googlebusiness" \
  -H "x-access-key: YOUR_API_KEY"
List integrations to find the location account ID
curl "{{API_BASE_URL}}/v1/connect/integrations?platform=googlebusiness" \
  -H "x-access-key: YOUR_API_KEY"
Publish a Google Business Profile update
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
  }'
Attach one public image via mediaItems
{
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/uploads/photo.png"
    }
  ]
}
Contract example 1
curl {{API_BASE_URL}}/v1/connect/googlebusiness \
  -H "x-access-key: YOUR_API_KEY"
Response example 6
{
	"mediaItems": [
		{
			"type": "image",
			"url": "{{MEDIA_BASE_URL}}/uploads/example/photo.png"
		}
	]
}