Location Extensions

AdWords location extensions show your business address, phone number, and a map marker with your ad text. Location extensions have undergone some major changes since their inception. Until mid-2014, business location information was managed by using the legacy location extensions and CampaignAdExtensionService. After that, locations were managed either through Google My Business and linked to AdWords or created through upgraded manual location extension feeds. Now, manual location extension feeds have been sunsetted and all your business locations should be managed by Google My Business, either through the Google My Business Location Manager or the Google My Business API.

The following guide shows an end-to-end example of how to create business locations using the Google My Business API and how to link them to your ads using the AdWords API.

Location extensions with Google My Business

Google My Business is the central repository for your business locations across all Google products. You don't have to worry about keeping your Google My Business locations and AdWords location extensions in sync. Simply perform a one-time setup of the required feed objects and you're done! AdWords will automatically keep its location extensions synchronized to the latest data from your Google My Business account.

This section guides you through creating business locations programmatically using the Google My Business API and linking them to AdWords by creating the required feed objects. If you want to use the Google My Business Location Manager for creating your locations, skip the following sections and jump right to step 3 in the following process.


If you aren't familiar with the concept of feeds in AdWords, read the feed guide for sitelinks. These instructions build off of that guide.

The steps to create and link business locations are as follows:

  1. Authenticate for Google My Business and AdWords API calls (OAuth 2.0).

  2. Create a new location using the Google My Business API.

    1. Use accounts.list to retrieve the Google My Business accounts that you own or have management rights on.
    2. Select the account to work with (for example, AccountType = BUSINESS).
    3. Create the location and specify a label, address, business hours, etc.
  3. Create a new location extensions feed linked to your Google My Business account.

    1. Set systemFeedGenerationData to a PlacesLocationFeedData object containing information about your Google My Business account.
    2. Set origin to ADWORDS.
    3. Do not specify any feedAttributes. AdWords will create these for you automatically because this is a system-generated feed.
    4. Perform a FeedService.mutate ADD operation.
  4. Associate the feed with the customer.

    1. Use the feedId from step 3.
    2. Use placeholder type 7 for LOCATION.
    3. Use an appropriate matchingFunction.
    4. Perform a CustomerFeedService.mutate ADD operation.
  5. (Optional) Associate the feed to specific campaigns or ad groups.

    1. Use the feedId from step 3.
    2. Use placeholder type 7 for LOCATION.
    3. Use a matchingFunction to filter based on the label from step 2c.
    4. Perform a CampaignFeedService.mutate ADD or AdGroupFeedService.mutate ADD operation.

If you are familiar with feeds for other extensions, you may have noticed that the steps above did not include creating a FeedMapping. Since this feed is a system-generated feed, AdWords already knows how to map the feed's attributes to the placeholder fields for location extensions. There's no need for you to provide that information. The following sections explain how to set the systemFeedGenerationData object when creating a new feed (step 3a). See below for a code example that brings all the pieces together.

Creating the PlacesLocationFeedData object on the feed

Setting the systemFeedGenerationData attribute on your feed tells AdWords to:

  • Link your Google My Business and AdWords accounts.
  • Automatically create feed attributes for your feed.
  • Automatically create a FeedMapping for your feed and the location targeting criterionType (77).
  • (Optional) Limit the set of locations that AdWords syncs from your Google My Business account.

Set the attributes of your PlacesLocationFeedData object as follows:

Attribute Required Description
emailAddress Yes The email address of your Google My Business account owner or one of its managers. This must match the email address provided in oAuthInfo.
oAuthInfo Yes OAuth2 information that grants your AdWords account access to your Google My Business account.
businessAccountIdentifier No The account ID of the managed business whose locations are to be used. If you are using the Google My Business API, you can get this ID from the account_id portion of the name of the Account. Otherwise, you can copy the BUSINESS_ACCOUNT_ID portion from the business URL of the form:
businessNameFilter No Name of the business to sync to AdWords.
categoryFilters No Categories of the listings to sync to AdWords.
labelFilters No Labels of the listings to sync to AdWords.

Creating the OAuthInfo object on the PlacesLocationFeedData

The oAuthInfo attribute on your PlacesLocationFeedData provides the information required to ensure that your AdWords account is allowed to read locations from your Google My Business account.

Set the attributes of your OAuthInfo object as follows:

