Skip to main content

Google Business Gallery (Photos & Videos)

Manage the photos and videos of a connected Google Business Profile location: list them, read one, upload new ones (from a public URL or by sending the file), change their category and delete them. You can also read the photos that Google Maps users added to the location.

All endpoints use Authorization: Apikey <YOUR_API_KEY> and the profile's existing Google Business connection (no extra permission). location_id is optional when the profile has a single location or a pinned one; it accepts locations/{id}, the bare id or accounts/{a}/locations/{id}.

Posting a photo as part of a post is still done with Upload Photos (gbp_post_type=MEDIA adds it to the gallery instead). These endpoints are the gallery's own API.

  • Method: GET
  • Endpoint: /api/uploadposts/google-business/media
ParameterRequiredDescription
userYesProfile username.
location_idNoLocation to read.
page_sizeNo1–2500 (default 100).
page_tokenNonext_page_token of the previous page.
{
"success": true,
"location_id": "locations/222222222",
"media_items": [
{
"name": "accounts/123456789/locations/222222222/media/AF1QipN",
"mediaFormat": "PHOTO",
"locationAssociation": { "category": "EXTERIOR" },
"googleUrl": "https://lh3.googleusercontent.com/...",
"thumbnailUrl": "https://lh3.googleusercontent.com/...",
"createTime": "2026-11-01T10:00:00Z",
"dimensions": { "widthPixels": 1600, "heightPixels": 1200 }
}
],
"total_media_item_count": 37,
"next_page_token": null,
"api_upload_limit": 100
}

media_items are Google's MediaItem objects unchanged. api_upload_limit: Google accepts at most 100 media items per location added through the API.

Get one media item​

  • Method: GET
  • Endpoint: /api/uploadposts/google-business/media/get

Pass user and either media_name (accounts/.../locations/.../media/{key}) or media_key with location_id. Answers {"success": true, "media_name": "...", "media_item": {...}}; 404 media_not_found if it does not exist.

Upload a photo or video​

  • Method: POST
  • Endpoint: /api/uploadposts/google-business/media

Send either a file (multipart) or a public URL (JSON):

FieldRequiredDescription
userYesProfile username.
location_idNoTarget location.
fileOne ofThe photo (JPG or PNG, up to 5 MB) or video (MP4 or MOV) to upload.
source_urlOne ofPublic http(s) URL Google downloads the media from.
categoryNoCOVER, PROFILE, EXTERIOR, INTERIOR, PRODUCT, AT_WORK, FOOD_AND_DRINK, MENU, COMMON_AREA, ROOMS, TEAMS or ADDITIONAL (default). LOGO is deprecated by Google and is sent as PROFILE.
descriptionNoUp to 1000 characters. Not allowed on COVER, and it cannot be changed later.
media_formatNoPHOTO or VIDEO. Guessed from the file type or the URL extension.
# by file
curl -X POST https://api.upload-post.com/api/uploadposts/google-business/media \
-H 'Authorization: Apikey YOUR_API_KEY' \
-F user=my-profile -F category=INTERIOR -F [email protected]

# by URL
curl -X POST https://api.upload-post.com/api/uploadposts/google-business/media \
-H 'Authorization: Apikey YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"user": "my-profile", "source_url": "https://example.com/front.jpg", "category": "EXTERIOR"}'

Answer (201 Created): {"success": true, "media_name": "...", "media_item": {...}, "upload_method": "bytes" | "url"}.

Photos other than PROFILE and COVER must be at least 250 px on the short edge and 10 KB (Google's rule); smaller ones get 400 MEDIA_TOO_SMALL without reaching Google. Videos are checked by their content (MP4, MOV, 3GP, M4V, AVI, WebM, MKV, MPEG, FLV or WMV), not by the file name.

If Google does not confirm the upload (504 media_outcome_unknown), Upload-Post does not retry it, so you never end up with the same photo twice: list the gallery and upload again only if it is not there. If the request never reached Google you get 502 google_unreachable instead, and it is safe to retry. When too many uploads are in progress you may get 429 media_upload_busy: retry after a few seconds.

Change a media item's category​

  • Method: PATCH
  • Endpoint: /api/uploadposts/google-business/media

Body: {"user": "my-profile", "media_name": "accounts/.../media/AF1QipN", "category": "INTERIOR"}. Only the category can change: Google does not allow editing the description, the format or the source (400 media_field_not_editable).

Delete a media item​

  • Method: DELETE
  • Endpoint: /api/uploadposts/google-business/media

Body: {"user": "my-profile", "media_name": "accounts/.../media/AF1QipN", "confirm": true}. The item disappears from the public profile and cannot be restored. Without "confirm": true the answer is 400 confirmation_required, before anything else is checked.

Customer photos​

  • GET /api/uploadposts/google-business/media/customers?user=&location_id=&page_size=&page_token= (page size 1–200, default 100)
  • GET /api/uploadposts/google-business/media/customers/get?user=&media_name= (accounts/.../media/customers/{key}, or media_key with location_id)

These are the photos Google Maps users added to the location. Each item carries an attribution (contributor name, profile photo and links). Google requires you to show it exactly as provided and never remove or alter it. Customer photos cannot be deleted through the API; attribution.takedownUrl is where an inappropriate one can be reported.

Errors​

Statuserror_codeMeaning
400media_source_required / invalid_media_sourceSend exactly one of file or source_url.
400invalid_source_urlsource_url is not a public http(s) URL.
400invalid_media_category / category_requiredUnknown or missing category.
400invalid_media_format, invalid_media_file, invalid_descriptionWrong format, unreadable file or description not allowed.
400MEDIA_TOO_SMALLPhoto under 250 px or 10 KB.
413MEDIA_TOO_LARGEFile over the size Google accepts.
400invalid_media_name / media_name_requiredMissing or malformed media_name / media_key.
400confirmation_requiredDelete without "confirm": true.
400invalid_jsonThe body of a PATCH or DELETE is not a valid JSON object.
404media_not_foundThe media item does not exist.
409MEDIA_LIMIT_REACHEDGoogle refused the upload: the location already has the 100 items the API can add.
429google_rate_limited, daily_limit_reachedToo many requests (per minute) or the daily limit of reads (scope, daily_limit); retry after retry_after_seconds.
429media_upload_busyToo many uploads in progress; retry in a few seconds.
504media_outcome_unknownGoogle did not confirm the upload; list the gallery before retrying.