Skip to main content

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. user is 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": true in the answer).

Search categories​

  • Method: GET
  • Endpoint: /api/uploadposts/google-business/categories
ParameterRequiredDescription
region_codeYesISO 3166-1 alpha-2 country code, e.g. ES.
language_codeYesBCP 47 language, e.g. es.
queryNoText to search in the category name (max 100 characters), e.g. bakery.
viewNoBASIC (default) or FULL (adds serviceTypes and moreHoursTypes).
page_size / page_tokenNo1-100 (default 100) / next_page_token of the previous page.
userNoProfile 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
ParameterRequiredDescription
namesYes1-100 category ids, comma separated (gcid:bakery,gcid:cafe) or repeated.
language_codeYesBCP 47 language.
region_codeNoCountry code.
viewNoFULL (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_size 1-500). Returns chains.
  • 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
NameTypeRequiredDescription
querystringOne ofFree text, like in Maps: "Panadería Sol, Calle Mayor 3, Madrid".
locationobjectOne ofA Google Location object with at least title (more precise).
page_sizeintegerNo1-10 (default 3).
userstringNoProfile 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's usage policy

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.

  • 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
NameTypeRequiredDescription
google_locationstringYesgoogleLocations/{id} from the search or the recommendations.
reason_bad_locationstringOne ofNOT_A_LOCATION, PERMANENTLY_CLOSED, DOES_NOT_EXIST, SPAM, NOT_A_BUSINESS, MOVED, DUPLICATE.
reason_bad_recommendationstringOne ofNOT_A_STORE_FRONT, NOT_PART_OF_SUGGESTED_CHAIN, IRRELEVANT.
elaborationstringDependsUp to 512 characters. Required for MOVED (the new address), NOT_PART_OF_SUGGESTED_CHAIN (the right chain) and IRRELEVANT (why).
language_codestringNoLanguage of elaboration.
location_groupstringNoaccounts/{id} of the location group the report is for.
confirmbooleanYestrue: the report is sent to Google from your account.

Errors​

StatuscodeMeaning
400invalid_region_code / invalid_language_code / invalid_view / invalid_query / invalid_namesA parameter is not valid.
400invalid_search / invalid_google_location / invalid_reason / elaboration_requiredSee the tables above.
400confirmation_requiredThe report needs "confirm": true.
400invalid_jsonThe body is not a valid JSON object.
400google_business_not_connectedConnect a Google Business account first.
429daily_limit_reached / google_daily_quota_exhaustedDaily limits; see retry_after_seconds.
502google_result_unknownGoogle did not confirm a report: do not send it again blindly.
503google_api_not_enabled / gbp_feature_disabled / gbp_quota_guard_unavailableTemporarily unavailable; try again later.