Say hello to your new one-stop shop for ads developer news

Monday, November 21, 2011


When we originally launched this blog in 2005, we sought to provide you with the most up-to-date information on the AdWords API, as well as useful resources to help with API development. Recently, we’ve realized that the content we produce can be shared between multiple Ads API developer communities and for this reason we have decided to create one central blog. With this in mind, we'll now be posting on the new Google Ads Developer blog. There, you'll also find information on our AdSense API, DoubleClick for Publishers API, DoubleClick for Advertisers API, and Google AdMob SDK products.

If you’re a subscriber of this blog, your feed will automatically be redirected, so you won't have to do a thing to keep getting the latest news. If you decide you'd like to subscribe to a particular label on the new blog (for example, only receive those posts labeled as "adwords_api"), you can choose to do that as well. Also, the old content of this blog is not going anywhere and will continue to be available, even after we switch to the new blog.

The Ads Developer blog will continue to be run by the same team, bringing you all the information you need as an ads developer. We look forward to seeing you over at http://googleadsdeveloper.blogspot.com/.

Posted by the AdWords API Team

Discover v201109: Filtering on Criterion type

Wednesday, November 16, 2011


We’ve noticed a popular question in the forum: “How do I retrieve criteria of a specific type via the API?”. Previously, there was no straightforward way to filter by the criterion type on the server side and the only workaround was to retrieve all criteria and process the list on the client side.

In v201109 we introduced a new filterable field called CriteriaType to the Criterion object. For example, the following request will return criteria of types ‘KEYWORD’ and ‘PLACEMENT’ only:
<get>
  <serviceSelector>
    <fields>Id</fields>
    <fields>CriteriaType</fields>
    <predicates>
      <field>CriteriaType</field>
      <operator>IN</operator>
      <values>KEYWORD</values>
      <values>PLACEMENT</values>
    </predicates>
  </serviceSelector>
</get>

You can find out the list of available criteria types in the documentation.

We hope this enhancement will make it easier to work with criteria. Please visit the forum or join our Google+ Hangout today if you have any questions regarding this change.

Danial Klimkin, AdWords API Team.

Discover v201109 - AdHoc Reports

Tuesday, November 15, 2011


AdHoc reports is one of the new features we introduced in v201109 of the AdWords API. AdHoc reports are free, synchronous and don’t require a stored report definition. This blog post explains this new feature and covers the best practices.

Downloading the report

AdHoc reports utilizes plain HTTP POST requests to generate reports synchronously from the AdWords API server. A raw HTTP request to download the reports is shown below:

POST /api/adwords/reportdownload/v201109 HTTP/1.1
HOST: adwords.google.com
clientCustomerId: XXX-XXX-XXXX
Content-Type: application/x-www-form-urlencoded
developerToken: XXXX
Authorization: GoogleLogin auth=XXX
returnMoneyInMicros: true
Content-Length: XXXX


__rdxml=URL_ENCODED_DEFINITION_XML

As shown, the report is downloaded by making a POST request to https://adwords.google.com/api/adwords/reportdownload/v201109. The clientCustomerId header specifies the client for which this report is being run. The Authorization header contains the authorization information for downloading the report. If you are using ClientLogin as the authorization method, this header takes the form
Authorization: GoogleLogin auth=AUTH_TOKEN_HERE
If you are using OAuth, the header takes the form
Authorization: OAuth OAUTH_SIGNATURE_HERE
The returnMoneyInMicros header tells the server whether to return money values in micros or not. This is true by default; if set to false, money values are downloaded in actual currency format. The developerToken header contains your AdWords API developer token. The Report Definition is written in XML format and is provided in the __rdxml parameter of the POST body. The request should be encoded in application/x-www-form-urlencoded or multipart/form-data format.

You may also use the GET method instead of POST to download reports by sending your request to https://adwords.google.com/api/adwords/reportdownload/v201109?__rdxml=URL_ENCODED_REPORT_DEFINITION_XML with the same headers as in the POST example. However, we recommend using POST over GET since GET requests are more likely to incur URL length limit errors.

Creating definition xml

A Report Definition corresponds to the serialized form of the ReportDefinition type. For instance, a Report Definition that downloads an AdGroup performance report for the last 7 days in CSV format would look like this:

  <reportDefinition>
    <selector>
      <fields>CampaignId</fields>
      <fields>Id</fields>
      <fields>Impressions</fields>
      <fields>Clicks</fields>
      <fields>Cost</fields>
      <predicates>
        <field>Status</field>
        <operator>IN</operator>
        <values>ENABLED</values>
        <values>PAUSED</values>
      </predicates>
    </selector>
    <reportName>Custom Adgroup Performance Report</reportName>
    <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
    <dateRangeType>LAST_7_DAYS</dateRangeType>
    <downloadFormat>CSV</downloadFormat>
  </reportDefinition>

Details about the supported report types and their field are available at http://code.google.com/apis/adwords/docs/appendix/reports.html.

Error codes

When downloading AdHoc reports, the AdWords API server responds with HTTP code 200 and report in the response body. In case of an error, one of the two different HTTP response code may be returned:

1. HTTP Status code is 400: This error occurs when the AdWords API server throws an API error. When this happens, the error message will be returned in the server response body. You need to examine your report definition XML and server response body and fix any errors before retrying the call. The response body would look like

!!!2|||-1|||Error message here???

An easy way to parse the error message is to match it against the regex pattern "\!\!\!([^\|]*)\|\|\|(.*)"

2. HTTP Status code is 500: This error implies that the server faced an issue while generating the report. Chances are that this is a temporary error and may go away if you retry the call after waiting for 30 seconds. However, if you get this error even after five retries, you should skip the download and report the issue on the forum.

