Locations setup

To set up your locations, you need to proceed through the following stages:

Discover locations

Published, verified locations are a canonical feature in Google Search and Maps results. These locations have an existing and verified owner. To change ownership from one Google Account to another, an ownership request is required. Unclaimed locations created by local guides or the user community are considered unverified. Platforms create and verify new locations.

To set up your locations with the Google My Business API, you need to create a platform for your merchants to manage their business on Google. On your platform, you can allow your users to search for listings that match their business name, address, and phone data.

The GoogleLocations API allows you to see in advance whether a location has been previously claimed by another merchant in Google My Business. If the location hasn't been claimed, you can immediately request ownership of that location. Otherwise, you must create and verify a new location.

For additional information, see the Search for matching listings guide.

Location search outcomes

When you search for location listings, you need to complete the following steps to claim a new location:

  1. Collect location data such as the business name, address, and category from the merchant.
  2. Call the googleLocations.search endpoint and provide the location data within the request body of the call. Alternatively, you can search for a query string, similar to what a user enters in Search or Maps. For example, "Starbucks 5th ave NYC" is a query string.
  3. The API returns a list of potential location matches and information about each location, such as the locationName and address of each one.

    When you receive the list returned by the API, you have two options:

    1. If there are no matches, use a blank place ID to create a new location and proceed to verify it.
    2. If there are one or more matches, have the business owner select the closest match.

      If requestAdminRightsUrl exists, the proposed owner must sign in to their Google Account and click the link to initiate the ownership request process.

      If requestAdminRightsUrl is absent, create a new location with the returned place ID and proceed to verify it.

Ownership requests

Merchant trust, explicit communication, and Google Accounts are central to the ownership claim process. Ownership claims may be partially automated, with some steps that require the proposed business owner to leave the platform, sign in to their Google Account, and click buttons or links in Google My Business.

It takes up to seven days to successfully transfer a business. When it's finally transferred, the merchant must sign in and manually complete the ownership claim process.

Existing business owners might reject the request, and proposed owners might fail to act on the notification email from Google. If the ownership claim is rejected, the proposed business owner can manually initiate an appeal.

To minimize drop-off, we recommended that you implement a process to track ownership requests. We suggest that you perform an automated or manual follow-up with the proposed owner 7-10 days after a claim is initiated.

Location ownership process overview

The following diagram shows the location ownership process:

Swimlane diagram of location ownership process.
Figure 1. Location ownership process overview diagram

Duplicates

If you add a location that’s already been verified in Google My Business, it doesn't appear on Google Maps and is marked as a "duplicate location" in your account. Only a single, verified location is permitted. Duplicate locations are unverified and unpublished. There's no need to manually remove duplicates.

Reviews typically are migrated to the newly verified location. See Moving reviews across listings for more information.

Create locations

In Google Maps, places are represented by place IDs, and Google My Business accounts and locations are represented by account IDs and location IDs.

Locations and places

When you create a new location, it becomes associated with a place in Google Maps. This also applies to service area businesses, even though the address isn't publicly visible.

We recommend the following practices when you create locations:

  • Include a place ID only. The API error response specifies if latitude-longitude coordinates are required.
  • If you're a business owner who drives the process, Google Maps JavaScript Places widgets and Geocoding APIs offer the best and most familiar experience for you to drop a pin on a map to precisely locate the business.
  • New developments and high-growth regions might require latitude-longitude coordinates. Normally, Google Maps establishes place IDs, addresses, and latitude-longitude data.

Locations and places have a many-to-many relationship. There can be multiple locations associated with a single place ID. For example, departments within a mall or hospital are multiple locations. Conversely, there can be multiple place IDs associated with a single location. For more information, see Guidelines for representing your business on Google. The guidelines are applicable to all users.

Maps place IDs

Maps place IDs aren't unique and might change over time. For information on how to safely cache, store, and manage Maps place IDs, multiple place IDs, and how to scope them, see the Place IDs guide.

To learn how to create and update floor plans, see the Use indoor maps to view floor plans guide.

OAuth credentials

Wherever possible, use the business owner’s OAuth credentials to create the location. This establishes the owner's Google Account as the primary owner to manage invites and change ownership, but without the use of the owner's name.

API objects and listing status

The API Location object encapsulates all information associated with a location. The LocationState object represents the current state of a location, such as "pending verify," "duplicate," and "published."

For a detailed description of each listing status, see Understand your listing status.

Categories and attributes

When you create or update locations, it's best to query and select from an up-to-date list of categories and attributes. The list of available categories and attributes is subject to change at any time.

