AdWords API Version 13 Now Available

We're happy to announce the release of the AdWords API version 13 (v13)! V13 introduces several changes to the AdWords API; we've highlighted the main points below. For a complete list of v13 changes, please see our release notes.

V13 Highlights

• New geotargeting options: Target multiple geographic levels (countries, regions, metro areas, and cities) within a single campaign, target specific regions of multiple countries in a single campaign, and setup negative targeting for specific regions (for example, target the United States with the exception of Alaska).
  
• New reports: Generate Search Query Performance and Geographic Performance reports using ReportService and DefinedReportJob.
  
• Mobile image ads: Use the new MobileImageAd ad type to create graphical advertisements for the mobile content network.
  
• Suggested campaign budgets: Retrieve budget suggestions for your campaigns with getRecommendedBudgetList.
• Active campaigns and ad groups: Want to retrieve only your active campaigns and ad groups? Now you can, using getActiveAdWordsCampaigns and getActiveAdGroups.
  
• Quality-based bid and Quality Score support: We've added two new Keyword fields:
• firstPageCpc (first page bid estimate)
• qualityScore (Quality Score of the keyword)

V12 Sunset in 2009

Per our versioning policy, v12 will be supported for four months from today, after which time it will be turned off. Therefore, please make sure that you upgrade to v13 before February 20th, 2009. As with every new version of the AdWords API, we strongly encourage you to review the Release Notes section of the Developer's Guide to learn more about this version.

Happy Holidays! Enjoy more API units

We know the holiday season is a busy time for advertisers and often means a number of updates to your campaigns. We'd like to help out by providing you with more API units.

Starting now and extending through January 15th of next year, all developers will receive a bonus of 20% more API units at no additional cost. 

• All developers can purchase API units at the rate of 1200/$0.25, up from 1000/$0.25, from now through January 15th, 2009.
• Advertisers who are eligible for free API units will receive credit at the rate 300/$ of AdWords spend, up from 250/$ of AdWords spend. They will be credited the holiday bonus based on their spend in previous months.

You can view your API quota in your MCC account, by clicking the My Account link under the AdWords API Center tab.

As always, we encourage you to use the API as efficiently as possible. For instance, we recommend using list methods (e.g. addCampaignList) whenever appropriate because they're the most cost-effective way to process large data sets. See our blog post on efficient software to learn other ways to get more out of your API units. For more general API best practices, see our previous post dedicated to just that topic.   

Happy Holidays,
-Adam Wooley, Product Marketing

AdWords Downtime: October 18, 10am-2pm PDT

We'll be performing routine system maintenance on Saturday, October 18 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Cheers,
-Jeffrey Posnick, AdWords API Team

Common issues that lead to SOAP faults (Part V)

Welcome to part 5 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In our previous episode, we discussed SOAP errors related to failed validations. Today we'll discuss SOAP errors related to syncing errors and concurrent changes. You can find links to our earlier posts here: Part 1, Part 2, Part 3, Part 4.

Syncing Errors

Some of the common ApiErrors are "Missing a required field", "Wrong value for a field", etc. They are often self-explanatory, so it's easy to spot the error. However, two errors are trickier to spot:

 

• The client asked us to load an entity but no entity with that ID was found. (Error code 5)

• The client does not have permission to perform the requested operation. (Error code 4)

Both these errors occur among developers who store their AdWords campaigns, ads, etc. in a local database. While storing your campaigns and ads in local database helps to boost performance in your application (and at times help  integration with other campaign management systems), your local database might be out of sync with your AdWords account for several reasons, which would cause these errors.

Common causes of your database being out of sync with your account are that the client updated some campaigns using the AdWords website, or that you have a bug in the code that's inserting the wrong records into your local database.

Both the ApiErrors mentioned above take more specific forms, and the detail, field, and trigger properties of the ApiError node should help you find out the cause behind the issue. For example, the following SOAP fault was generated while trying to update a Campaign that does not exist (Campaign ID: 0):

 

