AdWords API now fully supports OAuth 1.0a

With the release of v201109 we are happy to announce that we now fully support OAuth 1.0a in the AdWords API.

OAuth is an open standard for authorization. Google uses this standard to allow applications to access a user’s data (in this case AdWords) without requiring the user to give the application their Google username and password.

In OAuth, an application starts by contacting Google with an OAuth request. Next, the application redirects the user to Google to authorize the request. Once authorized, the user is directed back to the application, which can then upgrade their request token to an access token which the application can use to make requests to Google in lieu of a username and password.

The client libraries have code to handle much of the OAuth process for you. We have provided code examples in many languages to demonstrate how to use OAuth with the client libraries: DotNet, Python, Ruby, Perl, PHP.

Please note that making your first request against the sandbox using OAuth will not create accounts for you as described here. Please make your first request to the sandbox using email/password authentication to provision the sandbox accounts and make subsequent requests with OAuth.

For more information about using OAuth with Google APIs, please see this documentation.

If you have any questions about using OAuth with the client libraries, you can ask us on the forum.

Edit: the link describing how accounts are provisioned for you in the AdWords API sandbox was omitted in the original blog post.  This link has been updated and is located here.

Kevin Winter, AdWords API Team

AdWords API v201109 launch -- providing better targeting and reporting

We’re pleased to announce the launch of AdWords API v201109, which includes upgrades to targeting and reporting. We’ve highlighted some of the new features below. A complete list of changes is available in the release notes.  

v201109 highlights:

• Reporting: We have made several changes aimed at making reporting easier to use.
• Downloading reports is now free and does not require a stored ReportDefinition.
• We have added the ability to exclude zero impression rows, with an explicit flag.
• New “criteria” report lets you download all criteria data at once.
• We have added new data on call metrics.
• Geo targeting: We have been making several improvements to our location targeting services and are launching these in the API. We have created a new LocationCriterionService to look up geo criteria. And we have moved all geo targeting to the CampaignCriterionService. 
• Device targeting: In May we launched the ability for advertisers to target users on tablets in our web interface. We have now added this tablet device targeting option to the API. We have also updated the available list of O/S and carrier targets. 
• Asynch and Other: We have enhanced or updated several other existing features.
• The new MutateJobService allows for the scheduling of large batch updates as asynchronous jobs. This service simplifies mutate jobs submissions and will eventually replace BulkMutateJobService.
• We have added support for negative keywords feature in TrafficEstimatorService.
• We have enabled PartialFailure for AdGroupAdService.
• We no longer support email addresses as identifiers, please use Customer IDs instead.

Deprecation timeline for previous versions With the release of v201109, the following versions and services will be deprecated:

• API versions v13, v200909, v201003, v201008, v201101
• Please note: We are not supporting cross-client reports in this release, but we have released some sample code for those of you who need to run reports across many clients.
• API version v13 AccountService will only be available on a whitelist basis.

We will be sunsetting these versions and services at the end of February 2012. 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.

Posted by the AdWords API Team

Using AWCLI (AdWords Command Line Interface)

Earlier this year we released a demo that allows you to run AdWords API queries from the command line. Today, a new version is available and I’d like to point out some of its features.


Accessing production environment

We’ve made a change to reduce a risk of accidentally running the demo tool against a production environment. Since version 1.2.0, an explicit ‘--prod’ flag is required in order to query billable services. Check out ‘awcli --help’ for all available command-line options.


Automatic batch mode

AWCLI can now run in interactive or batch mode and detects the required mode automatically. In interactive mode, you will get a prompt to type your commands:

awcli:/>

In batch mode, any extra input is suppressed and the application exits after a command completes. This makes it easier to use the tool in shell scripts:

bash $ echo ls | ./awcli.sh
    #1 Campaign Name [69266990]
    [...]
bash $

You can also specify a command and its parameters as extra arguments to the tool itself:

bash $ ./awcli.sh --prod ls 69266990
    #1 AdGroup name [2390064350]
    [...]
