AdWords API Developer's Guide

Version 12 Release Notes

What's New

This release of AdWords API includes the following changes:

• Added conversion optimizer support - you can now enable conversion optimizer and adjust cost-per-acquisition bids through the AdWords API. Using conversion optimizer requires conversion tracking to be enabled on an existing campaign with at least 200 conversions in the past 30 days. For more information, see the CampaignService overview.
• Added CPC bidding for placement-targeted campaigns - use Website.maxCpc or AdGroup.siteMaxCpc to pay only when a user clicks on your placement-targeted ad.
• New budget fields in Campaign - A limited test release of monthly budget required two fields—budgetAmount and budgetPeriod—to replace dailyBudget. To use an existing campaign's budget with the new structure, set budgetPeriod to Daily and budgetAmount to the existing campaign's budget.
• AdGroup.id type change - AdGroup.id has been changed from an int to a long.
• Read-only fields added to LocalBusinessAd - as a consequence of adding some internal features, three new read-only fields (fullBusinessName, latitude, and longitude) are now available.
• Expanded code sample library - available at http://www.google.com/apis/adwords/samplecode.html

API Differences

The following tables show changes between v12 and v11. See the legend below for symbol descriptions (+ – ≠).

AdGroupService

CampaignService

AdService

CriterionService

Contents
Overview
API Differences

Overview

AdWords API version 11 (v11) introduces these changes to the AdWords API:

• New flexible report interface and one new report type - The report interface has changed in v11 to expand the range of reports you can schedule. The new, generalized DefinedReportJob object lets you create a custom report by choosing a report type, aggregation types, and an expanded set of report columns. It provides custom columns for any report type using the selectedColumns element. This generalized type replaces the specific report jobs available in v10 and earlier. The new interface can now expose new reports without requiring a new version release of the API.
  
  In v11, you can now aggregate by day of week (Sunday, Monday, Tuesday, etc.).
  
  The new report type is Reach and Frequency Performance, which has already been available from the AdWords website. This report shows how many people saw your ads and how many times they saw those ads over a certain period of time. This report data is available at the site, ad group, and campaign levels for CPM site-targeted campaigns only.
  
  
  For a list of v11 report types available, see the Report Section overview. To see how the v10 report types map to the v11 report types, see the table in that section.
• Renamed AdGroup CPC and CPM fields - To avoid ambiguity, we have renamed some AdGroup CPC and CPM fields by adding "keyword" or "site", to distinguish whether they apply to a keyword or website:
  • renamed maxContentCpc to keywordContentMaxCpc
  • renamed proxyMaxCpc to proxyKeywordMaxCpc
  • renamed maxCpm to siteMaxCpm
  • renamed maxCpc to keywordMaxCpc
• New shrunken image - AdService generates a smaller copy of almost any image that you submit and makes its URL available to you.
• Removed login info settings - Removed the ability to set the login email address or password (by removing AccountService.setLoginInfo).
• Campaign.endDay handling - If you set Campaign.endDay to a date both after 2036/12/31 and not 2037/12/30, the service will throw an exception. In previous versions, CampaignService silently rounded such out-of-range dates. 2037/12/30 is a special constant that causes the campaign to never end.
• Documentation improvements - Added alphabetic index of program elements. In the left navigation menu, added buttons to show and hide submenus.

API Differences

The differences between v11 and v10 follow.

Release Notes for V10

Contents
Overview
API Differences

Overview

AdWords API version 10 (v10) introduces these changes to the AdWords API:

• Site Suggestion Service - The new SiteSuggestionService provides operations for getting web site suggestions by category, topics you define, URLs or demographics. (Demographics is currently available in the U.S. only.) The suggestions the service returns include the URL of the suggested site, the approximate number of impressions per day, and which types of ads the site accepts (text, image, video).

  Categories are diverse, pre-defined areas, such as "Book Retailers" or "Veterinarians". Topics are any words or phrases you specify. Demographics target sites for age, household income, gender and ethnicity. For example you can ask for sites that target females from 18 to 34 with incomes over US$24,000.