<soapenv:Body>
  <soapenv:Fault>
    <faultcode>soapenv:Server.userException</faultcode>
    <faultstring>One or more input elements failed validation.</faultstring>
    <detail>
      <ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v12">
      <ns1:code>122</ns1:code>
      <ns1:message>One or more input elements failed validation.</ns1:message>
      <ns1:errors>
        <ns1:index>0</ns1:index>
        <ns1:field>campaignId</ns1:field>
        <ns1:trigger>0</ns1:trigger>
        <ns1:code>5</ns1:code>
        <ns1:isExemptable>false</ns1:isExemptable>
        <ns1:detail>No Campaign with this ID was found.</ns1:detail>
      </ns1:errors>
    </ns1:fault>
   </detail>
  </soapenv:Fault>
</soapenv:Body>

Note how the error took a specific form (Error code = 5, detail = No campaign with this id was found, field = campaignId, trigger = 0).

Similarly, the SOAP fault shown below was generated while trying to retrieve a Campaign (Campaign ID : 111111) that my MCC doesn't have access to.

 

<soapenv:Body>
  <soapenv:Fault>
    <faultcode>soapenv:Server.userException</faultcode>
    <faultstring>Either this object does not exist, or this user does not have permission to access it.</faultstring>
    <detail>
      <ns1:fault xmlns:ns1="https://adwords.google.com/api/adwords/v12">
        <ns1:code>4</ns1:code>
        <ns1:message>Either this object does not exist, or this user does not have permission to access it.</ns1:message>
        <ns1:trigger>111111</ns1:trigger>
      </ns1:fault>
    </detail>
  </soapenv:Fault>
</soapenv:Body>

Concurrent Changes

 

Finally, if you are writing multithreaded applications, or if multiple persons are using your application at the same time, you may come across the error "The Attempted modification failed due to changes made concurrently by another agent or user. (Error code 58)." To avoid this error, make sure your applications are properly synchronized, so that no two threads/instances of your application modifies the same campaign, ad group, ad, etc. at the same time.

 

You could also run into this error if two programs are modifying the same campaign, ad group or ad at the same time. For example, you could run into this error if 2 people are modifying the same campaign, ad, etc. using the AdWords Front End and AdWords Editor, or even 2 instances of your Application.

Debugging SOAP faults can be frustrating sometimes. We hope these tips will help you in figuring out common issues and save time for something that is more fun -- coding!

--Anash Oommen, AdWords API Team

 

Common issues that lead to SOAP faults (Part IV)

Welcome to part 4 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In our previous episode, we discussed possible causes for "operation does not exist" errors. Today we'll discuss SOAP errors on failed validations. You can find links to our earlier posts here: Part 1, Part 2, Part 3.

Failed Validation

A more generic error is "One or more input elements failed validation. (Error code 122)". In this case, the detail field of the response will contain a sequence of ApiError elements itemizing the validation errors found. The following fields may be specified:

 

• index: indicates the index of the element in the input array that caused the violation
• code: indicates the type of violation
• field: the input element field name that contains the violation
• trigger: a string describing the violation that triggered the error
• isExemptable: a boolean indicating whether it is possible to get an exemption for this kind of violation or not. The default is false
• textIndex: where in the text the violation occurred
• textLength: the length of the string that caused the violation
• detail: why the violation occurred

 

A common error that falls under this category is an Ad Policy violation. You receive an "The text specified for this Creative violates Google policy. (Error code 21)" error if you try to add an Ad that does not comply with Google’s Ad policy. To avoid getting this error, make sure that you check your Ads for policy violation using checkAds() before adding Ads using addAd(). If an Ad violates a policy, then checkAds() will return a sequence of ApiError objects that describe the policy violation. You can examine the details field to check what caused the policy violation. Also, some policy violations may be exemptable, and the isExemptable will be set as true if a policy violation is exemptable. If set, you can request for a policy exemption while adding this Ad.

Next time, we will explore errors that arise while syncing accounts, or performing concurrent requests to AdWords API.

 

--Anash Oommen, AdWords API Team