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, as explained below.

This guide uses Java for the code samples. For code examples in other programming languages, see the table at the end of this guide.

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
Store Locator
Sale Items
About Us

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 interrelated services you use to create and manage feeds.

This service is used to describe to AdWords the shape of your tabular data, i.e., a name or title for your Feed (table) as well as the column names and types.
This service is used to populate your feed with data. Each FeedItem represents a row in the table.
This service is used to specify how the feed will be used, i.e., how to map the columns of your table with the fields that a particular AdWords feature requires. This guide shows how to map a feed to be used for sitelinks.
This service enables your feed across a customer's entire account, i.e., all campaigns and ad groups.
This service enables your feed across an entire campaign, i.e., all ad groups within that campaign.
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 the table provided at the end of the document.

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).

1. Create the feed

We 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 FeedAttributes (columns). Each FeedAttribute itself has a name (column header) and type.

In the example below, createSiteLinksFeed() uses FeedService to create a Feed with FeedAttributes (columns) appropriate to hold tabular data for sitelinks:

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

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

  // Create the feed.
  Feed siteLinksFeed = new Feed();
      new FeedAttribute[] {textAttribute, finalUrlAttribute, line2Attribute, line3Attribute});

  // Create operation.
  FeedOperation operation = new FeedOperation();

  // 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",

In order to describe the tabular data that will be used for sitelinks, the method creates a Feed with FeedAttributes (columns) named Link Text, Final URLs, Line 1, and Line 2. We name the Feed Feed For Sitelinks as a useful description for our reference. The Feed's origin is set to FeedOrigin.USER to signify that its FeedItems (rows) will be populated by the advertiser. (In contrast, it is also possible for feeds to have their data populated by AdWords.)

A mutate operation is called on FeedService to create the Feed. Upon successfully adding the Feed, FeedService returns its ID as well as all the IDs for each FeedAttribute (column). It is 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 will see later, you can also create a Feed with more columns, only some of which contain data needed by the AdWords feature. One reason you might do this is to use the values in the other columns to filter which FeedItems (rows) apply to which campaign or ad group using a matching function, as described below.

2. Populate the feed

Now that the shape of the data has been described to AdWords, the sitelink data can be populated by adding FeedItems (rows) using FeedItemService.

We begin with a helper method, newSiteLinkFeedItemAddOperation(), to construct FeedItems. This helper method takes information about a sitelink (its text label, finalUrl, and descriptive lines) and the IDs of our Feed's FeedAttributes (columns) to create a new FeedItem (row) populated with the provided information. The new FeedItem 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 FeedItemAttributeValues (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, null);

