Tag Archives: feeds

New CallOnly creative type in AdWords API

Call-only ads in AdWords allow you to show mobile-ready ads that feature a click-to-call button and descriptive text, so your customers can call you directly from mobile search results. The AdWords API v201409 release introduced support for call-only ads through a new creative type: CallOnlyAd.

These new CallOnlyAds are set up just the same way as TextAds, with the addition of a few fields useful for the new type. In Ruby, for example, you would set up a new CallOnlyAd with a hash like this: 

{
  :xsi_type => 'CallOnlyAd',
  :description1 => 'Visit the Red Planet in style.',
  :description2 => 'Low-gravity fun for everyone!',
  :display_url => 'www.example.com',
  :phone_number => '(555) 555-5555',
  :business_name => 'Universal Cruises',
  :call_tracked => true,
  :phone_number_verification_url => 'www.example.com/landing_page'
}
You can also set the conversionTypeId if you want to measure calls in a specific conversion type. Otherwise, tracked calls will use a default conversion type.

The phoneNumberVerificationUrl is a new field for CallOnlyAds. If included, we will crawl the page you specify to look for the phone number for verification; this can speed up the approval process. Otherwise, we will have to crawl your entire website.

Previously, call-only ads were set up using feeds, specifically with the ONLY field (placeholder ID 4) within the Call placeholder type (placeholder type ID 2). The ONLY field will sunset in June 2015, so you should finish migrating all your existing call-only ads to the new CallOnlyAd creative type before that time. It is recommended that you create new campaigns to house your CallOnlyAds separately from other ad types.

As always, if you have any questions about this change, please contact us on the forum or via our Google+ page.

- Michael Cloonan, AdWords API Team

Announcing callout extensions support in the AdWords API

On September 3rd, 2014, we introduced callouts extensions: additional text you can include with your Google search ads that provide detailed information about your business, and products and services you offer. Starting today, all AdWords API versions can now manage callouts using the existing Feed API, similar to other feeds.

Feeds for callouts are mapped to feed placeholder type 17, with only one string field. See the feed placeholder documentation for more information.

- , AdWords API Team

Introducing Ad Customizers in AdWords API

Today, we are introducing ad customizers, a new way to insert dynamic information into your ads. Ad customizers work similarly to ad parameters. They allow you to set up a feed with dynamic data, targeted at specific campaigns, ad groups or keywords. Your ads then reference the information in those feeds so that the values are inserted when the ad is served. You can also create ads that dynamically count down to an event, by inserting {=COUNTDOWN(...)} in your ad. Learn more about this new feature here.

Ad customizers are currently supported in AdWords API test accounts. Production accounts need to be whitelisted before you can use this feature. You can sign up for this feature here. Once your account is whitelisted, you will receive a confirmation email and can start using ad customizers in the whitelisted account. We whitelist accounts in batches, so expect some delay between signing up for the feature and getting your account whitelisted.

If you have any questions about this feature or the AdWords API in general, you can post them on our developer forum. You can also follow our Google+ page for updates about the AdWords API.

Anash P. Oommen, AdWords API Team

AdWords API – Upgrading to account-level location extensions

On July 14th, 2014, AdWords announced upgraded location extensions, a more efficient way to manage and use business locations in ads by linking Google My Business and AdWords accounts.

The upgrade is taking place in phases for AdWords accounts throughout the coming months. The next phase of account upgrades is scheduled to start on August 25, 2014. All AdWords accounts will to be upgraded by November, 2014.

The upgrade has direct impact to AdWords API client applications. If you are using the CampaignAdExtensionService to manage LocationExtensions or LocationSyncExtensions, then you’re using the legacy location extensions that are being phased out. After an account is upgraded, you’ll need to use the new account-level feed-based location extensions.

How will existing location extensions be upgraded by Google?

Please review the AdWords Help Center article for all upgrade scenarios. For AdWords API developers, most accounts will fall into one of these scenarios:
  • Accounts that don’t have any existing legacy location extensions.
  • Accounts that have existing legacy location extensions not sourced from a Google My Business account (i.e., using LocationExtensions only).
  • Accounts that have existing legacy location extensions sourced from a Google My Business account (i.e., using LocationSyncExtensions).
If you programmatically create AdWords accounts that are not associated with any user, please get in touch with your Google representative for migration support.

Accounts that don’t have any existing legacy location extensions

For accounts that aren’t using any LocationExtensions or LocationSyncExtensions but will begin using location extensions, you should use feed-based location extensions instead.

Accounts that have existing legacy location extensions not sourced from a Google My Business account

