Work with Location Data

You can use the Google My Business API to create and edit locations in Google My Business. These locations can be used in Ads but need to be verified to be eligible to appear on Search and Maps. Note that verification of locations is not supported via the API.

In the Google My Business API, location data is represented by the v3.accounts.locations collection. You can perform the following operations on location data:

Batch get

Retrieves a collection of specified accounts.locations for a given account.

accounts.locations.batchGet

HTTP

To get a collection of locations, send a POST request using a URL and request body of the following form:

https://mybusiness.googleapis.com/v3/accounts/account_name/locations:batchGet

{
  "locationNames": [
    "accounts/account_name/locations/locationId",
    "accounts/account_name/locations/locationId",
  ],
}
Java

This function takes an ArrayList<String> of location names, and returns a GetLocationsResponse instance, from which you can get the list of accounts.locations.

/*
 * Returns the specified locations for a given account.
 * @param accountName Name (resource path) of the account to get locations from.
 * @param nameList List of location names to return.
 * @return GetLocationsRequest Data model class containing results.
 * @throws IOException.
 */
private static List batchGetLocations(String accountName, ArrayList nameList) throws IOException {
  GetLocationsRequest getLocationsRequest = new GetLocationsRequest();
  getLocationsRequest.setLocationNames(nameList);

  Mybusiness.Accounts.Locations.BatchGet locations =
      mybusiness.accounts().locations().batchGet(accountName, getLocationsRequest);

  GetLocationsResponse response = locations.execute();

  return response.getLocations();
}

You can access field data for the location instance (represented by the variable response in this example) through the following methods:

  • getAdditionalCategories()
  • getAddress()
  • getBusinessHours()
  • getLabels()
  • getLocationKey()
  • getLocationName()
  • getName()
  • getPrimaryCategory()
  • getPrimaryPhone()
  • getServiceArea()
  • getStoreCode()
  • getWebsiteUrl()

Create a location

Creates a new location under the specified account.

Note: The Google My Business API shares the same list of required fields as the Google My Business UI.

accounts.locations.create

HTTP

To create a new location, send a POST request using a URL and request body of the following form:

https://mybusiness.googleapis.com/v3/accounts/account_name/locations?languageCode=language&validateOnly=True|False

