Understanding Ad Group Bidding Options

Managing your bids is crucial to running a successful AdWords campaign. The AdWords API offers developers control over all aspects of their bidding strategy, but the variety of options available can be daunting. To add to this, AdWords added support for mixed keyword and website criteria within the same ad group several months ago. In the interest of answering some common questions, here are a few ad group structures and the way to implement them using the AdWords API.


CPC bidding

Getting the right setup

The AdWords API can be used to manage both keyword and website criteria within the same ad group. However, you do need to make sure your ad groups are properly configured before they'll accept both those criteria types. In order for your ad group to accept keyword criteria, it must have its keywordMaxCpc and/or keywordContentMaxCpc attributes set to your maximum CPC bid. In order for your ad group to accept website criteria, the siteMaxCpc attribute needs to be set as well. Failing to have a value set for siteMaxCpc is a common cause of SOAP errors of type 74 while trying to add website criteria to an existing ad group. In fact, a misleading message may appear: "This criterion type is invalid. Acceptable values are 'Website' and 'Keyword'.  Websites and keywords may not be used in ad groups in the same campaign." Rest assured, the spelling of "Website" did not change overnight. You may just need to set your siteMaxCpc value.

Which bid gets triggered?

Although controlling both keywords and websites within the same ad group adds a new range of possibilities for campaign structure, it can be confusing as to which bid will be triggered under different situations. This information is available in this article in the AdWords Help Center but it helps to visualize a few common scenarios.

For the following examples, let's suppose that we have added the keywords "Mars" and "rover" as well as the website "nasa.org" to our ad group. In our campaign we have set the bidding strategy to CPC and have enabled our ads to appear on Google search, Search partners, and Relevant pages across the entire network.

• A user searches for the phrase "Mars rover" within Google or on one of Google's search partners. AdWords will always use the keywordMaxCpc bid to determine if your ad should be placed.

• A user visits NASA's new Mars rover website with nasa.org as the domain. In this case, because you have nasa.org as one of your Website criteria, the bid will be either be the siteMaxCpc value from the ad group or the maxCpc from the Website criteria. If there's a maxCpc value defined in the criteria, then it will take precedence. Even if this website would trigger the keywords in your ad group, the placement-related bidding values will always take precedence as they're considered more specific.

• A user visits the Mars rover's manufacturer's website, which happens to be on the content network (i.e. it is an AdSense enabled website). The keyword criteria "Mars rover" is what ends up triggering the ad. In this case, AdWords will first check the maxCpc value set for the keyword that triggered the ad, if this is not set, the keywordContentMaxCpc value from the ad group will be used. If keywordContentMaxCpc is not set, it will use the keywordMaxCpc value. It will not under any circumstance use the siteMaxCpc value.

(By the way, if you're curious about which bid will get used if an ad is triggered by both a keyword and a website in the same ad group, it will always be the bid associated with your website.)


CPM bidding

If you've set up your campaign for CPM bidding (because you'll be running image or video ads on the Content network, and not text ads on the Search network), then the only relevant ad group bid setting to configure is siteMaxCpm. This simplifies setup considerably compared to the options available when you're using CPC bidding.

You can add both keyword and website criteria to the same ad group, and the siteMaxCpm bid will always be used when determining what you're willing to bid for each impression your ad receives.

Both keywords and website criteria will be able to trigger your ad in the Content network, with the caveat that your keyword criteria won't generate any impression or click-related statistics when used to trigger ads in the Content network.

--Adam Rogal and Jeffrey Posnick, AdWords API Team

AdWords Downtime: November 8, 10am-2pm PST

We'll be performing routine system maintenance on Saturday, November 8 from approximately 10:00am to 2:00pm PST. 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

v13's New Keyword Search Volume Info

AdWords API v13 ushered in a number of great new features, like exposing keyword quality score information, new report types, and support for more geo-targeting options. There is an additional new feature that received somewhat less fanfare, though: starting with v13, the getKeywordVariations() method of the Keyword Tool Service returns information about the average and last month's search volume for each suggested keyword variation. Ever since this feature was rolled out in the standalone Keyword Tool web page in July we've been hearing requests from developers eager to get that sort of information from the AdWords API, so we thought it would be worthwhile to explain how you can now retrieve similar data from your own code.

Let's say you're considering adding the keyword new york to one of your ad groups, and you're curious about what kind of search volume that keyword normally receives. You're interested in data pertaining to English-language queries in the United States and Canada, and you want data about that exact keyword--not any of its synonyms. In order to retrieve that search volume data, the following SOAP request body would be appropriate:

  <Body>
    <getKeywordVariations>
      <seedKeywords>
        <negative>false</negative>
        <text>new york</text>
        <type>Broad</type>
      </seedKeywords>
      <useSynonyms>false</useSynonyms>
      <language>en</language>
      <countries>US</countries>
      <countries>CA</countries>
    </getKeywordVariations>
  </Body>

If you make that SOAP request to the AdWords API v13, you'll get a (large) number of results back--around 200 potential variations on the keyword new york, like new york hotels or brooklyn new york. Each variations will have its own set of search volume data associated with it, and that data is all potentially useful. For the purposes of this example, though, what we're interested in is seeing the search volume data for our seed keyword of new york. Your original seed keyword(s) will always be included in the results you get back from getKeywordVariations(), so your code can loop through the results until it finds the one that matches your original request. In this case, the XML for the result entry looks like:

  <moreSpecific>
    <text>new york</text>
    <language>en</language>
    <advertiserCompetitionScale>5</advertiserCompetitionScale>
    <avgSearchVolume>68000000</avgSearchVolume>
    <lastMonthSearchVolume>83100000</lastMonthSearchVolume>
  </moreSpecific>

So now we know, that over the past twelve months, the average monthly search volume for the keyword new york was 68,000,000 queries, and last month the search volume made it all the way up to 83,100,000 queries. New York is a popular town!

Hopefully the additional data returned by the getKeywordVariations() method in AdWords API v13 will make it even easier to target and optimize your AdWords campaigns.

--Jeffrey Posnick, AdWords API Team

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