Google Ads

Introduction to Feeds Services  |  AdWords API  |  Google Developers

This guide is an introduction to feeds, which offer a generic and flexible
way for you to provide and use tabular data in an Google Ads account. Some
examples of Google Ads features that use tabular data are ad extensions, ad
customizers, and dynamic remarketing. This guide uses sitelink extensions as a
running example to explain how to use feeds services, but the process is
analogous for other types of tabular data by using different placeholder types.

This guide uses Java for the code samples. For code examples in other
programming languages, see Code examples.

Customer scenario

Suppose you’re an advertiser using Google Ads to drive traffic to your site.
You wish to have your ads appear with sitelinks so users can get to sections of
your site more quickly.

Here are some of the details for the sitelinks you want to show under your
ads:

Sitelink name Sitelink Final URLs
Home Page http://www.example.com
Store Locator http://www.example.com/locations
Sale Items http://www.example.com/discounts
Support http://www.example.com/support
Products http://www.example.com/prods
About Us http://www.example.com/about

Notice that the data is tabular—each column is a sitelink property, and
each row provides values for one sitelink.

Feeds services

There are several inter-related services you use to create and manage
feeds.

FeedService
This service is used to describe to Google Ads the shape of your tabular data:
a name or title for your feed (table) as well as its column names and
types.
FeedItemService
This service is used to populate your feed with data. Each feed item
represents a row in the table.
FeedMappingService
This service is used to specify how the feed maps the columns of your table
to the fields of a particular Google Ads feature. This guide shows how to map a
feed to be used for sitelinks.
CustomerFeedService
This service enables your feed across a customer’s entire account (all
campaigns and ad groups).
CampaignFeedService
This service enables your feed across an entire campaign (all ad groups
within that campaign).
AdGroupFeedService
This service enables your feed for a particular ad group.

Java code example

The code example below demonstrates how to add a sitelinks feed and
associate it with a campaign using the Java client library. For the
complete code example, see Code examples.

Adding sitelinks to a campaign consists of the following steps:

  1. Create the feed.
  2. Populate the feed.
  3. Map the feed to the sitelinks placeholder fields.
  4. Associate the feed to a customer, campaign, or ad group.
  5. Schedule when feed items should be enabled (optional).
  6. Target specific campaigns, ad groups, or criteria (optional).

1. Create the feed

Use FeedService to describe the shape of the data to be uploaded. This
consists of a name or title for the feed (table) and a set of feed attributes
(columns). Each feed attribute has a name (column header) and a type.

In the sample code, createSiteLinksFeed() uses FeedService to
create a Feed with FeedAttribute instances
appropriate to sitelinks:

private static void createSiteLinksFeed(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    SiteLinksDataHolder siteLinksData,
    String feedName)
    throws RemoteException {
  // Get the FeedService.
  FeedServiceInterface feedService = adWordsServices.get(session, FeedServiceInterface.class);

  // Create attributes.
  FeedAttribute textAttribute = new FeedAttribute();
  textAttribute.setType(FeedAttributeType.STRING);
  textAttribute.setName("Link Text");
  FeedAttribute finalUrlAttribute = new FeedAttribute();
  finalUrlAttribute.setType(FeedAttributeType.URL_LIST);
  finalUrlAttribute.setName("Link Final URLs");
  FeedAttribute line2Attribute = new FeedAttribute();
  line2Attribute.setType(FeedAttributeType.STRING);
  line2Attribute.setName("Line 2");
  FeedAttribute line3Attribute = new FeedAttribute();
  line3Attribute.setType(FeedAttributeType.STRING);
  line3Attribute.setName("Line 3");

  // Create the feed.
  Feed siteLinksFeed = new Feed();
  siteLinksFeed.setName(feedName);
  siteLinksFeed.setAttributes(
      new FeedAttribute[] {textAttribute, finalUrlAttribute, line2Attribute, line3Attribute});
  siteLinksFeed.setOrigin(FeedOrigin.USER);

  // Create operation.
  FeedOperation operation = new FeedOperation();
  operation.setOperand(siteLinksFeed);
  operation.setOperator(Operator.ADD);

  // Add the feed.
  FeedReturnValue result = feedService.mutate(new FeedOperation[] {operation});

  Feed savedFeed = result.getValue()[0];
  siteLinksData.siteLinksFeedId = savedFeed.getId();
  FeedAttribute[] savedAttributes = savedFeed.getAttributes();
  siteLinksData.linkTextFeedAttributeId = savedAttributes[0].getId();
  siteLinksData.linkFinalUrlFeedAttributeId = savedAttributes[1].getId();
  siteLinksData.line2FeedAttributeId = savedAttributes[2].getId();
  siteLinksData.line3FeedAttributeId = savedAttributes[3].getId();
  System.out.printf("Feed with name '%s' and ID %d with linkTextAttributeId %d"
      + " and linkFinalUrlAttributeId %d and line2AttributeId %d"
      + " and line3AttributeId %d was created.%n",
      savedFeed.getName(),
      savedFeed.getId(),
      savedAttributes[0].getId(),
      savedAttributes[1].getId(),
      savedAttributes[2].getId(),
      savedAttributes[3].getId());
}