Using the client libraries

All of the client libraries support AdHoc reports, and takes care of details like making requests with the right HTTP headers and encoding, constructing authorization headers, handling the HTTP response codes, etc. For instance, the DownloadAdHocReports.cs code example shows how to download AdHoc reports using AdWords API .NET library:

Support for cross-client reports

As mentioned in an earlier blog post, AdHoc reports do not support cross-client reports. If you wish to run reports against many clients, you can refer to this blog post for details.

We hope this blog post will help you use this new feature effectively. As usual, If you have any questions about downloading reports, you can ask us on the forum or our upcoming live Hangouts with the Developer Relations team.

  --Anash P. Oommen, AdWords API Team

UPDATE2: Developer Token Required In Report Downloads

Monday, November 14, 2011


A little over a week ago we published a blog post informing developers that we would begin requiring a developer token with report downloads to better allow us to monitor reports, and extended the deadline in an update. We are changing the deadline to Tuesday January 17th, 2012 to give our developers more time during the busy holiday season.

As mentioned in our prior update, the sandbox will still have this change as of November 16th. We strongly encourage you to use the time between November 16th and January 17th to make the change to your applications, test against the sandbox and move the change to production. The existing production report download will ignore the header until it is required, which means you can implement the changes before the deadline without it breaking your existing applications.

We will update the client libraries to help you implement this change before the November 16th change in the sandbox environment. 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.

, AdWords API Team

Discovering v201109: How to target Campaigns

Friday, November 11, 2011


With the introduction of v201109 we’ve made some changes in the AdWords API with regards to targeting campaigns.  This blog post will discuss these changes in detail.

From CampaignTargets to Criterion

Targeting campaigns in v201109 is now accomplished via the CampaignCriterionService. Previously, the CampaignTargetService had a large number of CampaignTargets that could be used to better direct who saw your ads. For v201109, almost all of these targets have been transformed into Criterion objects and moved to the CampaignCriterionService.

Some of these criteria can only be targeted (CampaignCriterion) or only excluded (NegativeCampaignCriterion).  The individual criteria are documented as to whether they are targetable-only or excludable-only on their individual documentation pages.  The table below shows a comparison between the old CampaignTargets and their respective Criterion as well as whether they are Targetable-only, Excludable-only or both.




A rose by any other name (or ID)

Please note that except for Proximity Criteria, we have changed all these targeting criteria to work with IDs instead of names.  This allows us to update the text of display values without requiring developers to change their applications.  Below is an example of the old and new ways to represent LanguageTarget/Language.

Old
<targets>
 <Target.Type>LanguageTarget</Target.Type>
 <languageCode>en</languageCode>
</targets>

New
<criterion xsi:type="Language">
 <id>1000</id>
 <type>LANGUAGE</type>
 <Criterion.Type>Language</Criterion.Type>
 <code>en</code>
</criterion>



Note that the “New” example shows the Language Criterion as it would be returned by the API.  When sending the value to the API, you only need to specify id and xsi:type, all other fields are ignored and read-only and documented as such.

We hope this blog post helps you as you update your application with the new Campaign Criteria.  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.

, AdWords API Team

Discover v201109: Changes to accounts identification

Thursday, November 10, 2011


The AdWords API allows you to manage a large number of accounts using a single login credential set. In order to determine which account to run a query against, a customer identifier is required.

Previously we allowed the use of either client email address or client customer ID as account identifier. Using email addresses does not handle a number of situations, though, such as address change, multiple accounts associated with one email and others. In addition, AdWords accounts created with no email address are just not accessible by this identifier.

In order to unify account identification we decided to remove support for email addresses as account identifiers starting with v201109. From this version onward only client customer IDs are supported by the AdWords API.

Migrating to client customer ID

Most applications managing more than one AdWords account hold account identifiers in some form of a local storage. In case your application uses client email addresses as identifiers, you will need to convert those to client customer IDs, or add an extra field for the IDs.

In order to make this migration smoother, we’ve provided an example that demonstrates how to obtain a client ID for a given email address. This example is included in every client library and also available online.

It is easy to change how you identify a client account when making API requests if you use our client libraries. Depending on the language you use, you will need to update the configuration file or constructor parameter to include clientCustomerId instead of clientEmail. In case you construct your queries manually, please refer to the SOAP headers documentation page for more details.

We would like to remind you that all existing versions that support identification by email addresses are scheduled for shutdown in Feb 2012.


Please join us on forum or in our upcoming Google+ Hangouts if you have any questions regarding this change.

Danial Klimkin, AdWords API Team.

UPDATE: Developer Token Required In Report Downloads

Tuesday, November 08, 2011


Last Thursday we published a blog post informing developers that we would begin requiring a developer token with report downloads.  Due to developer feedback regarding the proposed date being so close to the upcoming Thanksgiving holiday in the US, we are changing the deadline to Tuesday November 29th.

We’d also like to clarify two additional points:

  • We will start requiring the developer token as an HTTP header for report downloads in the sandbox as of November 16th.  This will allow developers to make requests with the developer token as an HTTP header to ensure their application will continue to function as expected when the production server begins requiring the developer token.
  • While the production service will begin requiring the developer token on November 29th, you can provide this HTTP header today and the server will still accept the request.  This means you can add the developer token in advance of the deadline without fear that report download functionality will be interrupted.
We will update the client libraries to help you implement this change before the November 16th change in the sandbox environment.  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.

, AdWords API Team

Discovering v201109: ConstantDataService

Monday, November 07, 2011


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.

, AdWords API Team