CriterionService
CriterionService provides operations for accessing, modifying,
and creating criteria (Keywords and Websites) in an AdGroup.
The Google Ad Server uses the criteria for selecting ads:
Keyword criteria are used to select ads
to display in search results pages.
Website criteria are used to select
ads to display in content pages at websites.
For more information about how to use the CriterionService, see the overview section.
Requests
Add new criteria to an AdGroup.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| criteria |
Criterion[] |
The new criteria to be added to the AdGroup,
which is specified by the adGroupId of the criteria --
all criteria elements must have the same adGroupId.
The criteria must all be Website criteria or
Keyword criteria in accordance with the Campaign
that the AdGroup belongs to.
For all Criterion:
- the following fields must be specified:
- adGroupId: The ID of the AdGroup to add this criterion to.
This must correspond to one of your existing adgroups.
- the following fields will be honored if specified:
- negative
- destinationUrl
For Keywords:
- the following fields must be specified:
- type
- text
- the following fields will be honored if specified:
- maxCpc
For Websites:
- the following fields must be specified:
- url
- the following fields will be honored if specified:
- maxCpm
Criterion is one of:
|
Response
| Response type | Response description |
|---|
Criterion[] |
The new Criterion, with all values (including IDs) filled in.
The returned Criterion will be either a Website or
Keyword Criterion.
Criterion is one of:
|
Check a batch of criteria for policy errors. The number of criteria in the
batch is limited to the maximum number of criteria per adgroup.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| criteria |
Criterion[] |
The criteria to be checked.
Criterion is one of:
|
| languageTarget |
LanguageTarget |
The overriding language context |
| geoTarget |
GeoTarget |
The overriding geographical context
For all Criterion:
- the following fields will be honored if specified:
- negative
- destinationUrl
For Keywords:
- the following fields must be specified:
- type
- text
- the following fields will be honored if specified:
- maxCpc
For Websites:
- the following fields must be specified:
- url
- the following fields will be honored if specified:
- maxCpm
If adGroupId is not specified, at least one of languageTarget and geoTarget
must not be null. |
Response
| Response type | Response description |
|---|
ApiError[] |
A list of policy errors |
Return a list of criteria associated with this AdGroup.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| adGroupId |
long |
The ID of the AdGroup. |
Response
| Response type | Response description |
|---|
Criterion[] |
An array of criteria for this AdGroup.
The returned criteria will be either Keyword
or Website data objects.
Criterion is one of:
|
Gets a list of the negative criteria associated with a campaign.
Negative criteria determine where the ads in the campaign will
not be displayed. Negative website criteria indicate websites
where the ads will not appear. Negative keyword criteria indicate
keywords that cause the ads to be excluded from display.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| campaignId |
int |
the campaign id |
Response
| Response type | Response description |
|---|
Criterion[] |
the negative criteria for the specified campaign
The returned criteria will be either Keyword
or Website data objects.
Criterion is one of:
|
Return a list of criteria with the specified IDs associated with
this AdGroup. This function will only return criteria associated
with one AdGroup at a time. Invalid IDs are ignored.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| adGroupId |
long |
The ID of the AdGroup. |
| criterionIds |
long[] |
The IDs of the criteria. |
Response
| Response type | Response description |
|---|
Criterion[] |
An array of Criterion instances that match the input list.
The returned criteria will be either Keyword
or Website data objects.
Criterion is one of:
|
Get statistics for a list of criteria in an ad group. See
StatsRecord
for details about the statistics returned. The time granularity is one day.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| adGroupId |
long |
The ad group that contains the criteria to be
queried |
| criterionIds |
long[] |
The criteria to query |
| startDay |
date |
The starting day of the period for which statistics are
to be collected (xsd:date). |
| endDay |
date |
The ending day of the period for which statistics are to be
collected, inclusive (xsd:date). |
Response
| Response type | Response description |
|---|
StatsRecord[] |
an array of
StatsRecords
containing information about the activity on the criteria.
The order of StatsRecord objects returned may be different from
the order in which the id's were requested. |
Remove a list of criteria from an AdGroup.
Note that there is no 'undo' for this operation.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| adGroupId |
long |
the ID of the AdGroup |
| criterionIds |
long[] |
the IDs of the criteria |
Response
| Response type | Response description |
|---|
(none) |
|
Removes all existing negative criteria from a campaign and
sets new negative criteria for the specified campaign.
Negative criteria determine where the ads in the campaign
will not be displayed. Negative website criteria indicate websites
where the ads will not appear. Negative keyword criteria indicate
keywords that cause the ads to be excluded from display.
Calling this method with a null or empty list clears the
negative criteria for the campaign. If your campaign already
has some negative criteria and you want to add more,
first call getCampaignNegativeCriteria, then add the new
negative criteria to the results and send the complete
set of negative criteria to setCampaignNegativeCriteria.
NOTE - Negative criteria keywords and websites in ad groups
(that is, where negative is true) can be paused and resumed
as expected. However, setting negative criteria using
setCampaignNegativeCriteria with a paused Keyword or
Website criterion will not pause the keyword or website.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| campaignId |
int |
the campaign id |
| criteria |
Criterion[] |
The negative criteria to be associated with the Campaign.
The criteria must be all Website criteria or
all Keyword critera in accordance with the campaign.
Criterion is one of:
|
Response
| Response type | Response description |
|---|
(none) |
|
Update all mutable fields associated with these criteria.
Only the maxCpc, maxCpm, negative, paused, and destinationUrl fields are
mutable.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| criteria |
Criterion[] |
the criteria to update, which is either a list of one or
more Keyword objects or a list of one or more Website
objects.
Required fields for each criterion:
- id: The ID of the Criterion. The Criterion must already exist.
- adGroupId: The ID of the AdGroup owning this Criterion. This field
is not mutable - you may not move a Criterion to another adgroup.
Optional fields for each criterion:
- paused: If this criterion is paused, it will not be used to serve
creatives.
- destinationUrl: If set, updates the destination URL.
If a zero-length string is present, we unset the destination URL
(so this keyword will default to using the one associated with the
creative).
Optional field for Keyword objects only:
- maxCpc: The new CPC for this keyword. If zero is specified, the
CPC for this keyword will be cleared, so the default CPC for the
adgroup will be used instead.
Optional field for Website objects only:
- maxCpm: The new CPM for this website. If zero is specified, the
CPM for this website will be cleared, so the default CPM for the
adgroup will be used instead.
Ignored fields for each criterion:
- negative: Whether this Criterion is negative. This field is
ignored, which means an existing negative keyword can not be converted
into a positive one, or vice versa.
Criterion is one of:
|
Response
| Response type | Response description |
|---|
(none) |
|
API Reference