In order to describe the tabular data that will be used for sitelinks, the
method creates a feed with the following feed attributes:

  • Link Text
  • Link Final URLs
  • Line 1
  • Line 2
  • Line 3

We set a feed name and a feed origin of FeedOrigin.USER to
signify that its feed items will be populated by the advertiser (as opposed to
Google Ads).

A mutate operation is called on FeedService to create the feed. Upon
successfully adding the feed, FeedService returns the feed ID as well as all
the feed attribute IDs. It’s important to store these IDs for use with other
services later. For simplicity, our example supposes that an object called
siteLinksData of type SiteLinksDataHolder has been
created and has the appropriate fields to hold the IDs. We will use this object
in subsequent steps to retrieve the IDs. You can create a similar object in
your implementation language.

Note that our feed has exactly the number of columns needed for sitelinks.
However, as we’ll see later, you can also create a feed with more
columns than needed by the Google Ads feature. One reason to do this is to
use the values in the extra columns to filter which feed items (rows) apply to
which campaign or ad group using a matching function.

2. Populate the feed

Now that the shape of the data has been described to Google Ads, the sitelink
data can be populated by adding feed items (rows) using FeedItemService.

We start with a helper method,
newSiteLinkFeedItemAddOperation(), to construct feed items. This
helper method takes information about a sitelink and the IDs of our feed
attributes to populate a new feed item. The new feed item is then wrapped
within an ADD operation and returned.

To understand how to construct a FeedItem, keep in mind this
way of characterizing a table: each row is a set of cells, and each cell is
located in a particular column and contains some content. Analogously, a
FeedItem (row) is a set of FeedItemAttributeValue
instances (cells), and each FeedItemAttributeValue (cell) has the
ID of a FeedAttribute (the column in which the cell is located)
and a stringValue (the cell’s content, if a string).

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line2, String line3) {
  return newSiteLinkFeedItemAddOperation(siteLinksData, text, finalUrl, line2, line3, false);
}

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line2, String line3,
    boolean restrictToLop) {
  // Create the FeedItemAttributeValues for our text values.
  FeedItemAttributeValue linkTextAttributeValue = new FeedItemAttributeValue();
  linkTextAttributeValue.setFeedAttributeId(siteLinksData.linkTextFeedAttributeId);
  linkTextAttributeValue.setStringValue(text);
  FeedItemAttributeValue linkFinalUrlAttributeValue = new FeedItemAttributeValue();
  linkFinalUrlAttributeValue.setFeedAttributeId(siteLinksData.linkFinalUrlFeedAttributeId);
  linkFinalUrlAttributeValue.setStringValues(new String[] {finalUrl});
  FeedItemAttributeValue line2TextAttributeValue = new FeedItemAttributeValue();
  line2TextAttributeValue.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2TextAttributeValue.setStringValue(line2);
  FeedItemAttributeValue line3TextAttributeValue = new FeedItemAttributeValue();
  line3TextAttributeValue.setFeedAttributeId(siteLinksData.line3FeedAttributeId);
  line3TextAttributeValue.setStringValue(line3);

  // Create the feed item and operation.
  FeedItem item = new FeedItem();
  item.setFeedId(siteLinksData.siteLinksFeedId);
  item.setAttributeValues(new FeedItemAttributeValue[] {linkTextAttributeValue,
      linkFinalUrlAttributeValue, line2TextAttributeValue, line3TextAttributeValue});

  // OPTIONAL: Restrict targeting only to people physically within the location.
  if (restrictToLop) {
    FeedItemGeoRestriction geoTargetingRestriction = new FeedItemGeoRestriction();
    geoTargetingRestriction.setGeoRestriction(GeoRestriction.LOCATION_OF_PRESENCE);
    item.setGeoTargetingRestriction(geoTargetingRestriction);
  }

  // Optional: use item.setStartTime() and item.setEndTime() to specify the
  // time period for the feed to deliver.  The example below will make the feed
  // start now and stop in one month.
  // Make sure you specify the DateTime in the customer's time zone.  You can
  // retrieve this from customer.getDateTimeZone().
  //   item.setStartTime(new DateTime(customerTimeZone).toString("yyyyMMdd HHmmss"));
  //   item.setEndTime(new DateTime(customerTimeZone).plusMonths(1).toString("yyyyMMdd HHmmss"));

  // Optional: use item.setScheduling() to specify time and days of the week for feed to deliver.
  FeedItemOperation operation = new FeedItemOperation();
  operation.setOperand(item);
  operation.setOperator(Operator.ADD);
  return operation;
}

