Web Services Overview
Overview
Campaign Data Services
Utility Services
The AdWords API is a set of web services that provides programmatic access to AdWords accounts. To access AdWords accounts programmatically, you build clients that connect to one or more of the AdWords API web services. Each service can be used independently, although for some operations (such as adding a new campaign that has ad groups, ads, and keywords), you will need to use multiple services in a single client program.
Overview
CampaignService, AdGroupService, CriterionService and AdService are collectively known as the campaign data services. They provide operations that let you manage campaigns, ad groups, critera, and ads (creatives). 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, which in turn contain criteria and ads. Wherever possible, operations that relate to a contained entity are supported by the service for that contained entity rather than the container. For example, to get all ad groups in a campaign, you use AdGroupService rather than CampaignService. To pause a campaign, you use CampaignService; to pause an individual ad group, you use AdGroupService. To set the default maximum bid for all keywords in an ad group, you use AdGroupService; to set the maximum bid for an single website criterion, you use CriterionService.
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.
A Word On IDs
Campaigns, ad groups, keywords, website criteria, and ads all have IDs that are set by the AdWords API web services. Keyword and ad IDs are unique only within their ad group, while ad group and campaign IDs are globally unique.
Data Objects
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:
- Required (for example, adGroupId is required when creating a Keyword)
- Optional (such as the Campaign.name),
- Set by the AdWords API web services and ignored if set by the client (such as AdGroup.id).
- Set by the client initially and cannot be subsequently modified (such as Keyword.text).
- Modifiable any time by the client (such as Keyword.maxCpc).
The API Reference section describes which fields are required, optional, set once, immutable, or modifable.
Monetary Units
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).
Note: Previously, the minimum bid was $0.05, which is 50000 (fifty thousand) micros. However, with the introduction of quality-based bidding, the minimum bid of fifty thousand micros has been phased out. For details of minimum bids, see the section Minimum and Maximum Bids for a Keyword.
Policy Checking for Ads and Keywords
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.
CampaignService
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.
The ad groups in a single campaign must all be placement-targeted or all be keyword targeted. For a discussion of the difference, see How do keyword-targeted and placement-targeted campaigns differ? in the AdWords Help Center.
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, dailyBudget. To use CampaignService, you send requests that pass in or return a single Campaign data object or an array of them.
Creating Campaigns
To create campaigns, create one or more Campaign data object and set the fields that describe them, such as name, dailyBudget, endDay, geoTarget, and networkTargeting.
Call the addCampaign operation to add a single campaign or addCampaignList to add a list of new campaigns. CampaignService creates the campaigns and sets their IDs. CampaignService also sets the startDay for each campaign to the current date.
When creating campaigns, the start day is always "now." The end day is optional. After creating a campaign, you can pause or resume it by updating the status field.
After you have created a new campaign, you can create an ad group and associate it with the campaign. After creating an ad group, you can create ads and targeting criterion and associate them with the ad group.
The first ad group you add to a new campaign defines the bidding strategy and targeting for that 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 and placement targeting.
Updating Campaigns
To update a campaign, create a Campaign data object and set its id field to the ID of the campaign to be changed. Set the fields you want to update. You must also set the budget-related fields--if you don't, the unset field is interpreted as zero (a valid but ineffective budget). If you want to keep the current budget, retrieve it using getCampaign and set the updated budget to the retrieved value. Any other fields that are to remain unchanged can be left empty. Then call the updateCampaign operation on CampaignService to update a single campaign, or updateCampaignList to update multiple campaigns simultaneously.
Getting Information about Campaigns
To get information about a campaign or list of campaigns, call getCampaign or getCampaignList, passing in the campaign ID or a list of campaign IDs. CampaignService returns a Campaign or list of Campaigns, which you can then interrogate to get the details of the returned campaigns.
Pausing Campaigns
To pause a campaign, create a Campaign object whose id matches the id of the campaign to be paused. Set the status field to Paused, then call updateCampaign.
Adding Ad Groups to Campaigns
To add an ad group to a campaign, create an AdGroup data object, set its fields, and call addAdGroup (or addAdGroupList) on AdGroupService, specifying the id of the campaign to which the ad group belongs. To select all the ad groups in a campaign, call the getAdGroupIds operation on AdGroupService.
Enabling Conversion Optimizer
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.
API Reference
For more information about CampaignService, see the API Reference:
AdGroupService
An ad group consists of one or more ads and one or more targeting criteria.
- Ads define the visual presentation of an advertisement; they can be text, an image, or an enhanced map component that displays on Google Maps. See AdService for more information.
- Targeting criteria define the circumstances under which the ad should be considered for display. See CriterionService for more information.
All operations that pertain to an ad group as a whole, such as creating ad groups, listing 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 identifed by its id field. An AdGroup has fields for its name, status, associated campaign ID, and default bid values.
Creating Ad Groups
An ad group must be associated with a campaign; it cannot exist in isolation. Ad groups in a single campaign must all have keyword criteria or must all have website criteria. For more explanation, see the section on the CriterionService.
To create ad groups, create one or more AdGroup data objects and set the name and exactly one of keywordMaxCpc, siteMaxCpm, siteMaxCpc for each AdGroup. The name must be unique to the ad groups within a campaign. You can optionally set the status field, which is listed as Enabled by default.
- keywordMaxCpc specifies the default maximum cost-per-click bid for all keywords in the ad group.
- siteMaxCpm specifies the default maximum cost-per-mille (thousand impressions) bid for all placement-targeted ads in the ad group.
- siteMaxCpc specifies the default maximum cost-per-click bid for all placement-targeted ads in the ad group.
After creating the AdGroup, call the addAdGroup request on AdGroupService specifying the AdGroup data and the id of the campaign to which you'd like to add the ad group. AdGroupService creates the ad group and set its id.
To add multiple ad groups to a campaign, call addAdGroupList.
Adding Targeting Criteria and Ads to Ad Groups
An ad group must have at least one targeting criterion and an ad. The targeting criterion can be a keyword for keyword-targeted ads or a website for placement-targeted ads. An ad group can contain only one type of criterion. Furthermore, all ad groups in a campaign must have the same type of criterion.
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 is to be associated with, and call addCriteria in CriterionService.
To add an ad, create an ad data object, set its adGroupId to the value of the AdGroup it is to be associated with, and call addAds in AdService.
If you add criteria to an ad group before you have added any ad, it is very likely that the minCpc value for the criteria will be higher than if you add the ad first.
Updating Ad Groups
To change the name, status, max CPC or max CPM of an ad group, create an AdGroup data object and set its id to the id of the ad group to be changed. 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.
Getting Information about Ad Groups
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.
API Reference
For more information about AdGroupService, see the API Reference:
CriterionService
You can choose whether the ads in your campaign are keyword-targeted or placement-targeted. All ads in a single campaign must be targeted in the same way: they must either all be keyword-targeted or all be placement-targeted.
- Keyword-targeted ads
Keyword-targeted ads are triggered by keywords. For example, if a user searches for flowers, the Google Ad Server looks for ads whose keyword is flowers.
You pay each time a user clicks on your ad. You specify the maximum cost per click (CPC) you are willing to pay.
For information about where keyword-targeted ads appear, see Where will my ads appear in the AdWords Help Center.
- Placement-targeted ads
Placement-targeted ads are displayed on content pages at specific web sites. You specify the web sites where the ad will potentially be displayed.
You can pay per click or per mille (thousand impressions). You specify the cost per click or cost per mille you are willing to pay. 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.
Creating Keywords and Websites
A keyword or website criterion must be associated with an ad group; it cannot exist in isolation.
To add targeting criteria to an ad group:
- Create a 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.
- Set the adGroupId field to the value of the AdGroup it is to be associated with.
- If the criterion is intended to determine where not to display the ad, set the negative field to true.
- Set the other fields that describe the criteria, such as destinationURL, language, maxCpc or maxCpm, and text or url. See Website or Keyword for a full list of the fields available on each.
- Call addCriteria in CriterionService, passing in one or more Keyword or Website objects.
CriterionService will create the keyword and set its id.
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.
Minimum and Maximum Bids for a Keyword
You indicate the most that you are willing to pay per click for a keyword by specifying the maxCpc field. When the keyword triggers your ad, the actual amount you pay per click depends on your keyword's Quality Score. Your Quality Score is determined by your keyword's clickthrough rate (CTR), relevance of ad text, historical keyword performance, and other relevancy factors.
The Google Ad Server determines the minimum bid required to keep your keyword active and ads up and running. The Google Ad Server sets the minCpc field of the keyword to that minimum bid. You specify the maximum amount you are willing to pay per click by setting the maxCpc field. If the maxCpc meets the minCpc, your keyword is active and will be used to trigger ads. If it doesn't, your keyword becomes inactive and is not used to trigger ads.
Due to fluctuation in user and advertiser behavior, the minCpc can change at any time. Remember, the higher the Quality Score, the lower the minimum bid and price you'll pay when someone clicks on your ad. Therefore, the best way to ensure you keyword's maxCpc meets the minCpc so your keyword remains active is to maintain a high-quality campaign.
To find the minimum bid required for a keyword to be active, you can use any of the requests that return a Keywords. Then you can get the value of the minCpc field of the keyword. For example, you could send a getAllCriteria request to the CriterionService to get all the keywords in an ad group, or send a getCriteria request to get keywords that have specific IDs.
When you send an addCriteria or updateCriteria request to add or update keywords, the Google Ad Server sets the minCpc fields for the added or updated keywords.
For more information about Google's keyword evaluation system, please see What are the AdWords keyword status changes?
Keyword Text and Type
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 frontend, where the matching type is incorporated into the keyword text. In the AdWords frontend, 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.
Website Url
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.
Hint: One way to see the available web sites is to go 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.
Updating Keywords and Websites
You can update the negative, and destinationUrl fields of a Criterion, be it a keyword or a website target. For a keyword, you can update the maxCpc field and for a website you can update the maxCpm or maxCpc field. You cannot update any other fields. To change any of the other fields, you need to delete the Keyword or Website, create a new one and reattach it to the ad group.
To update a keyword or website, create a
Keyword or Website data object as appropriate and set its id field. The fields negative and destinationUrl are optional; if unspecified, their values remain unchanged. One of field maxCpc or maxCpm must be set as appropriate. If you want to leave the maxCpc or maxCpm unchanged, first find the existing value, then reset the field to the same value. Then call the updateCriteria operation in CriterionService to update one or more Keywords or Websites.
Getting Information about Keywords and Websites
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.
API Reference
For more information about CriterionService, see the API Reference:
AdService
AdService lets you create ads, associate them with an ad group, modify them and delete them.
Creating Ads
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.
More About Image Ads
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.
Updating Ads
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.
Getting Information about Ads
AService 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.
API Reference
For more information about AdService, see the API Reference:
InfoService
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.
API Reference
For more information about InfoService, see the API Reference:
AccountService
The Account Service allows you to retrieve and update AdWords account
data. Account data is encapsulated in a single
AccountInfo object.
API Reference
For more information about AccountService, see the API Reference:
KeywordToolService
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:
- Create the SeedKeyword request data structure with the source keyword and what type of variations you want to generate: broad, phrase or exact matches.
- Pass the SeedKeyword to the getKeywordVariations operation in KeywordToolService.
- From the returned 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:
- Pass the URL of your website to the getKeywordsFromSite operation in KeywordToolService, specifying whether to follow links.
- From the returned 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.
API Reference
For more information about KeywordToolService, see the API Reference:
SiteSuggestionService
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:
- Fill in a LanguageGeoTargeting data object with the languages, countries, regions and metros you want to target
- In SiteSuggestionService, call the appropriate request: 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.
- Access fields on the returned SiteSuggestion data objects to get the URLs of the suggested websites, along with number of page views and booleans for whether the website accepts text, image and video ads.
For example, to get site suggestions for a demographics target:
- Create a LanguageGeoTargeting data object, and set its field values (languages, countries, regions, metros).
- Create a DemographicsTarget data object, and set its field values (children, ethnicity, gender, age range, household income).
- Pass both data objects to the getSitesByDemographics operation in SiteSuggestionService.
- From the returned SiteSuggestion objects, you can get the values of the fields url, pageViews, acceptsTextAds, acceptsImageAds, and acceptsVideoAds,
API Reference
For more information about SiteSuggestionService, see the API Reference:
TrafficEstimatorService
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, andCampaignEstimate.
To get an estimate for a keyword, campaign, or ad group:
- Create the corresponding request data structure, such as KeywordRequest, CampaignRequest, or AdgroupRequest.
- Fill in the information that describes what is to be estimated.
- Call the appropriate function, such as estimateKeyword, estimateAdGroup, or estimateCampaign in the service. These functions return data types that are specific to the request: KeywordEstimate, AdgroupEstimate, and CampaignEstimate.
- Access fields on the returned data structures to get the estimate results.
For example, to get estimates for a new keyword:
- Create a KeywordRequest data structure, and set the values of the type, text, and maxCpc fields.
- Pass the KeywordRequest to the estimateKeywords operation in TrafficEstimatorService.
- From the returned values, which is a KeywordEstimate object, you can get the values of the fields avgPosition, clicksPerDay, cpc and id.
API Reference
For more information about TrafficEstimatorService, see the API Reference:
ReportService
ReportService allows you to request a report 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 use ReportService, see how to create reports. When creating a report, for v11 or later, use DefinedReportJob; for v10 or earlier, use one of the other report jobs listed in the table below. To learn more about reports, see Report Center help.
ReportService generates a report in XML format, stores it in the Report Center, and returns the URL to the report. You can programmatically get the report by downloading the returned URL. The report is also available in the Report Center of the Google AdWords website.
In v11, the Report Service was upgraded to enable access to all the reports available in the Report Center, as shown in the following table. The report job types available in previous versions of the API work only up to v10. This table also shows how the v10 report types map to the v11 report types. CustomReportJob does not map to any V11 report type.
Getting Reports about your Clients' Accounts
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.
Report Job Fields
All v10 and earlier report jobs have the following fields in addition to any other fields that are specific to the particular type of report job:
- aggregationType — The aggregation period for the report, which can be Summary, Daily, Monthly, Quarterly or Yearly. The default is Summary.
- startDay and endDay — specify when the report starts and ends. These values are required. See the section Start and End Days for Reports for more information.
- name — An optional name for the report. It is not required for the name to be unique, although it is probably more helpful to you if it is. This name is displayed in the Report Center after the report is generated.
- status — This field is set by the Report Service after the report job is scheduled. The status indicates whether the report job is Pending, InProgress, Completed or Failed.
- id — This field is set by the Report Service when the report job is scheduled. This value uniquely identifes the report job.
- crossClient and clientEmails — These fields are applicable to MCC managers (that is, advertisers who have registered with My Client Account to administer AdWords accounts on behalf of other people or companies). MCC managers can use these fields to specify the generation of reports that span their clients' accounts. The crossClient field indicates whether or not to generate a report that runs across multiple client accounts. The clientEmails field specifies the IDs of the accounts to include in the cross-client report. You can always ignore both these fields if you want to generate a report for the single account that you logged in to.
Start and End Day for Reports
In v10 and earlier report jobs, when specifying the details of a report job, you must set the start day and end day. The type of the startDay and endDay fields is xsd:date.
The Report Service uses xsd:date to allow you to specify a time zone in addition to a date. Note, however, that the Report Service only takes the date and the timezone into consideration — it disregards any hour/minute/second information.
The default timezone is the account's local time zone.
The start and end dates are inclusive. To get one day of report data, pass in the same date for both the start and end dates. It is not possible to get a report for just part of a day.
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.
More on Custom Reports
In v10 and earlier, by default, a custom report includes all active keywords in all ad groups in all campaigns. You can filter custom reports by keywords, ad groups, and campaigns. For each of these, you can filter the report either by specific values or by status, but not both.
- campaigns
By default all your campaigns are included in the report.
Optionally, you can fill in either the campaigns or campaignStatuses field, but not both.
- ad groups
By default, all ad groups in the relevant campaigns are included in the report.
Optionally, you can fill in either the adGroups or adGroupStatuses field, but not both. Also, you can optionally choose to filter the report by syndication type by filling in the adWordsType (which is SearchOnly or ContentOnly).
- keywords
By default, all active keywords in the relevant ad groups are included in the report.
Optionally, you can fill in either the keywords or keywordStatuses field, but not both. Also, you can optionally choose to filter the report by keyword matching type by filling in the keywordType (which is Broad, Phrase, or Exact). The default for keywordType is All.
You specify what data to include in the report by setting the customOptions field. This field takes a list of values, such as Clicks, Impressions, DailyBudget, DescriptionLine1, ConversionRate, and more. The full list is provided in the reference page for CustomReportJob.You must specify at least one customOption or there will be nothing to report. For each custom option specified, the report includes a corresponding XML element. For example, if you specify the DestinationUrl custom option, the report includes a <DestinationUrl> element.
You can get data on the following kinds of URLs in a custom report:
- DestinationUrl
indicates the keyword destination URL if one was set, otherwise it indicates the ad destination URL.
- KeywordDestinationUrl
If the keyword exists, the KeywordDestinationUrl indicates the keyword's destination URL if one was set, otherwise it indicates the ad destination URL. I the keyword was deleted, KeywordDestinationUrl is an empty string in the report.
- CreativeDestinationUrl
Always indicates the ad's destination URL.
API Reference
For more information about ReportService, see the API Reference:
API Reference