If you’re using LocationExtension entities to manage individual locations, the automatic upgrade process will perform the following:
  1. A Google My Business account will be created and linked with the AdWords account. All administrators of that AdWords account will have access to locations in the linked Google My Business account.
  2. A CustomerFeed with the Location placeholder type will be created.
  3. Existing locations in LocationExtension entities will be copied into the Google My Business account. Existing LocationExtension entities will then be removed.
  4. Ads in all campaigns will be served with locations from the linked Google My Business account (you can create a CampaignFeed to further filter or disable location extensions served for a given campaign).
Accounts that have existing legacy location extensions sourced from a Google My Business account

If you’re using LocationSyncExtension to link campaigns to a Google My Business account, then the automatic upgrade process will perform the following:
  1. The campaign-level links to the Google My Business account will be switched to a single link at the account level.
    • A CustomerFeed with the Location placeholder type will be created for the account.
  2. Any existing LocationExtension entities will be removed, so make sure they’re copied to the linked Google My Business account before the upgrade.
  3. Ads in all campaigns will be served with locations from the linked Google My Business account (you can create a CampaignFeed to further filter or disable location extensions served for a given campaign).
If an AdWords account is already linked to Google My Business at the account level using CustomerFeed, any existing legacy location extensions will be removed during the upgrade process.

How do I know if an account has been upgraded?

An account is considered upgraded if either condition is true:
  1. It has a CustomerFeed for the Location placeholder type. You can query CustomerFeedService to check: 

    select FeedId, PlaceholderTypes where PlaceholderTypes = 7
  2. It has neither a CustomerFeed nor legacy LocationExtension or LocationSyncExtension entities.
In an upgraded account, any attempts to create legacy location extensions using the CampaignAdExtensionsService will return the AdExtensionError.INVALID_ADEXTENSION_TYPE error.

How do I continue to manage locations?

There’s currently no API support for Google My Business. Locations are managed via the Google My Business Locations interface, which supports bulk management.

Can I start using upgraded location extensions before an account is upgraded?

Since the upgrade process is complicated for many accounts, the simplest approach is to allow accounts using legacy location extensions to be automatically upgraded (account owners will be notified 30 days before the upgrade).

What about reporting?

For upgraded accounts, you’ll need to use the Placeholder Feed Item Report rather than the Ad Extensions Performance Report to download statistics for each location.

We are here to help

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the AdWords API forum or via the Google Ads Developers Google+ page.

- , AdWords API Team

AdWords API – Using CONVERSION DURATION THRESHOLD feed placeholder will throw errors

The CONVERSION DURATION THRESHOLD placeholder was deprecated on April 28th, 2014. Starting July 21st, 2014, using this placeholder with the FeedMappingService will result in a FeedMappingError.INVALID_PLACEHOLDER_FIELD error for all AdWords API versions.

See this post for details on how to set your conversion duration going forward with the CONVERSION TYPE ID placeholder instead.

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the AdWords API forum or via the Google Ads Developers Google+ page.

- Ray Tsang, AdWords API Team

Reminder: AdWords API is sunsetting CONVERSION DURATION THRESHOLD feed placeholder

This is a reminder that the CONVERSION DURATION THRESHOLD placeholder is sunsetting starting on April 28th, 2014.

Starting on the sunset date, AdWords accounts will be migrated to use the new CONVERSION TYPE ID placeholder for a four-week time period. During this period, some AdWords accounts that you access via the AdWords API may be migrated, and some may not. Read on to find out how to determine if a feed has been migrated or not. Migration of all AdWords accounts is scheduled to complete by end of May, 2014.

How will an existing conversion duration threshold be migrated?

If you used CONVERSION DURATION THRESHOLD in a Feed Mapping prior to the sunset date, then we will automatically migrate those values after the sunset date - and they will be accessible via the AdWords API v201402 as follows:
  • New AdCallMetricsConversion will be automatically created for you with the existing conversion duration threshold.

    Note: If you have 3 feed items with call duration threshold, where two of them are set to 120 seconds, and one of them are set to 30 seconds, then only two AdCallMetricsConversion will be created - one with AdCallMetricsConversion.phoneCallDuration set to 120 seconds, and another one set to 30 seconds.

  • Feed attributes using CONVERSION DURATION THRESHOLD will remain, setting and reading those values will not produce errors. However, any associated feed attribute values will not be honored.

  • A new feed attribute will be automatically created in your existing feed, and it will be automatically be mapped to the new CONVERSION TYPE ID placeholder type.

  • The new conversion type ID feed attribute will be associated to the newly created AdCallMetricsConversion.

