Discovering v201109: ConstantDataService

We’ve released the ConstantDataService as a new service with v201109.  This blog post will talk about what it is used for as well as suggest some best practices.

The ConstantDataService currently has two web service methods available: getCarrierCriterion and getLanguageCriterion.  These methods return Carrier and Language criteria respectively.  These criteria can be used with the CampaignCriterion to get more fine-grained control of the targeting of your campaigns.  This functionality replaces the CampaignTargetService’s LanguageTarget and MobileCarrierTarget.

Previously, we published lists of these targets/criteria in static files on code.google.com as the sole way to get a list of possible options.  With the ConstantDataService, we are now exposing these values programmatically via the AdWords API.  As a result, your application can now dynamically obtain a list of options for these criteria.  Let’s see how to get a list of Carriers in Python.

# Initialize client object.
client = AdWordsClient(path=os.path.join('..', '..', '..', '..'))

# Initialize appropriate service.
constant_data_service = client.GetConstantDataService(
   'https://adwords-sandbox.google.com', 'v201109')

# Get all carriers.
carriers = constant_data_service.GetCarrierCriterion()

# Display results.
for carrier in carriers:
 print ('Carrier with name \'%s\', ID \'%s\', and country code \'%s\''
        ' was found.' % (carrier['name'], carrier['id'], carrier['countryCode']))

Output from this script would look like this:

Carrier with name 'NTT DoCoMo', ID '70000', and country code 'JP' was found.
Carrier with name 'KDDI/au', ID '70001', and country code 'JP' was found.
Carrier with name 'Vodafone', ID '70002', and country code 'JP' was found.
Carrier with name 'EMOBILE', ID '70003', and country code 'JP' was found.
Carrier with name 'WILLCOM', ID '70004', and country code 'JP' was found.
Carrier with name 'T-Mobile', ID '70030', and country code 'DE' was found.
[snip]

The dataset that the ConstantDataService exposes can now be easily updated while allowing your applications to dynamically stay up-to-date.  We do not expect the dataset to change often and we expect most changes to be additive in nature.  As a result, we strongly encourage caching this information rather than looking it up on demand.  For example, in Python, you could store this information in a pickle or a database and reuse it as necessary.

We hope you have found this post discussing the ConstantDataService and its use in obtaining Carrier and Language criteria to be informative.  If you have any questions about this service or how to use it, please post on the forum or try to attend our Google+ Hangouts with members of the AdWords API Developer Relations Team.

Kevin Winter, AdWords API Team

ACTION REQUIRED: Developer Token Required In Report Downloads Starting 11/23

We would like to announce an important change to the process of downloading reports from the AdWords API that will affect all report downloads for tools built on API versions post v13.  Currently, downloading reports costs no API units and has previously not required a developer token.  To allow us to better monitor usage of reports, we will start requiring a developer token when downloading reports.  Downloading reports will still cost zero API units.

All report downloads - whether they be AdHoc or pre-v201109, using either GET or POST - must provide the developer token as an HTTP header. Example formatting of header:

developerToken: 1a2B3c4D5e_-6v7w8x9y0z

If your application fails to provide the developer token as an HTTP header after November 23rd, it will receive the error message QuotaCheckError.INVALID_TOKEN_HEADER when downloading reports.

We will be publishing updates to the example and utility code in the client libraries to reflect this change.  Please see our report download documentation for more information regarding report downloads.  If you have any questions or would like to discuss this change, please post on the forum or try to attend our Google+ Hangouts with members of the AdWords API Developer Relations Team.

Kevin Winter, AdWords API Team

Upcoming change in the “Slot” field for reports

As part of our updates to the design and experience of Google Search and all of our other products, we are introducing new ad placements on Google Search. This will result in a visible change on the “Display Name” and “XML Attribute” values of the “Slot” field in the following reports:

• Account Performance
• Ad Performance
• Ad Extension Performance
• Ad Group Performance
• Campaign Performance
• Criteria
• Destination URL
• Keywords Performance
• Managed Placements Performance

After this change, “Display Name” will change from “Top vs. side” to “Top vs. other” and “XML Attribute” from “topVsSide” to “topVsOther”. Also all current statistics reported as “SearchRhs / Google search: Side” will get merged into “SearchOther / Google search: Other” numbers. If your reporting code relies on the “Slot” field, plan accordingly to support this change, which is scheduled to happen on November 8th. If you have any questions regarding this change please post them on the forum.

 David Torres, AdWords API Team

Client Library Updates

We have recently released new versions of the AdWords API client libraries to support v201109 and AdHoc reports.  Please see below for a summary of changes for each library.

Java

• Support for v201109 was added along with utility code for AdHoc reports in v8.4.0.
• Released reference implementation to download reports for lots of client accounts.

DotNet