Attribute Value Description
httpMethod GET or PUT The HTTP method for getting authorization information.
httpRequestUrl https://www.googleapis.com/auth/plus.business.manage The OAuth scope for Google My Business. Always use the value shown here when setting up a Google My Business feed.
httpAuthorizationHeader Bearer OAUTH_ACCESS_TOKEN The authorization header containing the OAuth access token that grants your AdWords account permission to read from your Google My Business account. In place of OAUTH_ACCESS_TOKEN, substitute an access token generated from OAuth credentials for the emailAddress of the PlacesLocationFeedData and a scope matching httpRequestUrl.

Complete code example

The following code uses the Java client libraries for both the Google My Business API and the AdWords API. Refer to the respective instructions for setting up for your particular language.

Step 1: Authenticate for Google My Business and AdWords API calls (OAuth 2.0)

// Creating the default factory and transport (used later)
JsonFactory jsonFactory = JacksonFactory.getDefaultInstance();
HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

// Load the credentials from the ads.properties file.
// Please note: This example assumes that your AdWords and MyBusiness accounts
// are linked to the same Google account, and that both scopes were used when
// generating the refresh token:
// - https://www.googleapis.com/auth/adwords
// - https://www.googleapis.com/auth/plus.business.manage
// If you are using different Google accounts, you must authenticate
// separately and maintain two credentials (see
// /my-business/content/set-up-java-client).
Credential credential =
    new OfflineCredentials.Builder()

Step 2: Create a new location using the Google My Business API

// Initialize GMB.
Mybusiness gmb =
    new Mybusiness.Builder(httpTransport, jsonFactory, credential)
// Get list of GMB accounts (2a).
Mybusiness.Accounts.List listAccounts = gmb.accounts().list();
ListAccountsResponse response = listAccounts.execute();
List<Account> accounts = response.getAccounts();

// Find the account to work with (2b). The first BUSINESS account is used
// here, but you can use any other account as well (e.g., PERSONAL).
Account mainAccount = null;
for (Account account : accounts) {
  if (account.getType().equalsIgnoreCase("BUSINESS")) {
    mainAccount = account;
if (mainAccount == null) {
  throw new RuntimeException("Main GMB account not found");
// Create the location (2c).
Location location = new Location();
location.setLocationName("My Company");
location.setPrimaryCategory(new Category().setName("Software Company"));
// Create an address.
Address address = new Address();
List<String> addressLines = new ArrayList<String>();
addressLines.add("1600 Amphitheatre Pkwy");
address.setLocality("Mountain View");
// Create business hours (optional).
BusinessHours businessHours = new BusinessHours();
List<TimePeriod> periods = new ArrayList<TimePeriod>();
List<String> days =
    Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");
for (String day : days) {
  TimePeriod period = new TimePeriod();

// Assign a label to the location (optional). This example uses the AdWords
// customer ID as a label to associate the location with an ad group in AdWords.
// You can use any label value to identify locations, or no label at all
// (e.g., filter by business name or category).
CreateLocationRequest createLocationRequest = new CreateLocationRequest();
// Use a random request ID.
Mybusiness.Accounts.Locations.Create createLocation =
Location createdLocation = createLocation.execute();

Step 3: Creating a new feed linked to your Google My Business

// Initialize AdWords.
AdWordsSession session = new AdWordsSession.Builder()
AdWordsServices services = new AdWordsServices();
FeedServiceInterface feedService =
    services.get(session, FeedServiceInterface.class);
// Create the feed object.
Feed gmbFeed = new Feed();
gmbFeed.setName("GMB feed #" + System.currentTimeMillis());
// Create the PlacesLocationFeedData object (3a).
PlacesLocationFeedData feedData = new PlacesLocationFeedData();
OAuthInfo oAuthInfo = new OAuthInfo();
    String.format("Bearer %s", credential.getAccessToken()));
// Since this feed's feed items will be managed by AdWords,
// you must set its origin to ADWORDS (3b).
// Note: No feed attributes for the feed were specified, as this is a
// system-generated feed (3c).
// Create an operation to add the feed.
FeedOperation feedOperation = new FeedOperation();
// Add the feed (3d).
FeedReturnValue addFeedResult = feedService.mutate(
    new FeedOperation[] {feedOperation});
Feed createdFeed = addFeedResult.getValue(0);

Step 4: Associate the feed to the customer

CustomerFeedServiceInterface customerFeedService =
    services.get(session, CustomerFeedServiceInterface.class);
CustomerFeed customerFeed = new CustomerFeed();
// Set feedId and placeholder type (4a + 4b).
customerFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_LOCATION});
// Create a matching function that will always evaluate to true (4c).
Function customerMatchingFunction = new Function();
ConstantOperand constOperand = new ConstantOperand();
    new FunctionArgumentOperand[] {constOperand});