Note that in order to get the name and field attribute ID of the newly created conversion type ID field attribute, you should use the FeedMappingService to determine the feed attribute ID that is associated with the CONVERSION TYPE ID placeholder type.

How do I know if a Feed has been migrated?

If a feed has been migrated, you will be able to see that the Feed has an attribute associated to the CONVERSION TYPE ID placeholder type. You can use the FeedMappingService to determine this.

How do I set conversion duration threshold on a migrated Feed?

If you’d like to continue using conversion duration threshold, then you must upgrade to the AdWords API v201402.

In a migrated feed, the CONVERSION TYPE ID feed item attribute value refers to an AdCallMetricsConversion object by ID. To set the conversion duration threshold, you must update the associated AdCallMetricsConversion object’s phoneCallDuration field. Please note that doing this will impact other feed items that are associated to the same AdCallMetricsConversion object.

Alternatively, you can also associate the CONVERSION TYPE ID feed item attribute value to a different AdCallMetricsConversion:
  • Re-use an existing AdCallMetricsConversion that has the right phone call duration
  • Use the ConversionTrackerService to create new AdCallMetricsConversion with the phoneCallDuration field set
In a migrated feed, if you continue to set the attribute value associated with the CONVERSION DURATION THRESHOLD placeholder, then those values will be ignored.

Can I start using the new placeholder before the Feed gets migrated?

Yes. Starting from the sunset date, you will be able to use the new CONVERSION TYPE ID placeholder in your feed. If you are using the placeholder in your feed and set the attribute value to a valid AdCallMetricsConversion ID, then the CONVERSION TYPE ID value will be used, and the CONVERSION DURATION THRESHOLD value will be ignored.

If you choose to do this prior to the automatic migration - don’t worry. The automatic migration process will not overwrite your existing CONVERSION TYPE ID values with CONVERSION DURATION THRESHOLD values.

We are here to help

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the AdWords API forum or via the Google Ads Developers Google+ page.

- Ray Tsang, AdWords API Team

Enforcing Unique Names for Feeds in the AdWords API

Starting on April 29, 2014, the FeedService will start validating that newly added Feeds have unique names within an AdWords account. Once this change goes into effect, you will get a FeedError when you ADD a new Feed with the same name as another active Feed.

Currently it’s possible to have multiple Feeds with the same name. Introducing unique names will improve clarity in the user interface, and it will also allow Feeds to be referenced unambiguously by name, in addition to their ID.

Please ensure that your application is both uniquely naming Feeds and able to handle a potential naming conflict before this change goes into effect.

Shortly after this change is rolled out, we will append a unique value to the names of any remaining duplicates. For example, the following pair of Feeds on the left would be renamed as follows:

Old Names
New Names
My Sitelinks Feed
My Sitelinks Feed-1
My Sitelinks Feed
My Sitelinks Feed-2


- Adam Ohren, AdWords API Team

New feed-based location extensions in v201402 of AdWords API

As previously announced, AdWords API v201402 lets you manage your upgraded, feed-based location extensions in addition to your campaign location extensions. Upgraded location extensions are linked to your Google Places for Business account and offer significant benefits over manually entered location extensions. Most importantly, once you configure your upgraded location extensions you don't have to worry about keeping them up to date with changes in your Google Places for Business account -- AdWords does it for you!

As mentioned in our detailed guide to upgraded location extensions, you can use the AdWords API to set up your extensions in a few easy steps: There are a few key differences between feeds with systemFeedGenerationData ("location feeds") and other feeds you may have created for sitelinks, app or call extensions.

Type or Attribute
Location Feeds
Other Feeds
Required

Defines the link between your AdWords and Places for Business accounts.
Not applicable
Not applicable

AdWords maintains the feed item attribute -> placeholder field relationship for you.
Required

You maintain the feed item attribute -> placeholder field relationship.
Automatically managed by AdWords.
Maintained by you via the FeedItemService
Required
Not applicable
Optional

Only needed if you want more control over which businesses from your Places account are used for location extensions on a particular Campaign.
Required
Optional
Optional
Only needed if you want more control over which businesses from your Places account are used for location extensions on a particular AdGroup.

Just as for other feed types, you can get stats for a location feed's extensions from the PLACEHOLDER_FEED_ITEM report.

This is just a quick overview of the AdWords API support for upgraded location extensions. For more information, check out our feed services guide for location extensions and the accompanying code sample in each client library (Java, Perl, PHP, Python, Ruby, .NET).

Still have questions? Feel free to visit us on the AdWords API Forum or our Google+ page.

- Josh Radcliff, AdWords API Team

Introducing a new type of feed for AdWords API: Review extensions