Next, we define the method createSiteLinksFeedItems() that
creates all of the feed items and the feed item operations containing them,
invoking our helper method with different information for each sitelink we want
to create.

The feed items returned by the mutate call include IDs which we store in
siteLinksData for later use. (Again, we suppose that this object
has already been created and has the appropriate fields to hold the IDs.)

private static void createSiteLinksFeedItems(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws RemoteException {
  // Get the FeedItemService.
  FeedItemServiceInterface feedItemService =
      adWordsServices.get(session, FeedItemServiceInterface.class);

  // Create operations to add FeedItems.
  FeedItemOperation home = newSiteLinkFeedItemAddOperation(siteLinksData, "Home",
      "http://www.example.com", "Home line 2", "Home line 3");
  FeedItemOperation stores = newSiteLinkFeedItemAddOperation(siteLinksData, "Stores",
      "http://www.example.com/stores", "Stores line 2", "Stores line 3");
  FeedItemOperation onSale = newSiteLinkFeedItemAddOperation(siteLinksData, "On Sale",
      "http://www.example.com/sale", "On Sale line 2", "On Sale line 3");
  FeedItemOperation support = newSiteLinkFeedItemAddOperation(siteLinksData, "Support",
      "http://www.example.com/support", "Support line 2", "Support line 3");
  FeedItemOperation products = newSiteLinkFeedItemAddOperation(siteLinksData, "Products",
      "http://www.example.com/prods", "Products line 2", "Products line 3");
  // This site link is using geographical targeting to use LOCATION_OF_PRESENCE.
  FeedItemOperation aboutUs = newSiteLinkFeedItemAddOperation(siteLinksData, "About Us",
      "http://www.example.com/about", "About Us line 2", "About Us line 3", true);

  FeedItemOperation[] operations =
      new FeedItemOperation[] {home, stores, onSale, support, products, aboutUs};

  FeedItemReturnValue result = feedItemService.mutate(operations);
  for (FeedItem item : result.getValue()) {
    System.out.printf("FeedItem with feedItemId %d was added.%n", item.getFeedItemId());
    siteLinksData.siteLinkFeedItemIds.add(item.getFeedItemId());
  }

  // Target the "aboutUs" sitelink to geographically target California.
  // See https://developers.google.com/adwords/api/docs/appendix/geotargeting for
  // location criteria for supported locations.
  restrictFeedItemToGeoTarget(adWordsServices, session, result.getValue(5), 21137L);
}

3. Map to placeholders

For each supported Google Ads features that uses tabular data, there is a placeholder type specifying
the fields and data types required by that feature. FeedMappingService is used
to map a feed to a placeholder type, indicating how the feed is to be used, and
to map some feed attributes (columns) to the placeholder’s fields, indicating
how those feed attributes are to be interpreted for this Google Ads feature.

// See the Placeholder reference page for a list of all the placeholder types and fields.
// https://developers.google.com/adwords/api/docs/appendix/placeholders
private static final int PLACEHOLDER_SITELINKS = 1;

// See the Placeholder reference page for a list of all the placeholder types and fields.
// https://developers.google.com/adwords/api/docs/appendix/placeholders
private static final int PLACEHOLDER_FIELD_SITELINK_LINK_TEXT = 1;
private static final int PLACEHOLDER_FIELD_SITELINK_FINAL_URL = 5;
private static final int PLACEHOLDER_FIELD_LINE_2_TEXT = 3;
private static final int PLACEHOLDER_FIELD_LINE_3_TEXT = 4;

private static void createSiteLinksFeedMapping(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData) throws RemoteException {
  // Get the FeedItemService.
  FeedMappingServiceInterface feedMappingService =
      adWordsServices.get(session, FeedMappingServiceInterface.class);

  // Map the FeedAttributeIds to the fieldId constants.
  AttributeFieldMapping linkTextFieldMapping = new AttributeFieldMapping();
  linkTextFieldMapping.setFeedAttributeId(siteLinksData.linkTextFeedAttributeId);
  linkTextFieldMapping.setFieldId(PLACEHOLDER_FIELD_SITELINK_LINK_TEXT);
  AttributeFieldMapping linkFinalUrlFieldMapping = new AttributeFieldMapping();
  linkFinalUrlFieldMapping.setFeedAttributeId(siteLinksData.linkFinalUrlFeedAttributeId);
  linkFinalUrlFieldMapping.setFieldId(PLACEHOLDER_FIELD_SITELINK_FINAL_URL);
  AttributeFieldMapping line2FieldMapping = new AttributeFieldMapping();
  line2FieldMapping.setFeedAttributeId(siteLinksData.line2FeedAttributeId);
  line2FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_2_TEXT);
  AttributeFieldMapping line3FieldMapping = new AttributeFieldMapping();
  line3FieldMapping.setFeedAttributeId(siteLinksData.line3FeedAttributeId);
  line3FieldMapping.setFieldId(PLACEHOLDER_FIELD_LINE_3_TEXT);


  // Create the FeedMapping and operation.
  FeedMapping feedMapping = new FeedMapping();
  feedMapping.setPlaceholderType(PLACEHOLDER_SITELINKS);
  feedMapping.setFeedId(siteLinksData.siteLinksFeedId);
  feedMapping.setAttributeFieldMappings(new AttributeFieldMapping[] {linkTextFieldMapping,
      linkFinalUrlFieldMapping, line2FieldMapping, line3FieldMapping});
  FeedMappingOperation operation = new FeedMappingOperation();
  operation.setOperand(feedMapping);
  operation.setOperator(Operator.ADD);

  // Save the field mapping.
  FeedMappingReturnValue result =
      feedMappingService.mutate(new FeedMappingOperation[] {operation});
  for (FeedMapping savedFeedMapping : result.getValue()) {
    System.out.printf(
        "Feed mapping with ID %d and placeholderType %d was saved for feed with ID %d.%n",
        savedFeedMapping.getFeedMappingId(), savedFeedMapping.getPlaceholderType(),
        savedFeedMapping.getFeedId());
  }
}

