Documentation for the requested version is not available.Documentation for the requested diff is not available.
This topic provides in-depth information about each of the AdWords API web services. For more general information about AdWords API, see the Introduction.
The AdWords API web services logically fall into two categories:
Use these web services to edit your AdWords campaigns and associated data. CampaignService, AdGroupService, AdService, and CriterionService are considered campaign data services.
Use these web services to manage your AdWords account and to assist you in intelligently editing your campaigns. AccountService, InfoService, KeywordToolService, ReportService, SiteSuggestionService, and TrafficEstimatorService are considered utility services.
CampaignService, AdGroupService, CriterionService and AdService are collectively known as the campaign data services. Use these services to manage campaigns, ad groups, criteria, and ads. Each service provides operations that pertain to the relevant entity as a whole, for example, CampaignService has functions for campaign-wide operations.
Campaigns contain ad groups; ad groups contain criteria and ads. Wherever possible, operations on an entity are supported by that entity's service instead of the parent entity's service. For instance, you use CampaignService to add campaigns, AdGroupService to add ad groups, CriterionService to add criteria, and AdService to add ads.
The campaign data services provide most operations in two forms: one for a single operation and one for a batch operation. For example, CampaignService provides the getCampaign operation for getting an individual campaign and the getCampaignList operation for getting multiple campaigns. Using a batch operation is more efficient than multiple calls to a single operation, so you should use batch operations wherever possible.
Each of the campaign data services performs operations on a corresponding data object:
|
CampaignService uses Campaign objects.
AdGroupService uses AdGroup objects.
AdService uses ad objects.
CriterionService uses Keyword and Website objects.
When sending a request to a service, you usually need to create the corresponding data object, or a list of data objects, and send it to the service. Each higher-level data object has several fields associated with it. Each field falls into one of the following categories:
adGroupId is required when creating a Keyword)
Campaign.name),
AdGroup.id).
Keyword.text).
Keyword.maxCpc).
The API Reference section describes which fields are required, optional, set once, immutable, or modifable.
Campaign, AdGroup, Criterion, and Ad objects all have IDs that are set by the AdWords API web services. Ad IDs are unique only within their ad group, while AdGroup, Criterion, and Campaign IDs are globally unique.
Throughout the AdWords API, money values are always specified in terms of micros, which are millionths of the fundamental currency unit. The data type for micros is a 64-bit long.
For US dollars, $1 is 1,000,000 micros. Note that bids are restricted to billable units; in US dollars, all bids must be multiples of 10000 micros (one cent).
To guarantee that keywords and ads are effective, Google has established a set of advertising policies (available at https://adwords.google.com/select/guidelines.html). Some of these policies include correct spelling, no excessive punctuation (such as Great Deals!!!!), and no superlatives (such as best, fastest and cheapest). Ads and keywords that violate the Google advertising policies are usually disapproved and not served.
The AdWords API checks for such editorial policy violations. If you try to submit an ad that violates the published policies, the request fails. A single violation will cause the entire operation to fail. For example, if you submit a batch of a hundred ads, and just one ad violates the published policies, then none of the ads are submitted.
If submitting an ad fails, the returned error will describe the cause of the failure, including what triggered the violation, the reason for the violation, and (if applicable) which element in the input array caused the violation.
If the returned error also contains an isExemptable field set to true, you can request an exemption from the policy your ad violated. To do this, resubmit your ad or keyword with your reason for exemption specified in the exemptionRequest field. You should only request an exemption if you have a valid reason (such as your advertised product's name containing multiple exclamation points!). Specifying the exemptionRequest field prevents the policy violation from causing an error, but does not guarantee that the ad will ultimately be approved.
Specifying an unnecessary exemption request will cause any add or update operation to fail. Only use the exemptionRequest field if your ad or keyword violates policy.
Requests that fail due to policy violations are considered to be user error and are charged against your token.
Errors not caused by policy violation can never be circumvented by an exemption request. For example, if you try to add a keyword longer than 80 characters, the returned error will always have isExemptable set to false.
View the API Reference
This web service lets you access, create, list, and modify campaigns and perform campaign-wide operations such as pausing a campaign. A campaign contains one or more ad groups. Operations that pertain to ad groups are handled by AdGroupService.
Keyword targets and placement targets are specified as Criterion, as discussed in the section CriterionService.
A campaign is represented by a Campaign data structure that has fields describing the campaign, such as startDay, endDay, name, status, and budgetAmount. To use CampaignService, you send requests that pass in or return a single Campaign data object or an array of them.
To create a campaign, construct a Campaign data object and set its required and optional fields, as described in CampaignService.addCampaign.
After successfully creating a new campaign, you can use AdGroupService to create new ad groups associated with the campaign. After creating an ad group, you can use AdService and CriterionService to respectively create ads and targeting criteria, and associate them with the ad group.
The first ad group you add to a new campaign defines the bidding strategy for the entire campaign. For example, if you create an ad group with siteMaxCpc set and you associate it with a new campaign, then the campaign is now tied to a CPC bidding strategy.
To update a campaign, construct a Campaign data object and set its id to the ID of the campaign to be changed. Set the fields you want to update. Omit the fields that are to remain unchanged. Then call CampaignService.updateCampaign operation on CampaignService.
To get information about one or more campaigns, call one of the provided get requests.
To pause a campaign, construct a Campaign data object and set its id to the ID of the campaign to be paused. Set its status to «Paused» and call updateCampaign.
To turn on conversion optimizer for a given campaign, first call getConversionOptimizerEligibility, passing in the campaign's ID, to see if the campaign is eligible. If so, construct a new ConversionOptimizerSettings object and set enabled to true and maxCpaBidForAllAdGroups to the initial bid. Then update the campaign, using the newly-constructed conversion optimizer settings object. For more information, see
What is the Conversion Optimizer? in the AdWords Help Center.
View the API Reference
An ad group consists of one or more ads and one or more targeting criteria.
All operations that pertain to an ad group as a whole, such as creating ad groups, updating ad groups, and associating ad groups with a campaign, are handled by AdGroupService.
Operations related to ads are handled by AdService, including adding an ad to an ad group. Similarly, operations related to targeting criteria, such as adding keywords or websites to an ad group, are handled by CriterionService. However, setting the max bid for all keywords in an ad group is an ad group-wide operation, and is therefore handled by AdGroupService.
An ad group is represented by an AdGroup data object that is uniquely identified by its id field. An AdGroup has fields for its name, status, associated campaign ID, and default bid values.
To create an ad group, construct a AdGroup data object and set its fields as described in AdGroupService.addAdGroup. Remember that a campaign can have exactly one bidding strategy (cost-per-click or cost-per-mille), so you cannot set both CPC- and CPM-related fields.
After constructing the AdGroup object, call AdGroupService.addAdGroup with newData set to the new AdGroup data and CampaignID set to the campaign with which it should be associated. New ad groups must always be associated with an existing campaign.
Tip: To add multiple ad groups, use AdGroupService.addAdGroupList. This batch request is faster than calling addAdGroup multiple times.
To function properly, an ad group must have at least one targeting criterion and at least one ad. The targeting criterion can be a Keyword, which contextually matches searches or page contents against a specified word, or a Website, which specifies placements on which to display ads.
To add a criterion to an ad group, create one or more Keyword or Website data objects, set the adGroupId of each one to the value of the AdGroup it should belong to, and call CriterionService.addCriteria.
To add an ad, create one or more *Ad data objects, set their adGroupId to the value of the AdGroup it should belong to, and call AdService.addAds.
To change the name, status, or default bids for an ad group, create an AdGroup data object and set its id to the ID of the ad group you want to change. Set the fields you want to update. Fields that don't need to be changed can be left empty. Then call the updateAdGroup operation in AdGroupService to update a single ad group, or updateAdGroupList to update multiple ad groups in a campaign simultaneously.
To delete an AdGroup, set the status to Deleted. To pause an ad group, set the status to Paused.
AdGroupService has operations for retrieving information about ad groups. You can retrieve AdGroup data objects by id, or you can retrieve all ad groups in a campaign.
View the API Reference
Use keyword and placement targeting to control how your ads are considered for display:
Keyword targeting causes ads to be displayed if a search or placement contextually matches the text in a Keyword criterion. For example, a search for "flowers" or a web page about flowers would trigger a Keyword criterion with its text field set to "flowers".
You can use keyword targeting to display your ads on both the search network and the content network.
For information about where keyword-targeted ads appear, see Where will my ads appear? in the AdWords Help Center.
Placement targeting causes ads to be displayed if a placement matches the url in a Website criterion. You can use Website criteria to specify where your ads should display (if the parent campaign's contentTargeting is «AllPlacements»), or to override bids for a subset of placements (if the parent campaign's contentTargeting is «SelectedPlacements»).
For more information about placement-targeted ads, see the following pages in the AdWords Help Center:
Each ad group has one or more criteria (websites or keywords) that can trigger the ad. For example, an ad about flowers might be triggered by the keywords flowers, bouquets, valentine's day, and weddings. CriterionService lets you manage keyword criterion and website criterion and get information about them. For example, you can set the maximum cost-per-click or destination URL for keyword criterion, or you can set the URL of the website for website criterion.
The CriterionService allows you to get, add, update and remove criteria associated with an ad group. It also allows you to get simple statistics for the criteria associated with an ad group.
The CriterionService uses Keyword data object to represent keywords and Website data objects to represent websites.
A new keyword or website criterion must be associated with an existing ad group. To add targeting criteria to an ad group:
Keyword or Website data object as appropriate.
For statically typed languages, such as Java, create an instance either of Website or Keyword.
For dynamically typed languages such as Perl and Python, create a data object and specify its xsi:type attribute to be either Website or Keyword. Instead of setting the xsi:type you can alternatively specify the criterionType field to be either Website or Keyword.
adGroupId field to the value of the AdGroup it is to be associated with.
negative field to true.
destinationURL, language, maxCpc or maxCpm, and text or url. See Website or Keyword for a full list of the fields available on each.
CriterionService.addCriteria, passing in one or more Keyword or Website objects.
CriterionService adds the criteria and set their IDs.
When you add or update a keyword, CriterionService checks that it conforms to Google's Editorial Policy Guidelines, and returns an error if it doesn't. See the section Policy Checking for Ads and Keywords for details.
The text field of a Keyword specifies the text of the keyword. The text cannot be changed after it has been set the first time. The text can contain up to 10 words, with a total maximum of 80 characters. The text can contain letters, digits, and the following special characters:
space # $ & _ - " [ ] ' + . / :
To specify whether a keyword matches exactly, by phrase, or broadly, specify the type of the keyword. This is different from how you set up keywords in the AdWords front-end, where the matching type is incorporated into the keyword text. In the AdWords front-end, brackets [] in the keyword text mean exact match, quotes "" mean phrase match, and everything else is broad match.
For more information about how keywords match, see What are keyword matching options? on the Google website.
Websites must be part of the Google content network to be of value as part of an AdGroup. (See What is the Google Network? for more information).
Information about which websites are part of the network is currently available through the Google AdWords website.
Tip: You can see the available web sites by going through the steps of creating a placement-targeted campaign in the Campaign tab of the Google AdWords website up to the point where you use the Site tool to choose available sites.
Use CriterionService.updateCriteria to update the negative, maxCpc, and destinationUrl fields of a criterion. For a website, you can also update the maxCpm field. You cannot update any other fields. To change any of the other fields, you need to call removeCriteria to delete the Keyword or Website and then add a replacement.
Use the getCriteria operation on CriterionService to get the keywords or website targets in an ad group.
Given a keyword or website, you can get the values of its fields to find information about it.
View the API Reference
AdService lets you create ads, associate them with an ad group, modify them and delete them.
An ad must be associated with an ad group; it cannot exist in isolation. To add an ad to an ad group, create an ad data object, which is one of:
Set the fields that describe the ad -- for example, for text ads, set the headline, description1 and description2 fields.
For each ad, set the destinationURL, which is the URL for the link in your ad that users can click on. Also specify the label for this link using the displayURL field. Set the adGroupId field to the value of the AdGroup it is to be associated with. Call the addAds operation on AdService to add one or more ads. AdService will create the ads and set their id fields.
When you create an ad, AdService checks it to ensure that it conforms to Google's Editorial Policy Guidelines, and if not, returns an error. See the section Policy Checking for Ads and Keywords for details.
Before creating an image ad through the API, you must create at least one image ad through the AdWords user interface at http://adwords.google.com. This is to ensure that you agree to the image scaling agreement that is available through the user interface.
Images can be static or animated. Static images can be PNG, GIF, or JPEG format. Animated images can be flash images (SWF) or animated GIFs. For the latest details about image format, image size (in pixels), file size, and more, see Editorial Guidelines for Image Ads in the AdWords Help Center.
When creating an image ad programmatically, set the image field to an Image object that contains a name and a byte array containing the image data.
When the addAds operation returns from adding an image ad, the returned ad contains an Image object that has no byte data but instead has fields filled in that describe the image (such as height, width, and mimeType ). This returned ad includes imageUrl and thumbnailUrl fields that point to where the image is hosted in the Google Ads System. You can fetch the images from these URLs or link to them.
You can currently change only the status of an ad (enabled, disabled, paused). To update the text, URL or any other part of an ad, you need to delete the existing ad and create a new one.
AdService has the following operations for getting ads:
getAd — returns an ad object for a given ad id and ad group id.getActiveAds — returns all active ads in an ad group.getAllAds — returns all ad in an ad group.Once you have an ad object, you can get more information about it from the values of its fields.
Utility services help you manage your AdWords account and campaigns by providing supplemental data. Here are a few tasks you can perform using the utility services:
View the API Reference
The Info Service allows you to obtain some basic information about your API usage. For example, it lets you find out how many operations you have performed during a given date range in total or for a specific method. You can also get basic data, such as how many API units your token entitles you to this month, the cost of a specific method, and how many API units have been used by calls to a specific method.
View the API Reference
The Account Service allows you to retrieve and update AdWords account data. Account data is encapsulated in a single AccountInfo object.
View the API Reference
The Keyword Tool Service allows you to generate new keywords based on seed keywords you provide or on the words found on a website from a URL that you provide.
To get keyword variations based on a seed keyword:
SeedKeyword request data structure with the source keyword and what type of variations you want to generate: broad, phrase or exact matches.
SeedKeyword to the getKeywordVariations operation in KeywordToolService.
KeywordVariations, you get the variations of the seed keyword along with traffic information, such as relative values of advertiser competition and search volume.
To get keyword variations based on words found on your website:
getKeywordsFromSite operation in KeywordToolService, specifying whether to follow links.
SiteKeywordGroups, you get groups of keywords based on words found on the website. Groups are sorted by decreasing relevance to the site. Each keyword includes traffic information, such as relative values of advertiser competition and search volume.
View the API Reference
SiteSuggestionService provides operations for getting web site suggestions four different ways: by category, topics you define, URLs or demographics. For each call, the service returns an array of SiteSuggestion data objects; each object includes the URL of the suggested site, the approximate number of impressions per day, and which types of ads the site accepts (text, image, video). You can then target your ads to these URLs by creating placement-targeted campaigns.
Categories are diverse, pre-defined areas, such as "Book Retailers" or "Veterinarians". Topics are any words or phrases you specify. Demographics target sites for age, household income, gender and ethnicity. For example you can ask for sites that target females from 18 to 34 with incomes over US$24,000.
To get site suggestions by category, topics, URLs or demographics:
getSitesByCategoryName, getSitesByUrls, getSitesByTopics or getSitesByDemographics. This last request also requires you to fill in a DemographicsTarget data object with preferences to target children, ethnicity, gender, age range and household income.
For example, to get site suggestions for a demographics target:
LanguageGeoTargeting data object, and set its field values (languages, countries, regions, metros).
DemographicsTarget data object, and set its field values (children, ethnicity, gender, age range, household income).
getSitesByDemographics operation in SiteSuggestionService.
SiteSuggestion objects, you can get the values of the fields url, pageViews, acceptsTextAds, acceptsImageAds, and acceptsVideoAds,
View the API Reference
TrafficEstimatorService provides operations for estimating keyword traffic, campaign traffic, and ad group traffic. The operations take input arguments of KeywordRequest, AdgroupRequest, and CampaignRequest. The operations return estimates in the form of data types such as KeywordEstimate, AdgroupEstimate, and CampaignEstimate.
To get an estimate for a keyword, campaign, or ad group:
KeywordRequest, CampaignRequest, or AdgroupRequest.
estimateKeyword, estimateAdGroup, or estimateCampaign in the service. These functions return data types that are specific to the request: KeywordEstimate, AdgroupEstimate, and CampaignEstimate.
For example, to get estimates for a new keyword:
KeywordRequest data structure, and set the values of the type, text, and maxCpc fields.
KeywordRequest to the estimateKeywords operation in TrafficEstimatorService.
KeywordEstimate object, you can get the values of the fields avgPosition, clicksPerDay, cpc and id.
View the API Reference
Use ReportService to generate reports about the performance of your AdWords campaigns. If you have registered with My Client Center (MCC) to administer accounts on behalf of your clients, you can get reports about your clients' AdWords accounts. To learn more about reports, see Report Center help.
If you have registered with My Client Center (MCC) to administer accounts on behalf of your clients, you can get reports about your clients' AdWords accounts. To do this, login without setting the clientEmail header. When setting up the report job, you need to set the crossClient and clientEmails fields. Set crossClient to true, and specify a list of the client login email addresses of the accounts to include in the report as the value of the clientEmails field.
If you set the crossClient field to true and do not supply a value for clientEmails, the generated reports include all the client accounts.
If an MCC manager manages another MCC manager, the first manager can get reports from clients of the second MCC manager. In this case, the first manager can supply the second manager's login as the clientEmail header.
In the case that an MCC manager manages another MCC manager, where the first manager wants to obtain a report across the second manager's clients, then the first manager could supply the second manager's login as the clientEmail header.
When scheduling a report job, you must define the report date range by setting startDay and endDay. This range is inclusive, and is based on your account's local time zone.
Note: If you request a single day's worth of data by setting the start and end date to the same date, you will get a summary report, regardless of the value of AggregationType.