Review extensions, which let you show accolades from reputable third parties right in your search ads, were introduced last year. We have now made this feature available for the AdWords API in v201402.

Creating review extensions is the same as creating sitelinks as described in this guide. The only differences are:
  • The different placeholderId for FeedMappingService. As shown in the feed placeholders page, the placeholderId for review extensions is 8.
  • A different set of Feed attributes for FeedService. A review extension consists of four attributes:
    • Text (String): Either an exact quote or paraphrase from a third-party source that appears beneath your ad
    • Source (String): Name of the third-party publisher of the quoted or paraphrased review you’re using in your review extension
    • Source URL (URL): Landing page of the third-party website where the quoted or paraphrased review is located
    • Format (Boolean): Indicates whether your review is formatted as an exact quote from the third-party source, or if you’re paraphrasing. Setting to true means your review is formatted as an exact quote, false means paraphrasing.
Here is the Java code to create a Feed for review extensions. Code examples in other programming languages are available as part of the client libraries. 

FeedAttribute textAttribute = new FeedAttribute();
textAttribute.setType(FeedAttributeType.STRING);
textAttribute.setName("Text");

FeedAttribute sourceNameAttribute = new FeedAttribute();
sourceNameAttribute.setType(FeedAttributeType.STRING);
sourceNameAttribute.setName("Source Name");

FeedAttribute sourceUrlAttribute = new FeedAttribute();
sourceUrlAttribute.setType(FeedAttributeType.URL);
sourceUrlAttribute.setName("Source URL");

FeedAttribute exactlyQuotedAttribute = new FeedAttribute();
exactlyQuotedAttribute.setType(FeedAttributeType.BOOLEAN);
exactlyQuotedAttribute.setName("Exactly Quoted");

Feed reviewExtensionFeed = new Feed();
reviewExtensionFeed.setName("Feed For ReviewExtension from API");
reviewExtensionFeed.setAttributes(
    new FeedAttribute[] {textAttribute, sourceNameAttribute,
    sourceUrlAttribute, exactlyQuotedAttribute});
If you have any questions about this feature or the AdWords API in general, you can post them on the developer forum. You can also follow the Google+ page for updates about the AdWords API.

- Takeshi Hagikura, AdWords API Team

Sunsetting CONVERSION DURATION THRESHOLD feed placeholder in AdWords API

If you use AdWords call extensions, you know that you can count phone calls as conversions based on the duration of the call (e.g., 60 seconds). When using AdWords API feeds, this duration threshold is specified as the CONVERSION DURATION THRESHOLD placeholder. This placeholder is sunsetting on April 7th, 2014. You will not receive errors if you continue to read and set values associated with this placeholder. However, these values will not be honored past the sunset date.

How do I set conversion duration threshold in the future?
After the sunset date, if you’d like to continue using conversion duration threshold, then you must upgrade to the AdWords API v201402:
  • Use the ConversionTrackerService to create an AdCallMetricsConversion
  • Set the call duration threshold in the AdCallMetricsConversion.phoneCallDuration field
  • Use the new CONVERSION TYPE feed placeholder and setting the feed attribute value to the value of the newly created AdCallMetricsConversion.Id
Note: CONVERSION TYPE placeholder is not available for use at the time of this post. We will make a separate announcement when it’s ready.

What will happen to my existing conversion duration threshold values?
If you used CONVERSION DURATION THRESHOLD in a Feed Mapping prior to the sunset date, then we will automatically migrate those values after the sunset date - and they will be accessible via the AdWords API v201402 as follows:
  • New AdCallMetricsConversion will be automatically created for you with the existing conversion duration threshold.

    Note: If you have 3 feed items with call duration threshold, where two of them are set to 120 seconds, and one of them are set to 30 seconds, then only two AdCallMetricsConversion will be created - one with AdCallMetricsConversion.phoneCallDuration set to 120 seconds, and another one set to 30 seconds.
  • Feed attributes using CONVERSION DURATION THRESHOLD will remain, setting and reading those values will not throw errors. However, any associated feed attribute values will not be honored.
  • A new feed attribute will be automatically created in your existing feed, and it will be automatically be mapped to the new CONVERSION TYPE placeholder type
  • The new conversion type feed attribute will be associated to the newly created AdCallMetricsConversion
Note that in order to get the name and field attribute ID of the newly created conversion type field attribute, you should use the FeedMappingService to determine the feed attribute ID that is associated with the CONVERSION TYPE placeholder type.

If you have any questions about this upcoming change or anything else related to the AdWords API, please contact us on the AdWords API forum or via the Google Ads Developers Google+ page.

- , AdWords API Team