• Check keyword traffic - A new request checkKeywordTraffic (in TrafficEstimatorService) lets you check a batch of keywords to see whether they will get any traffic.
• Proximity target - You can now target your ads by map coordinates and a surrounding circular area using ProximityTargets.
• GeoTarget field changes - The four fields in GeoTarget of type string[] (countries, regions, metros and cities) have been replaced by new fields that take data objects. For example, field cities has been replaced by field cityTargets of type CityTargets which then has a cities field of type string[]. This change enables an easier way to clear a field. This change does not otherwise alter the current capabilities, but sets the stage for us to add new capabilities in a future release. These differences are illustrated in the API differences below.
• Target all (boolean) - A new field targetAll in GeoTarget is true if targeting all countries or false if a targeting object is set or the campaign is using a targeting that the AdWords API does not support (such as polygon targeting).
• New currency support - Added support for currencies Ukrainian Hryvnia (UAH), Vietnamese Dong (VND) and Serbian Dinar (RSD).
• Zero impression reports enabled - (enabled June 12, 2007) The boolean field includeZeroImpression is now enabled in KeywordReportJob and CustomReportJob. When generating keyword and custom reports, it lets you include entities that have zero impressions. Very large reports that include zero impression rows may fail with error 112. If your report fails, try breaking it down into smaller ones. You will be charged the normal rate for scheduling the report (scheduleReportJob = 1000 units) whether or not the report succeeds. However, due to developer demand, we are enabling this feature now despite this issue. We are working to make this feature more scalable.

API Differences

The differences between v10 and v9 follow.

Release Notes for V9

Contents
Overview
API Differences

Overview

AdWords API version 9 (v9) introduces these changes to the AdWords API:

• Video ads - A new data object, VideoAd, holds data associated with a video ad. Another data object, Video, holds data for the video itself. A new method getMyVideos gets a list of your videos.
• Local timezone statistics - Now all calls return statistics in the account's local timezone, no matter what. As such, removed the inPST parameter from the statistics requests (AdGroupService.getAdGroupStats, AdService.getAdStats, and CampaignService.getCampaignStats).
• New email preferences - Added an ability to get periodic emails on your account's performance (accountPerformanceEnabled) and disapproved ads (disapprovedAdsEnabled).
• Check batch of ads - Added the request checkAds to check a batch of ads for policy errors.
• Specify default network - Replaced the field defaultAdsTargeting with defaultNetworkTargeting. Removed the field termsAndConditions (no replacement).
• New Active/InActive status for keyword and criterion - Active status replaces Normal and Inactive replaces OnHold in KeywordStatus and CriterionStatus.
• Removed Creative Service - Removed both CreativeService and Creative. Use AdService instead, which has improved functionality. See v8 of these release notes for a summary of the improvements.

API Differences

The differences between v9 and v8 follow.

Release Notes for V8

Contents
Overview
API Differences

Overview

AdWords API version 8 (v8) introduces these changes to the AdWords API:

• Budget Optimizer - A new field budgetOptimizerSettings in Campaign allows you optimize your budget. You can enable or disable the optimizer and set a ceiling on bids placed by the optimizer (proxy bids). While turning off the Budget Optimizer, you can also specify whether or not the optimized proxy bids replace the original user bids.

  When the Budget Optimizer is enabled, proxy bids will be placed by the budget optimizer and used in place of your manual bids. You can view the status of these bids in the field proxyMaxCpc on AdGroup and Keyword. Initially, before the Budget Optimizer has a chance to calculate bids, the adgroups will take on a default proxyMaxCpc that is the minimum currency value, and the keywords will have no proxy bids. Shortly thereafter, these bids will be adjusted, and you will see individual proxy keyword bids show up. You will still be able to read your manual bids (maxCpc) while the Budget Optimizer is on.

• AdService - Provides improved functionality over CreativeService and will eventually replace it.

  A new service, AdService, provides operations for accessing, creating and modifying Ads in an AdGroup. Ads have different visual representations for different targets:

  • Local Business Ads - Data associated with ads on Google Maps
  • Mobile Ads - Data associated with ads on a mobile phone
  • Image Ads - Data associated with image ads
  • Text Ads - Data associated with text-only ads
  • Commerce Ads - Sandbox only - Data associated with commerce ads.
  In addition, a new Business data object is available:
  • Business - Represents the data associated with a business
• Check creatives and criteria - Three methods have been added to check creatives and criteria: CriterionService.checkCriteria, CreativeService.checkCreative and CreativeService.checkCreativeList. They can be used in any version from v5 forward.
• Remove FX country code - Metropolitan France (FX) has been removed from the country codes.
• New custom report options - You can include this information in a custom report:
  • BusinessAddress
  • BusinessName
  • CurrencyCode
  • CustomerId
  • PhoneNumber