In this example, the method configures the feed to be used for sitelinks. It
does this by setting a placeholder type on the FeedMapping to the
constant PLACEHOLDER_SITELINKS. The value for this constant is
1. The method also maps the feed attributes to the placeholder
fields that are needed for sitelinks. This mapping tells Google Ads which feed
attributes (columns) correspond to which aspects of sitelinks.

Not all feed attributes have to be mapped to a placeholder field. As noted
earlier, a feed can have more feed attributes than the Google Ads feature
requires. Those extra feed attributes can be useful for filtering the feed
items using a matching function.

The same feed can be used in more than one FeedMapping, which
can be useful if multiple Google Ads features require similar tabular data.

4. Associate to customer, campaign, or ad group

At this point, the feed is ready to be used for sitelinks. The last step is
to associate the feed with a customer (CustomerFeedService),
campaign (CampaignFeedService)
or ad group (AdGroupFeedService)
to enable sitelinks for the specific set of ads.

Choosing whether to associate a feed to a customer, campaign, or ad group is
based on the data in your feed and the level of control you want. Using
sitelinks as an example again, if all of the ad groups in a campaign are to
show the same sitelinks, then you would associate the feed with the campaign.
Similarly, if you want sitelinks to be used with every campaign, associate the
feed with the account. If different ad groups in the same campaign are to show
different sitelinks, then you would associate the feed separately with specific
ad group only.

When you associate a feed, you can filter which feed items (rows) are
actually enabled for that customer, campaign, or ad group. For example, you can
have a single feed where some feed items (by virtue of a filter) are used for
one campaign and other feed items (by virtue of another filter) are used for
another campaign, and so on. Filters are applied by providing a matching
function which is evaluated for each feed item.