{
    "storeCode": "GOOG-SYD",
    "locationName": "Google Sydney",
    "primaryPhone": "02 9374 4000",
    "address": {
      "addressLines": [
        "Level 5",
        "48 Pirrama Road",
      ],
      "locality": "Pyrmont",
      "postalCode": "2009",
      "administrativeArea": "NSW",
      "country": "AU",
    },
    "websiteUrl": "https://www.google.com.au/",
    "businessHours": {
      "periods": [
        {
          "openDay": "MONDAY",
          "closeDay": "MONDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "MONDAY",
          "closeDay": "MONDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "TUESDAY",
          "closeDay": "TUESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "TUESDAY",
          "closeDay": "TUESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "WEDNESDAY",
          "closeDay": "WEDNESDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "THURSDAY",
          "closeDay": "THURSDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
        {
          "openDay": "FRIDAY",
          "closeDay": "FRIDAY",
          "openTime": "09:00",
          "closeTime": "17:00"
        },
      ]
    },
    "primaryCategory": {
      "categoryId": "gcid:software_company"
    }
}
Java

This function creates a new example location for Google Sydney.

/**
 * Creates a new location.
 * @param accountName The name (resource path) of the account to create a
 *   location for.
 * @return Location The data for the new location.
 * @throws Exception
 */

public static Location createLocation(String accountName) throws Exception {
    System.out.println("Creating Location");

    // Street address
    List addressLines = new ArrayList();
    addressLines.add("Level 5, 48 Pirrama Road");
    Address address = new Address()
        .setAddressLines(addressLines)
        .setLocality("Pyrmont")
        .setAdministrativeArea("NSW")
        .setCountry("AU")
        .setPostalCode("2009");

    // Business hours
    List periods = new ArrayList<>();
    List days = Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");

    for (String day : days) {
      TimePeriod period = new TimePeriod()
          .setOpenDay(day)
          .setOpenTime("9:00")
          .setCloseTime("17:00")
          .setCloseDay(day);
      periods.add(period);
    }
    BusinessHours businessHours = new BusinessHours()
        .setPeriods(periods);
    Location location = new Location()
        .setAddress(address)
        .setRegularHours(businessHours)
        .setLocationName("Google Sydney")
        .setStoreCode("GOOG-SYD")
        .setPrimaryPhone("02 9374 4000")
        .setPrimaryCategory(new Category().setName("Software Company"))
        .setWebsiteUrl("https://www.google.com.au/");

    Mybusiness.Accounts.Locations.Create createLocation =
        mybusiness.accounts().locations().create(accountName, location);
    createLocation.setRequestId("1a84939c-ab7d-4581-8930-ee35af6fefac");
    createLocation.setLanguageCode("en-AU");

    Location createdLocation = createLocation.execute();

    System.out.printf("Created Location:\n%s", createdLocation);
    return createdLocation;
  }

Delete a location

Deletes the specified location.

accounts.locations.delete

HTTP

To delete a location, send a DELETE request using a URL of the following form:

https://mybusiness.googleapis.com/v3/accounts/account_name/locations/locationId
Java

This function uses accounts.locations.delete to delete the specified location.

/**
 * Deletes the specified location.
 * @param locationName The name (resource path) of the location to delete.
 * @throws Exception
 */
public static void deleteLocation(String locationName) throws Exception {
  Location location = new Location();
  location.setName(locationName);
  Mybusiness.Accounts.Locations.Delete deleteLocation =
    mybusiness.accounts().locations().delete(locationName);
  deleteLocation.execute();
}

Get a location by name

Gets the specified location.

accounts.locations.get

HTTP

To request a location by name, send a GET request using an HTTP URL of the following form:

https://mybusiness.googleapis.com/v3/accounts/account_name/locations/locationId
Java

This function takes a list of locations and returns the data for the specified account if it exists.

/*
 * Returns the specified location
 * @param locationName The name (resource path) of the location to retrieve.
 * @returns Location The requested location.
 */
private static Location getLocationByName(String locationName) throws IOException {
    Mybusiness.Accounts.Locations.Get location =
        mybusiness.accounts().locations().get(locationName);

    Location response = location.execute();
    return response;
}

You can access field data for the location instance (represented by the variable response in this example) through the following methods:

  • getAdditionalCategories()
  • getAddress()
  • getBusinessHours()
  • getLabels()
  • getLocationKey()
  • getLocationName()
  • getName()
  • getPrimaryCategory()
  • getPrimaryPhone()
  • getServiceArea()
  • getStoreCode()
  • getWebsiteUrl()

You can return the Google Maps version of a location by appending googleUpdated to the request URL as shown here:

https://mybusiness.googleapis.com/v3/accounts/123456789/locations/012345678:googleUpdated

If there are no results, a full version of the location will be returned.

List all locations

Lists all of the locations for the specified account.

accounts.locations.list

HTTP

To list all of the locations for an account, send a GET request using a URL of the following form:

https://mybusiness.googleapis.com/v3/accounts/account_name/locations
Java

This function returns a list of locations for the specified account.

/*
 * Returns all locations for the specified account.
 * @param accountName The account for which to return locations.
 * @returns List A list of all locations for the specified account.
 */
public static List listLocations(String accountName) throws Exception {
  Mybusiness.Accounts.Locations.List locationsList =
      mybusiness.accounts().locations().list(accountName);
  ListLocationsResponse response = locationsList.execute();
  List locations = response.getLocations();

  if (locations != null) {
    for (Location location : locations) {
      System.out.println(location.toPrettyString());
    }
  } else {
    System.out.printf("Account '%s' has no locations.", accountName);
  }
  return locations;
}

Filter results when listing locations

You can use filters to limit the results that are returned when calling accounts.locations.list. To filter a request, append a filter expression to the base URL as shown in this example:

https://mybusiness.googleapis.com/v3/accounts/0123456789/locations?filter=location.locationName=%22Best+Buy%22

Filter expressions are made up of one or more restrictions which can be combined by AND or OR logical operators. A sequence of restrictions implicitly uses AND. A restriction has the form of <field> <operator> <value>, where the operator is either EQUALS (=) or HAS (:). You can use the HAS (:) operator for repeated fields (for example location.labels:"newly open"), otherwise it is equivalent to EQUALS.

The following example shows a filter expression that returns all locations with the name "Pepé Le Pew", with a category of either "french_restaurant" or "european_restaurant", and a label of "newly open".

location.locationName=%22Pepé+Le+Pew%22+AND+
(location.categories=%22gcid:french_restaurant%22+OR+
location.categories=%22gcid:european_restaurant%22)+AND+
location.labels:%22newly open%22

You can add restrictions using the following fields:

  • location.locationName
  • location.labels
  • location.categories (combines the primaryCategory and additionalCategories fields)
  • location_state.is_suspended
  • location_state.is_duplicate
  • location_state.is_google_updated

Spaces and quote marks must be encoded as follows:

  • Encode quote marks by using "%22".
  • Encode spaces by using a plus sign ("+").

Patch a location

Updates one or more fields for the specified location.

accounts.locations.patch

HTTP

To update a location, send a PATCH request using a URL and request body of the following form:

https://mybusiness.googleapis.com/v3/accounts/account_name/locations/locationId?languageCode=language&validateOnly=True|False&fieldMask=field1,field2,etc.

{
    "locationName": "Google Shoes",
    "primaryPhone": "(212) 553-5558",
}

Enter the fields and updated values under location, and enter a comma-separated list of updated fields as the value for fieldMask.

Java

This function updates the locationName field for a location.

/**
 * Updates the specified fields in the specified location.
 * @param phone A string value for the location's primary phone.
 * @param name The name (resource path) for the location to update.
 * @throws Exception
 */
public static void updateLocation(String phone, String name) throws Exception {
    Location location = new Location()
        .setPrimaryPhone(phone);

    Mybusiness.Accounts.Locations.Patch updateLocation =
        mybusiness.accounts().locations().patch(name, location);
    updateLocation.setFieldMask("primary_phone");
    updateLocation.setLanguageCode("en-AU");
    Location updatedLocation = updateLocation.execute();

    System.out.printf("Updated Location:\n%s", updatedLocation);
  }

Send feedback about...

Google My Business API
Google My Business API
Need help? Visit our support page.