bash $

Browsing Ad Parameters

A new CriterionLocation was added which allows you to browse Criteria. This enables you to list and view AdParams associated with your criteria:

bash $ ./awcli.sh [options] ls <campaign_id>/<adgroup_id>/<criterion_id>
    #1 $100 [1]
    #2 50 [2]
bash $

...and even edit them: 'edit #1' will spawn your configured editor. The changes will be automatically applied when you save and exit.


Querying stats

You can combine AWCLI output with other command-line tools to retrieve parts of the information you need. For example, you can use Unix filters to obtain ad group stats:

bash $ ./awcli.sh --prod cat <campaign_id>/<adgroup_id> | grep -E "clicks|impressions"
        clicks = 12,
        impressions = 160,
bash $

Getting AWCLI

AWCLI is available from the Google Code page and is part of the AdWords Java API client libraries project. You can find installation and running instructions as well as usage examples on the wiki page. Please join us to discuss the tool and report any issues on the project page or forum.


Danial Klimkin, AdWords API Team.

Announcing the next AdWords API Workshops in October / November

The Google Developer Relations team will be holding their next series of semi-annual AdWords API Workshops in October and November. These workshops will focus on new and upcoming features in the AdWords API, as well as best practices for special topics.

We invite you to join us for our next AdWords API Workshops which will be hosted in the following cities:

• London, October 17th
• San Francisco, October 18th
• Hamburg, October 19th
• Amsterdam, October 21st
• New York City, October 25th
• Tokyo, November 8th - New Location added this year
• Singapore, November 11th - New Location added this year

In addition to presenting technical deep-dives on the topics listed below, we will also have the team on-hand to answer all your API-related questions, and also plan to give attendees a sneak peak and an opportunity to beta test a new programming feature being rolled out in the AdWords Frontend.

Workshop topics include:

• Report Service Updates
• AdWords API Authentication & Authorization Updates
• Efficient API Usage with the Simplified Mutate Job Service
• Campaign Targeting Changes
• Mobile Best Practices

All events will have the same agenda, and will run from approximately 10:00AM - 3:00PM (local time). These workshops are geared towards software engineers who are already familiar with the AdWords API. Each session will focus on writing code and there will be no non-technical track.

For more information and to register, visit: http://sites.google.com/site/awapiworkshops/home.

-- Sumit Chandel, AdWords API Team

Client Library Updates

We have recently made the following changes to the AdWords client libraries.

Ruby

• Made performance improvements.
• Added unit spend information to responses.
• Added support for Proxy servers.

Python

• Updated common module to version 2.1.0, which may impact your code. See the ChangeLog for more details.
• Fixed issues 161, 162, 163 in version 14.2.3.
• Added a tarball in the download section that collects all the required modules for this client library into a single download with an installer script.

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

Resolving Conflicts after Google Apps Account Migration

Recently, we have migrated the Google Apps accounts to a new infrastructure that includes all Personal Google accounts. This has introduced a conflict for API users who have the same email address for both types of accounts. As a result, you will not be able to generate a ClientLogin token and will be presented with an error message such as “Either this object does not exist, or this user does not have permission to access it”, “Invalid client email specified” or an AuthenticationError.CLIENT_EMAIL_INVALID in the SOAP response. You can also verify whether your account is in conflict by making a request directly to the Client Login API.

Request:
https://www.google.com/accounts/ClientLogin?accountType=GOOGLE&Email=my_email_address&Passwd=my_password

Response:
Error=Unknown
Url=https://www.google.com/accounts/ErrorMsg?Email=my_email_address&service=gam&id=unknown

Before the migration, it was possible to have a Google Apps account with your domain (jane@altostrat.com) and a Personal Google account for AdWords, Picasa, Reader, etc. with the same email address. With the new infrastructure, both types of accounts are in one unified system so when you try to generate a ClientLogin token with jane@altostrat.com, we do not know which account you are trying to use. More details about conflicting accounts can be found at the Google Accounts Help Article.

