Google Business Categories, Chains and Google Locations
Lookups you need before editing a listing: the category ids (gcid:...), the service
types and "more hours" types of a category, the chain a location belongs to, and whether a
business already exists on Google Maps.
- Authentication: API Key —
Authorization: Apikey <YOUR_API_KEY> - Connection: you need at least one Google Business account connected.
useris optional for the catalogs: without it, any connected account of yours is used. - Caching: categories, category details and chains are the same for everyone, so they
are cached for 24 hours (
"cached": truein the answer).
Search categories
- Method:
GET - Endpoint:
/api/uploadposts/google-business/categories
| Parameter | Required | Description |
|---|---|---|
region_code | Yes | ISO 3166-1 alpha-2 country code, e.g. ES. |
language_code | Yes | BCP 47 language, e.g. es. |
query | No | Text to search in the category name (max 100 characters), e.g. bakery. |
view | No | BASIC (default) or FULL (adds serviceTypes and moreHoursTypes). |
page_size / page_token | No | 1-100 (default 100) / next_page_token of the previous page. |
user | No | Profile whose connection is used. |
curl 'https://api.upload-post.com/api/uploadposts/google-business/categories?region_code=ES&language_code=es&query=panader%C3%ADa' \
-H 'Authorization: Apikey YOUR_API_KEY'
{
"success": true,
"categories": [{ "name": "categories/gcid:bakery", "displayName": "Panadería" }],
"next_page_token": null,
"cached": false
}
Category details (service types, more-hours types)
- Method:
GET - Endpoint:
/api/uploadposts/google-business/categories/batch
| Parameter | Required | Description |
|---|---|---|
names | Yes | 1-100 category ids, comma separated (gcid:bakery,gcid:cafe) or repeated. |
language_code | Yes | BCP 47 language. |
region_code | No | Country code. |
view | No | FULL (default) or BASIC. |
With view=FULL each category carries serviceTypes (the serviceTypeId values for
structured services) and moreHoursTypes (the
hours_type_id values for more_hours in location info).
Chains
GET /api/uploadposts/google-business/chains?name=Mercadona[&page_size=10]— search a chain or brand (page_size1-500). Returnschains.GET /api/uploadposts/google-business/chains/get?chain=chains/...— one chain (chainNames,websites,locationCount).
Use the chain name as parent_chain in location info.
Is the business already on Google?
- Method:
POST - Endpoint:
/api/uploadposts/google-business/google-locations/search
| Name | Type | Required | Description |
|---|---|---|---|
query | string | One of | Free text, like in Maps: "Panadería Sol, Calle Mayor 3, Madrid". |
location | object | One of | A Google Location object with at least title (more precise). |
page_size | integer | No | 1-10 (default 3). |
user | string | No | Profile whose connection is used. |
{
"success": true,
"count": 1,
"google_locations": [
{ "name": "googleLocations/123", "location": { "title": "Panadería Sol", "...": "..." },
"requestAdminRightsUri": "https://business.google.com/..." }
],
"claimed": [true],
"policy_notice": "..."
}
If requestAdminRightsUri is present, someone else manages the listing: open that link to
request access. If not, you can create the location.
Google only allows this search for businesses you work with. Using it for lead generation or
competitive analysis is against Google's policy and gets API access revoked. Google also
limits the number of searches per day: you can run a limited number per day
(429 daily_limit_reached), and when Google's daily limit is used up the API answers
429 google_daily_quota_exhausted until midnight Pacific time.
Recommended locations
- Method:
GET - Endpoint:
/api/uploadposts/google-business/google-locations/recommended?user=X[&account=][&page_size=25][&page_token=]
Locations Google recommends to a personal account or location group (other account types
get an error from Google). Returns google_locations, total_size and next_page_token.
Report a wrong listing
- Method:
POST - Endpoint:
/api/uploadposts/google-business/google-locations/report
| Name | Type | Required | Description |
|---|---|---|---|
google_location | string | Yes | googleLocations/{id} from the search or the recommendations. |
reason_bad_location | string | One of | NOT_A_LOCATION, PERMANENTLY_CLOSED, DOES_NOT_EXIST, SPAM, NOT_A_BUSINESS, MOVED, DUPLICATE. |
reason_bad_recommendation | string | One of | NOT_A_STORE_FRONT, NOT_PART_OF_SUGGESTED_CHAIN, IRRELEVANT. |
elaboration | string | Depends | Up to 512 characters. Required for MOVED (the new address), NOT_PART_OF_SUGGESTED_CHAIN (the right chain) and IRRELEVANT (why). |
language_code | string | No | Language of elaboration. |
location_group | string | No | accounts/{id} of the location group the report is for. |
confirm | boolean | Yes | true: the report is sent to Google from your account. |
Errors
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_region_code / invalid_language_code / invalid_view / invalid_query / invalid_names | A parameter is not valid. |
| 400 | invalid_search / invalid_google_location / invalid_reason / elaboration_required | See the tables above. |
| 400 | confirmation_required | The report needs "confirm": true. |
| 400 | invalid_json | The body is not a valid JSON object. |
| 400 | google_business_not_connected | Connect a Google Business account first. |
| 429 | daily_limit_reached / google_daily_quota_exhausted | Daily limits; see retry_after_seconds. |
| 502 | google_result_unknown | Google did not confirm a report: do not send it again blindly. |
| 503 | google_api_not_enabled / gbp_feature_disabled / gbp_quota_guard_unavailable | Temporarily unavailable; try again later. |