Introduction to Feeds Services

This guide is an introduction to feeds, which offer a generic and flexible way for you to provide and use tabular data in an AdWords account. Some examples of AdWords 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 AdWords 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 AdWords 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 AdWords 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 AdWords).

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 AdWords 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 AdWords, 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 AdWords 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 AdWords 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 AdWords 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 AdWords 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 AdWords 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)

Starting in v201802, 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.

Library AddSitelinksUsingFeeds example
Java AddSitelinksUsingFeeds.java
Perl add_site_links_using_feeds.pl
PHP AddSitelinksUsingFeeds.php
Python add_site_links_using_feeds.py
Ruby add_site_links_using_feeds.rb
C# AddSitelinksUsingFeeds.cs
VB.NET AddSitelinksUsingFeeds.vb

Send feedback about...

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