private static FeedItemOperation newSiteLinkFeedItemAddOperation(
    SiteLinksDataHolder siteLinksData, String text, String finalUrl, String line2, String line3,
    Long locationId) {
  // Create the FeedItemAttributeValues for our text values.
  FeedItemAttributeValue linkTextAttributeValue = new FeedItemAttributeValue();
  FeedItemAttributeValue linkFinalUrlAttributeValue = new FeedItemAttributeValue();
  linkFinalUrlAttributeValue.setStringValues(new String[] {finalUrl});
  FeedItemAttributeValue line2TextAttributeValue = new FeedItemAttributeValue();
  FeedItemAttributeValue line3TextAttributeValue = new FeedItemAttributeValue();

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

  // OPTIONAL: Use geographical targeting on a feed item.
  // IDs can be found in the documentation or retrieved with the
  // LocationCriterionService.
  if (locationId != null) {
    Location location = new Location();
    // OPTIONAL: Restrict targeting only to people physically within the location.
    FeedItemGeoRestriction geoTargetingRestriction = new FeedItemGeoRestriction();

  // 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();
  return operation;

Continuing the example, the method below, createSiteLinksFeedItems(), creates all of the FeedItems and the FeedItemOperations containing them, invoking our helper method with different information for each sitelink we want to create.

The FeedItems 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 Exception {
  // Get the FeedItemService.
  FeedItemServiceInterface feedItemService =
      adWordsServices.get(session, FeedItemServiceInterface.class);

  // Create operations to add FeedItems.
  FeedItemOperation home = newSiteLinkFeedItemAddOperation(siteLinksData, "Home",
      "", "Home line 2", "Home line 3");
  FeedItemOperation stores = newSiteLinkFeedItemAddOperation(siteLinksData, "Stores",
      "", "Stores line 2", "Stores line 3");
  FeedItemOperation onSale = newSiteLinkFeedItemAddOperation(siteLinksData, "On Sale",
      "", "On Sale line 2", "On Sale line 3");
  FeedItemOperation support = newSiteLinkFeedItemAddOperation(siteLinksData, "Support",
      "", "Support line 2", "Support line 3");
  FeedItemOperation products = newSiteLinkFeedItemAddOperation(siteLinksData, "Products",
      "", "Products line 2", "Products line 3");
  // This site link is using geographical targeting by specifying the
  // criterion ID for California.
  FeedItemOperation aboutUs = newSiteLinkFeedItemAddOperation(siteLinksData, "About Us",
      "", "About Us line 2", "About Us line 3", 21137L);

  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());

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 FeedAttributes (column) to the placeholder's fields, indicating how those FeedAttributes are to be interpreted for this AdWords feature.

// See the Placeholder reference page for a list of all the placeholder types and fields.
private static final int PLACEHOLDER_SITELINKS = 1;

// See the Placeholder reference page for a list of all the placeholder types and fields.
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 Exception {
  // Get the FeedItemService.
  FeedMappingServiceInterface feedMappingService =
      adWordsServices.get(session, FeedMappingServiceInterface.class);

  // Map the FeedAttributeIds to the fieldId constants.
  AttributeFieldMapping linkTextFieldMapping = new AttributeFieldMapping();
  AttributeFieldMapping linkFinalUrlFieldMapping = new AttributeFieldMapping();
  AttributeFieldMapping line2FieldMapping = new AttributeFieldMapping();
  AttributeFieldMapping line3FieldMapping = new AttributeFieldMapping();

  // Create the FeedMapping and operation.
  FeedMapping feedMapping = new FeedMapping();
  feedMapping.setAttributeFieldMappings(new AttributeFieldMapping[] {linkTextFieldMapping,
      linkFinalUrlFieldMapping, line2FieldMapping, line3FieldMapping});
  FeedMappingOperation operation = new FeedMappingOperation();

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

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 FeedAttributes to the placeholder fields that are needed for sitelinks: link text, final URLs, and descriptive lines. This mapping tells AdWords which FeedAttributes (columns) correspond to which aspects of sitelinks.

Not all FeedAttributes have to be mapped to a placeholder field. As noted earlier, a Feed can have more FeedAttributes (columns) than the AdWords feature requires. Those extra FeedAttributes may, for example, be useful for filtering the FeedItems using a matching function, as described below.

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 should show the same sitelinks, then you can associate the feed with the campaign. Similarly, if you want sitelinks to be used with every campaign, associate the feed with the account. On the other hand, if different ad groups in the same campaign should show different sitelinks, then you should associate the feed separately with specific ad group only.

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

private static void createSiteLinksCampaignFeed(AdWordsServicesInterface adWordsServices,
    AdWordsSession session, SiteLinksDataHolder siteLinksData, Long campaignId) throws Exception {
  // 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
  // for more details.
  String matchingFunctionString = String.format(
      "AND( IN(FEED_ITEM_ID, {%s}), EQUALS(CONTEXT.DEVICE, 'Mobile') )",

  CampaignFeed campaignFeed = new CampaignFeed();

  Function matchingFunction = new Function();

  // 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();
  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 FeedMapping for the Feed as a whole. The reason is that requiring the placeholders to be configured again provides the flexibility for a Feed with multiple FeedMappings 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 FeedItems (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 FeedItems are enabled by adding a FeedItemScheduling into a FeedItem object as shown below:

// Create and set the days and time.
FeedItemSchedule schedule = new FeedItemSchedule();

// Create the feed item scheduling.
FeedItemScheduling scheduling = new FeedItemScheduling();
scheduling.setFeedItemSchedules(new FeedItemSchedule[] {schedule});
If you want to reset the schedule, set the empty FeedItemScheduling as shown in the code below.

private static FeedItemOperation newSiteLinkFeedItemOperationResetScheduling(
    Long feedId, Long feedItemId) {
  // Create the feed item and operation.
  FeedItem feedItem = new FeedItem();

  FeedItemScheduling scheduling = new FeedItemScheduling();

  FeedItemOperation operation = new FeedItemOperation();
  return operation;

Code examples

Refer to the following complete code examples in our client libraries to learn more about Feeds services.
Library AddSitelinksUsingFeeds example
PHP AddSitelinksUsingFeeds.php
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.