• Support for v201109 was added along with utility code for AdHoc reports in v13.0.0.

Python

• Project hosting has moved here.
• Support for v201109 was added along with utility code for AdHoc reports in v15.0.3.
• Updated common module from version 2.1.0 to version 3.0.0, which may impact your code.  See the ChangeLog for more details.

Ruby

• Support for v201109 was added along with utility code for AdHoc reports in v0.4.1.
• Now properly handles xsi:type in XML responses.

Perl

• Support for v201109 was added along with utility code for AdHoc reports in v2.5.0.

PHP

• Support for v201109 was added along with utility code for AdHoc reports in v2.7.0.
• Bug fixes and minor improvements.

JavaScript

• Support for v201109 was added along with an example for AdHoc reports in v1.1.0.

You can download updated versions of the AdWords API client libraries from their respective sites, or see a list of all the client libraries.
If you have any questions or would like to discuss these changes, please post on the forum.


Kevin Winter, AdWords API Team

120 days until deprecation deadline

As we announced last month, with the release of AdWords API v201109, we will be deprecating the following versions and services:

• API versions v13, v200909, v201003, v201008, v201101*
• API version v13 AccountService will only be available on a whitelist basis.

*Note: We are not supporting cross-client reports in this release, but we have released some sample code for single account reporting across many clients.

We will be sunsetting these versions and services on February 29, 2012.

To help with the migration, we’ll be running a “Discover v201109” blog series, as well as hosting Google+ Hangouts with members of the AdWords API Developer Relations Team.

In addition, as with every new version of the AdWords API, we encourage you to review the resources in the AdWords API client libraries. If you have any questions please post them on the AdWords API forum.

Finally, we may send out periodic service announcements via email on the deprecation timeline and resources to migrate to v201109. Please be sure that your contact information is up to date in your My Client Center account. Review this blog post for more details.
 
Posted by Katie Miller, AdWords API Team

Hangout with us: AdWords API Office Hours

Google+ Hangouts have proven to be a great way to connect people and engage with an audience, something the Google Developer Relations team is very passionate about. In that spirit we’re going to start holding office hours for the AdWords API using Hangouts, the first of which will be on November 16th from 1-2PM EST (10-11AM PST). Unlike our workshop events which have agendas prepared beforehand, these office hours will be entirely focused on your questions and feedback, so please come prepared with any technical or implementation topics you’d like to discuss. With the v201109 release and the reports migration we’re confident there will be plenty to talk about.

To join the hangout you’ll need to have a Google+ account (sign up here) and the Google voice and video plugin installed (download available for Windows, Mac, and Linux). Hangouts are currently limited to ten people at a time, so if you aren’t able to join right away please try again later in the hour as a slot may have opened up. Additional information about Hangouts is available in the Google+ Help Center.

Let us know you’re planning to attend by clicking the “I’ll be there” button on the developers.google.com page for this event. We’re still deciding how often to hold office hours, so if you’d like to see more of them make sure you show your support by registering and attending. Plans for sessions in Europe and Asia-friendly timezones are also in the works, so stay tuned for more details. We look forward to talking with you face-to-face, but until then you can reach us on the AdWords API forum with any comments or questions.

- Eric Koleda, AdWords API Team

Downloading reports for lots of client accounts

Reporting has changed significantly with v201109. We’d like to take this opportunity to discuss how to download reports for lots of clients simultaneously. To download reports for a large number of client accounts, we recommend requesting the download of these reports simultaneously.

We recommend requesting no more than 10 reports concurrently and to use one thread for each concurrent download. If for some reason the report download fails, we recommend you retry after a short wait. The length of the wait should increase with the number of times the request has been tried (known as Exponential Backoff). This backoff algorithm helps prevent making too many requests to the server in a short period of time.

You should check the specific reason the download failed and only retry if it was a transient error (such as exceeding the rate limit) instead of retrying if the report definition XML was invalid. The HTTP Status of the response provides useful information:

• HTTP Status 500 indicates there is a transient server side issue and the request can be retried after a delay. We retrying no more than 5 times for any given report.
• HTTP Status 400 indicates there was a problem with the request (or the report itself) and retrying will not help.
• HTTP Status 200 means the report download was successful.

With v201109 you should use Ad Hoc reports to download new reports. With this new feature, there is no need for stored ReportDefinitions. The XML describing a Report Definition is sent directly with report download. A developer token is required, but the API call accrues no costs (report downloads are now free!).

Another benefit of downloading reports in this fashion is you get data more quickly than with legacy cross-client reports. As soon as a report download succeeds, you can start processing the data by putting it into a database or performing further logic on the results.

We hope this discussion of best practices will help you with writing report download code in the future. We’ve published a reference implementation showing how to do this in java here. If you have any questions about downloading reports, you can ask us on the forum.

Kevin Winter, AdWords API Team