API Version 4 Now Available

Friday, May 12, 2006

We are happy to announce the release of the AdWords API Version 4.

Version 4 (V4) introduces three major enhancements to the AdWords API: local time zone operations, reporting on a list of account logins, and an update of the traffic estimator fields.


V4 includes new local time zone operations necessary for setting and retrieving account time zone information. Specifically, we’ve expanded the AccountService to include new getLocalTimezone, setLocalTimezone, and getTimeZoneEffectiveDate operations.

However, for the next few weeks, only getLocalTimezone and getTimezoneEffectiveDate will be supported. During this time, any calls to setLocalTimezone will return error code 111 (invalid time zone change). After we finish rolling out time zone support to all AdWords users, we will enable setLocalTimezone (this change will be announced on the AdWords API Blog and Forum).

For more information on how our new time zone support settings will affect API developers, please review our April 27th blog post.


The KeywordReportJob, CustomReportJob, AdTextReportJob and UrlReportJob objects in the ReportService have been modified so that developers can more easily report on a subset of accounts by providing a comma-separated list of account email logins. Specifically, we are replacing the clientAccounts (int[]) field with a new clientEmails (string[]) field.


To maintain functional parity with the AdWords web interface, we are replacing three fields in the KeywordEstimate data object with six (6) new fields. These new fields represent interval boundaries instead of single values. These changes, originally implemented in the AdWords web interface, are designed to give advertisers greater insight into their keyword performance.

  • avgPosition will be replaced with… lowerAvgPosition & upperAvgPosition
  • ClicksPerDay will be replaced with… lowerClicksPerDay & upperClicksPerDay
  • cpc will be replaced with… lowerCpc & upperCpc
  • Zero Impression Reporting – In order to support zero impression reporting in a future release, we have added an “includeZeroImpression” field to the KeywordReportJob and CustomReportJob. Please be aware that zero impression data will not be available in V4. We will notify all developers when this functionality becomes available.
  • Unique Request ID - A new response header element, requestId, uniquely identifies each request. This element allows tracking of requests by developers and the web service.
  • Geo Codes – We are no longer supporting non-standard country codes, including UK and YU. This will affect any method that uses GeoTarget as well as keyword tool methods.


Per our versioning policy, V3 will be supported for two months from today, at which time it will be turned off. Therefore, please make sure that you upgrade to V4 before July 12, 2006.

For technical details about V4, please review the latest Release Notes section of the Developer’s Guide.

-- Rohit Dhawan, Product Manager