Use the categories.list and attributes.list API methods to obtain an accurate update to the date list from Google. Available options are localized and differ between languages and regions. The API uses BCP 47 language codes and ISO 3166-1 alpha-2 country codes to describe languages and regions.

Postal addresses

Addresses must comply with Google My Business regional and language postal address requirements. These requirements are often higher than those in unverified community-sourced businesses found in Google Maps. Local guides and users of Maps and Search can enter business addresses and details for unclaimed locations. This information is often colloquial and in non-standard formats.

This open source project might help your platform meet these requirements.

Merchants, operations teams, and third-parties can help ensure accuracy.

When you call accounts.locations.create with the validateOnly=true parameter set, we recommend that you confirm that the required fields are present and that the postal addresses are properly formatted.

Geocoding

Geocoding converts addresses into geographic coordinates, which you can then use to place markers on a map, or to position the map.

Latitude and longitude coordinates are used to establish physical locations in Maps with geocoding, in places APIs, and are also used with third-party data.

Merchants, operations teams, and third parties can help ensure addresses are accurately linked to a place, which represents a latitude-longitude coordinate pair.

Location updates

Changes to locations come primarily from location owners and managers, but they may also come from the wider internet community, local guides, and Google. How Google sources and displays business information describes how updates are managed, and how they surface in Maps and search results.

Edits are generally accepted but aren't guaranteed. The What happens to your edits and Manage Google updates support pages describe the review and publishing process in more detail.

The accounts.locations.getGoogleUpdated method returns details of Google location edits.

Verify locations

The location verification process publishes a location to Google Maps and Search. Unverified businesses aren't publicly visible. The process positively confirms the identity of the location owner, and it effectively links a Google Account to that location. The owner might be required to enter a PIN code to verify the location.

Platform-based verification

Partner platforms can verify locations without the need for users to exit the platform. The platform queries the available verification methods, such as email, SMS, voice, and postcard, or automatically, and, if necessary, prompts the business owner to choose their preferred method. Google services deliver the PIN verification code to the business owner. If automatic verification is available, the business owner isn't required to perform any steps to successfully verify their business.

The following diagram shows the platform-based verification process:

Swimlane diagram of Platform-based verification overview process.
Figure 2. Platform-based verification overview diagram

Best practices

In some situations, verification can take up to several days to complete. You need to poll for the verification status. If an empty list of verification methods is returned, use retries.

Changes to business names, addresses, and categories can trigger re-verification. Perform these types of edits before you start the verification process.

Follow these best practices to maximize the merchant conversion rates:

  • Measure how frequently each verification method is presented.
  • Measure the drop-off rates across dialogs and steps.
  • Conduct a follow-up with the merchant if the location doesn't become verified.

Chains and brands

Chains and brands operate under different requirements to meet franchise, franchisee, and partner goals. Chains are managed by a dedicated partnership and support team.

For more information on the registration, creation, and verification of chain locations, see the Request bulk verification for 10+ locations guide.

Once verified, published chain locations can be managed with the Google My Business API in the same manner that other locations are managed, with some exceptions. For instance, site managers are treated differently, and they can add themselves to franchise locations. See Owners and managers of listings for more information.

Linking

To make your location findable, you can link it to Google Ads, posts, and reviews.

For information on how to sync your Google My Business account with Google Ads, see the Google Ads Integration guide and the Using the Google My Business API to manage your location extensions post on the Google Ads Developer blog.

For general information, and to learn more about the AdWords API, visit the AdWords API developer site or the Adwords API forum.

The Google My Business location storeCode must match the Ads local product inventory feed value.

Use the following format to construct a Deep link:

https://business.google.com/{edit|posts|reviews}/l/u{location_id}

The Google My Business API returns un-obfuscated account and location IDs. The Google My Business web interface uses a mixture of obfuscated and un-obfuscated IDs.

User login and access restrictions apply. For example, the Google Account user must have owner, or manager, rights to edit a location.

Insights

The API provides you with several location insights and metrics.

For each location, the following metrics are available for you to analyse:

  • The frequency that the resource was shown when the location is searched for directly.
  • The frequency that the resource was shown as a result of a categorical search, such as for a restaurant.
  • How many times that the resource was viewed on Google Search.
  • How many times that the local post was viewed on Google Search.
  • How many times that the resource was viewed on Google Maps.
  • How many times that the website was clicked.
  • How many times that the phone number was clicked.
  • How many times that the driving directions were requested.
  • How many times that the call-to-action button was clicked.
  • The amount of views of photos uploaded by the merchant.
  • The total number of photos that are currently live that were uploaded by the merchant.

For more on location insights, see Retrieve location insights.