private static void createSiteLinksCampaignFeed(
    AdWordsServicesInterface adWordsServices,
    AdWordsSession session,
    SiteLinksDataHolder siteLinksData,
    Long campaignId)
    throws RemoteException {
  // Get the CampaignFeedService.
  CampaignFeedServiceInterface campaignFeedService =
      adWordsServices.get(session, CampaignFeedServiceInterface.class);

  // Construct a matching function that associates the sitelink feed items to the campaign, and
  // sets the device preference to mobile. See the matching function guide at
  // https://developers.google.com/adwords/api/docs/guides/feed-matching-functions
  // for more details.
  String matchingFunctionString = String.format(
      "AND( IN(FEED_ITEM_ID, {%s}), EQUALS(CONTEXT.DEVICE, 'Mobile') )",
      Joiner.on(',').join(siteLinksData.siteLinkFeedItemIds));

  CampaignFeed campaignFeed = new CampaignFeed();
  campaignFeed.setFeedId(siteLinksData.siteLinksFeedId);
  campaignFeed.setCampaignId(campaignId);

  Function matchingFunction = new Function();
  matchingFunction.setFunctionString(matchingFunctionString);

  campaignFeed.setMatchingFunction(matchingFunction);
  // Specifying placeholder types on the CampaignFeed allows the same feed
  // to be used for different placeholders in different Campaigns.
  campaignFeed.setPlaceholderTypes(new int[] {PLACEHOLDER_SITELINKS});

  CampaignFeedOperation operation = new CampaignFeedOperation();
  operation.setOperand(campaignFeed);
  operation.setOperator(Operator.ADD);
  CampaignFeedReturnValue result =
      campaignFeedService.mutate(new CampaignFeedOperation[] {operation});
  for (CampaignFeed savedCampaignFeed : result.getValue()) {
    System.out.printf("Campaign with ID %d was associated with feed with ID %d.%n",
        savedCampaignFeed.getCampaignId(), savedCampaignFeed.getFeedId());
  }
}

This method creates an association between a campaign and a feed. There are
two pieces of this data that are configured with this association: the
placeholder types and the matching function (filter).

You may wonder why the placeholder type (in this example, sitelinks) needs
to be configured again for the CampaignFeed when it was already
configured in the feed mapping for the feed. The reason is that requiring the
placeholders to be configured again provides the flexibility for a feed with
multiple feed mappings to be used for only some placeholder types in some
campaigns and other placeholder types in other campaigns.

Setting a matching function in the CampaignFeed tells the
serving system which feed items (rows) to actually use as sitelinks. See the Matching Functions
guide
for more details. In this example, we used FEED_ITEM_ID
as a RequestContextOperand in our matching Function;
however, we could have just as easily used another
RequestContextOperand type, or even matched using a
FeedAttributeOperand such as FeedAttributeId.

The same process works for ad groups and customers. You can connect feeds by
creating an AdGroupFeed
using the AdGroupFeedService
or CustomerFeed
using the CustomerFeedService.

5. Schedule feed items (optional)

You can optionally specify the days and times when feed items are enabled by
setting the feed item’s schedules attribute. Simply set
schedules to a FeedItemScheduling
that contains a FeedItemSchedule
for each day of the week and start/end time when you want the feed item
enabled.

To remove all schedules from a feed item, set its schedules to
a FeedItemScheduling object with an empty
feedItemSchedules collection.

For an example of how to construct a FeedItemSchedule, check
out the code
snippet for updating ad extensions
.

6. Set targeting for feed items (optional)

You can use FeedItemTargetService
to restrict individual feed items to only target specific campaigns, ad groups,
or criteria.

For example, if you want to restrict a given feed item to apply to an ad
group within a campaign, create a FeedItemAdGroupTarget
that includes the feedId, feedItemId, and
adGroupId. The FeedItemAdGroupTarget ensures that the
feed item will only serve with that ad group.

Keep in mind that targeting this way is restrictive only, meaning that the
entity you are targeting needs to already be included in the previously set up
matching function. Setting a FeedItemTarget will limit that feed
item to serving for that entity, but will not expand the matching function to
include that entity if it wasn’t already.

Removing feed items

To remove a feed item, set its status to REMOVED.
Removed feed items that have no associated stats will be permanently deleted
after some time.

Code examples

Refer to the following complete code examples in our client libraries to
learn more about feeds services.

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close