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=MEDIAadds it to the gallery instead). These endpoints are the gallery's own API.
List gallery media
- Method:
GET - Endpoint:
/api/uploadposts/google-business/media
| Parameter | Required | Description |
|---|---|---|
user | Yes | Profile username. |
location_id | No | Location to read. |
page_size | No | 1–2500 (default 100). |
page_token | No | next_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):
| Field | Required | Description |
|---|---|---|
user | Yes | Profile username. |
location_id | No | Target location. |
file | One of | The photo (JPG or PNG, up to 5 MB) or video (MP4 or MOV) to upload. |
source_url | One of | Public http(s) URL Google downloads the media from. |
category | No | COVER, 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. |
description | No | Up to 1000 characters. Not allowed on COVER, and it cannot be changed later. |
media_format | No | PHOTO 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}, ormedia_keywithlocation_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
| Status | error_code | Meaning |
|---|---|---|
| 400 | media_source_required / invalid_media_source | Send exactly one of file or source_url. |
| 400 | invalid_source_url | source_url is not a public http(s) URL. |
| 400 | invalid_media_category / category_required | Unknown or missing category. |
| 400 | invalid_media_format, invalid_media_file, invalid_description | Wrong format, unreadable file or description not allowed. |
| 400 | MEDIA_TOO_SMALL | Photo under 250 px or 10 KB. |
| 413 | MEDIA_TOO_LARGE | File over the size Google accepts. |
| 400 | invalid_media_name / media_name_required | Missing or malformed media_name / media_key. |
| 400 | confirmation_required | Delete without "confirm": true. |
| 400 | invalid_json | The body of a PATCH or DELETE is not a valid JSON object. |
| 404 | media_not_found | The media item does not exist. |
| 409 | MEDIA_LIMIT_REACHED | Google refused the upload: the location already has the 100 items the API can add. |
| 429 | google_rate_limited, daily_limit_reached | Too many requests (per minute) or the daily limit of reads (scope, daily_limit); retry after retry_after_seconds. |
| 429 | media_upload_busy | Too many uploads in progress; retry in a few seconds. |
| 504 | media_outcome_unknown | Google did not confirm the upload; list the gallery before retrying. |