• AdWords Terms & Conditions now required - A requirement is added that all targeted AdWords accounts must have agreed to AdWords Terms & Conditions. If a call is attempted on a targeted account that has not agreed to the terms, an error occurs. We recommend that you speak with your advertisers/clients in order to determine who should review and accept/decline these terms. Account managers (MCC users) can automatically accept them on behalf of clients for all accounts as described at New Google Advertising Program Terms & Conditions on the AdWords API Blog.
• Warning: Fields re-ordered - In general, the order of fields in an object constructor may be taken from their order in the WSDL. In v8, the order of many WSDL fields changed and so the order of any generated object constructors may change. You might experience some compile failures, which are easy to detect and fix, if your stub generator makes all-field constructors, because a type will be wrong if its field is in the wrong order.

  However, please pay very close attention to any Address object constructors — it may be hard to tell that the order changed because the types of all Address fields are identical (String). This will not raise a compile error but it will generate the wrong stubs.

  If you are using setters or key/value assignment, you won't have a problem because it won't matter what order the fields are in. However, if you are generating, for instance, Java stubs with Axis, it generates an all-field constructor. The order of fields in this constructor will change in v8.

• Made "pause/unpause" available on live AdWords web service - No longer just sandbox. See v7 of these release notes for details.

API Differences

The differences between v8 and v7 follow.

Release Notes for V7

Contents
Overview
API Differences

Overview

AdWords API version 7 (v7) introduces these changes to the AdWords API:

• Ad scheduling - You can now schedule ads by intervals that are multiples of 1 day, 1 hour or 15 minutes. This is set in the schedule field in Campaign. Ad scheduling can be enabled or disabled by way of the status in AdSchedule . For more information, see What is ad scheduling?
• Cross-adgroup updates - Now you can use updateCriteria to do updates across different ad groups. (This means the id for each criterion in the criteria parameter passed into updateCriteria can now be different.) For example, you can set the keyword maxCpc or language in various ad groups with a single call. (No change to API.)
• Removed method to set local timezone - The setLocalTimezone method, which was turned off in v6, has been removed from v7. You can set the time zone only when creating an account.
• Removed method to create an AdWords account - Method createAdWordsAccount, which has always been restricted, has been deprecated.
• Removed deprecated setters and getters from AccountService - These setters and getters were in AccountService. They were replaced in v5 by fields in AccountInfo.
• Added clientCustomerId - You can now provide clientCustomerId in place of clientEmail in the header.
• Pause/unpause keywords, websites and creatives -
  Pausing keywords and websites - You can now pause or unpause (or resume) keywords by setting paused in Keyword to true or false (then call updateCriteria). Similarly, you can pause and unpause websites using the paused field in Website.

  NOTE - Pausing negative criteria - Negative criteria keywords and websites in ad groups (that is, where negative is true) can be paused and unpaused as expected. However, setting negative criteria using setCampaignNegativeCriteria (in CriterionService) with a paused Keyword or Website criterion will not pause the campaign.

  
  Pausing and deleting creatives - Creatives have a new status field that you can set to Paused (to pause) or Enabled (to unpause). Then pass the creative to the new updateCreatives request. The mechanism for deleting a creative has also changed — you now set the same status field to Disabled and call updateCreatives (rather than calling deleteCreative). You now check the deleted status by seeing if the status is Disabled (rather than checking if deleted is true). (Also, the request activateCreative has been removed, which is how you formerly activated a deleted creative.)
  
  Reports on paused keywords - You can get a report for paused keywords by setting KeywordStatus to the value Paused.

API Differences

The differences between v7 and v6 follow.

Release Notes for V6

Contents
Overview
API Differences

Overview

AdWords API version 6 (v6) introduces these changes to the AdWords API:

• Get quota units per client - You can now get the quota for each client using getUnitCountForClients. It returns an array of ClientUsageRecord data objects.
• Set startDay in a Campaign - You can set the startDay in Campaign to the day you want the campaign to start. This field is now mutable so you can change it to a day in the future up until the campaign starts. This field is passed in a Campaign data object in addCampaign. In v5 and earlier, this field was set to "today" and was immutable.
• Aggregate reports by week - You can now set the AggregationType to Weekly. This value can be used in all report job types.
• Get statistics on creatives - You can now get statistics for a list of creatives in an ad group using getCreativeStats in CreativeService. The time granularity is one day.
• Can no longer set local timezone - The setLocalTimezone method in AccountService is now deprecated and has been turned off. Calling it generates an error code. You can set the time zone only when creating an account. We plan to remove this in v7.