// Create an operation to add the customer feed.
CustomerFeedOperation customerFeedOperation = new CustomerFeedOperation();
// Add the feed (4d).
CustomerFeedReturnValue customerFeedResult = customerFeedService.mutate(
    new CustomerFeedOperation[] {customerFeedOperation});
CustomerFeed createdCustomerFeed = customerFeedResult.getValue(0);

Step 5: Associate the feed to specific ad groups (similar for campaigns)

AdGroupFeedServiceInterface adgroupFeedService =
    services.get(session, AdGroupFeedServiceInterface.class);
// Create the ad group feed.
AdGroupFeed adgroupFeed = new AdGroupFeed();
// Set feedId and placeholder type (5a + 5b).
adgroupFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_LOCATION});
// Define matching function based on the label (5c).
Function matchingFunction = new Function();
String matchingFunctionString = String.format(
    "EQUALS(FeedAttribute[%d, 14], \"%s\")",
// Create an operation to add the ad group feed.
AdGroupFeedOperation operation = new AdGroupFeedOperation();
// Add the feed (5d).
AdGroupFeedReturnValue result = adgroupFeedService.mutate(
    new AdGroupFeedOperation[]{operation});
AdGroupFeed createdAdGroupFeed = result.getValue(0);

Filtering location extensions

Location extensions are automatically applied to every campaign and ad group under the account. You can apply location extensions to a specific ad group or campaign through filters.

Filtering strategies

Location extensions let you define location filters at several levels of your account using various mechanisms. Use the matchingFunction of a CampaignFeed or AdGroupFeed if you want different locations to appear on ads for different campaigns or ad groups.

The most specific filter takes precedence. For example, let's say you have:

  • a CustomerFeed
  • a CampaignFeed for campaign A
  • an AdGroupFeed for ad group G in campaign A
  • another campaign B that has neither a CampaignFeed nor an AdGroupFeed

With this setup you will get the following behavior (the dotted lines show which matching function is used for which ad):

  • Ads serving for ad group G will only show location extensions for items that match the AdGroupFeed's matching function.
  • Ads serving for all other ad groups in campaign A will only show location extensions for items that match the CampaignFeed's matching function.
  • Ads serving for campaign B will show location extensions for items that match the CustomerFeed's matching function.

Using attributes for filtering

Filters in feed objects limit the feed items that sync via the businessNameFilter, categoryFilters, or labelFilters attributes of the PlacesLocationFeedData object. In addition, filters in the other objects determine which feed items in AdWords will be used as location extensions for a given combination of customer, campaign, and ad group. You might use these filters if:

  • You are using the same Google My Business account with multiple AdWords accounts and each AdWords account is logically associated with a subset of locations.
  • You have locations in your Google My Business account that you don't ever want to show up in ads.

For an account, campaign, or ad group, you can specify matchingFunctions for filtering based on any of the attributes available in the location extensions feed. We recommend filtering based on the following attributes:

  • Labels (Placeholder 14): By specifying labels for each location in Google My Business and using these labels for filtering in AdWords, you can customize your filtering entirely. For example, you can use the customer ID or a unique ID generated by your application.

    If labelFilters is specified, only listings that have any of the specified labels are candidates to be synchronized into FeedItems. If labelFilters has no entries, then all listings are candidates for syncing. In addition, all labels of a Google My Business listing are synced to a feed attribute with feedAttributeId = 14 and type = STRING_LIST. You can filter for feed items that have one or more labels by specifying a condition in your matching function as follows:

  • Business name (Placeholder 1): You can use the business name of the location for granular filtering.

  • Business category (Placeholder 9): Filtering by categories allows you to define broader matches or resolve ambiguity when AND-combined with business name.

Automatic removal of invalid filters

AdWords will perform a daily check of the filters defined for your location extensions. If it determines that no Google My Business locations are matching the filter, it will take the following steps to remove the filter:

Filter location Steps to remove filter
PlacesLocationFeedData Set the following attributes of the PlacesLocationFeedData to null:
  • businessNameFilter
  • categoryFilters
  • labelFilters
CampaignFeed Remove the CampaignFeed.
AdGroupFeed Remove the AdGroupFeed.

Next steps

See the matching functions guide to learn more about filtering by feed attribute ID, and the sitelinks feed guide for examples of how to create ad group and campaign feeds.

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.