To differentiate between your conflicting accounts, we have created a temporary account (jane%altostrat.com@gtempaccount.com) for you to temporarily hold your data. You can log into http://www.google.com/accounts with your gtempaccount and use the wizard to resolve your conflicts. A full walkthrough on the data migration wizard can be found at the Data Migration Getting Started Guide.

Please note that this issue will only affect tools built using clientEmail as a header to identify accounts. If you use clientCustomerId, the tool will not be affected. We recommend using clientCustomerId instead of clientEmail as a best practice.

As always, please post any questions to the forum.

Kevin Winter, AdWords API Team

Tablet Targeting in v201101

Last month the device targeting options in AdWords were expanded to include new settings for tablets.  Previously tablets had counted as mobile devices, with the iPad listed as one such device.  The AdWords API worked the same way, using the PlatformTarget HIGH_END_MOBILE for both mobile devices and tablets and the MobilePlatformTarget "iPad" for the iPad specifically.  Representing these new tablet settings in the current v201101 version of the API is tricky, and in this blog post we’ll cover the behavior you can expect.

The first thing to note is that there is no PlatformTarget that represents tablets, since enum values can’t be added to an existing version.  You can look at the MobilePlatformTargets returned to get a better idea of what’s being targeted, but be aware that the meaning of some of the values have changed.  Specifically, the value "iPad" now represents any tablet, and the value "iPhone" represents any iOS device.

The tables below show the PlatformTargets and MobilePlatformTargets returned for every combination of device and operating system that can be set in the UI.

	Computers	Mobile	Tablets
Android	DESKTOP (None)	HIGH_END_MOBILE Android	HIGH_END_MOBILE Android, iPad
iOS	DESKTOP (None)	HIGH_END_MOBILE iPhone	HIGH_END_MOBILE iPhone, iPad
webOS	DESKTOP (None)	HIGH_END_MOBILE Palm	HIGH_END_MOBILE Palm, iPad
All	DESKTOP (None)	HIGH_END_MOBILE (None)	HIGH_END_MOBILE iPad

	Computers & Mobile	Computers & Tablets	Mobile & Tablets	All
Android	(None) Android	DESKTOP Android, iPad	HIGH_END_MOBILE Android, iPad	(None) Android, iPad
iOS	(None) iPhone	DESKTOP iPhone, iPad	HIGH_END_MOBILE iPhone, iPad	(None) iPhone, iPad
webOS	(None) Palm	DESKTOP Palm, iPad	HIGH_END_MOBILE Palm, iPad	(None) Palm, iPad
All	(None) (None)	DESKTOP (None)	HIGH_END_MOBILE (None)	(None) (None)

As you can see there are certain states in the UI that appear identical in the API. This is unfortunate behavior that is due to the limited values available in the current version of the API.  Specifically, it’s not possible to distinguish:

1. Tablets vs. Mobile & Tablets
2. Mobile with all operating systems vs. Mobile & Tablets with all operating systems
3. Computers vs. Computers & Tablets with all operating systems
4. Computer & Mobile with all operating systems vs. All devices with all operating systems

Likewise, using these values in a mutate request may inadvertently change the targeting options of the campaign since the system will always apply the broadest targeting that matches the input.  For example, let’s say you have a campaign that was configured in the AdWords web interface to target just Android tablets.  If you called CampaignTargetService.get() you would get back the PlatformTarget "HIGH_END_MOBILE" and the MobilePlatformTargets "Android" and "iPad".  If you then call CampaignTargetService.mutate()using those same values, the campaign will be updated to target both tablets and mobile devices that run Android.

What this means is that there are certain targeting combinations that can’t be determined or applied accurately in the v201101 version of the API.  In the next version of the API we plan to update these target types to support the new tablet settings, which will make reading and writing these combinations much simpler.  As always, if you have any questions about this topic you can reach us on the AdWords API forum.

- Eric Koleda, AdWords API Team