API Differences

The differences between v6 and v5 follow.

Release Notes for V5

Contents
Overview
API Differences

Overview

AdWords API version 5 (v5) introduces these changes to the AdWords API: batch error handling, hourly reports, four new report jobs, new AccountInfo object, new application token, new fault element, changed fault messages, changed error messages, and the removal of KeywordService.

• Batch Error Handling and Minimizing of Quota - When you pass in an item or list of items with an operation, if that operation produces validation error 122 "One or more input elements failed validation", the response now batches up all detected errors and returns them as a list, as the ApiError[] type in the errors field. (In v4, it would just return the first error.) Batching of errors reduces the number of iterative requests required to debug a call. In addition, we now charge quota only in proportion to the number of items that failed, rather than for the entire list of items in the operation (as was done previously). For example, if 100 creatives are passed in and 8 creatives produce errors, then only 8/100 of that operation's quota is charged. A single creative can produce multiple errors (such as "trademark violation" and "too many words"), but it still counts as only one failed creative. Error handling handling is now formalized in the ApiException and ApiError data objects. (Batch error handling is also known as "Batch semantics".)

  Please note that operations are still atomic — that is, an operation will either execute on all items or won't execute at all.

  Requests that have been modified to handle batch errors:

  • CampaignService: addCampaign, addCampaignList, updateCampaign, updateCampaignList
  • AdGroupService: addAdGroup, addAdGroupList, updateAdGroup, updateAdGroupList
  • CreativeService: activateCreative, activateCreativeList, deleteCreative, deleteCreativeList, addCreative, addCreativeList
  • CriterionService: addCriteria, updateCriteria, removeCriteria, setCampaignNegativeCriteria
• Hourly Reports - Two new values of AggregationType have been added to generate hourly accounts only on the new reports CampaignReportJob and AccountReportJob (not CustomReportJob):
  • HourlyRegardlessDate - Generates reports across the specified range of dates totaled by hour
  • HourlyByDate - Generates reports with hourly totals day for each date

  These are possible values in the aggregationType field. In hourly reports, only start dates of Feb 1, 2006 or later are valid; dates before that produce an error. NOTE: Aggregation Type is called "Report Type" on the AdWords website. For more information , see What are hourly reports?.

• Four New Report Jobs - AccountReportJob, AdGroupReportJob, AdImageReportJob, CampaignReportJob.
• New AccountInfo Object and AccountService Requests - The new AccountInfo data object collects all account information into a single object, including customer ID (not previously available), billing address, preferences. This object can be accessed with getAccountInfo and updateAccountInfo on AccountService. All fields are accessible to the MCC account manager except billable info can only be gotten by the account owner. The getters and setters in AccountService are now deprecated and will be removed in a future version.
• New timeZoneId Parameter - New timeZoneId field in createAdWordsAccount request of AccountService holds an optional time zone.
• New emailAddress Field - New emailAddress field in Address data object holds a contact email address for the account. This address can be different from your login email address.
• New Application Token - New applicationToken request header element that indicates the application that is sending the request.
• New Fault Element - In the interest of better interoperability with Apache Axis clients, the fault <detail> element contains a <fault> element in our namespace. This allows Axis to turn these into ApiException objects on the client side. Here's an example of a fault:

  <soapEnv:Fault>
    <faultcode>...</faultcode>
    <faultstring>...</faultstring>
    <detail>
      <ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v5">
      <ns1:code>5</ns1:code>
      <ns1:message>No AdGroup with this ID was found.</ns1:message>
      <ns1:trigger>1234</ns1:trigger>
      </ns1:fault>
    </detail>
  </soapEnv:Fault>
  

• Changed Fault Messages - Some faultString messages have changed from v4 so code depending on these strings might break. For example, a message that used to say "Invalid keyword", now gives a more specific reason in its error message.
• Changed Error Messages -
  • New error codes from Error Code 114 and up.
  • Changed Error Code 40 - This error code has changed meaning, from "A report was too large to download through the API" to "The scheduled report job is too large to generate.".
  • Changed Error Code 41 - This error code has changed meaning, from "The client request did not contain a 'token' header." to "The request did not contain a header named 'token' or 'developerToken'.".
  • A few other error codes have minor changes to their message strings.
  • Error code 125 won't take any effect until after October 2, 2006.
• Removal of KeywordService - Use CriterionService instead.

API Differences

The differences between v5 and v4 follow.