My favorites | English | Sign in

Documentation for the requested version is not available.Documentation for the requested diff is not available.

CriterionService

Link to this version

Use CriterionService to create and manage criteria in an ad group. Criteria are used to determine if ads should be considered for display:

  • A Keyword criterion defines text that matches search queries and web page content. You can use Keyword criteria to target both the search network and the content network.
  • A Website criterion defines a URL that matches a website. You can use Website criteria to target the content network.

Tip: Before adding new criteria, use checkCriteria to make sure they do not trigger policy errors. Checking a criterion costs only 1 API unit, whereas a failed add costs 20 API units.

More Information

Requests

addCriteria

Adds new criteria to an ad group.

Parameters

criteria Criterion[]
List of new criteria to be added. All new criteria must be associated with the same ad group.

Required fields:

Required fields for Keyword criteria:

Required fields for Website criteria:

Optional fields:

Criterion is one of:

Response

Criterion[] List of new criteria with their id fields set.

Criterion is one of:

Samples

Code sample not available.
 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

      // Create new website structure.
      long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");
      Website website = new Website();
      website.setAdGroupId(adGroupId);
      website.setCriterionType(CriterionType.Website);
      website.setUrl("example.com");

      // Check new website for policy violations before adding it.
      String[] languageTarget = new String[] {"en"};
      GeoTarget geoTarget = new GeoTarget();
      geoTarget.setCountryTargets(new CountryTargets(new String[] {"US"},
          new String[]{}));
      ApiError[] errors = service.checkCriteria(
          new Criterion[] {website}, languageTarget, geoTarget);

      // Add website if there are no policy violations.
      if (errors == null) {
        Criterion[] criteria = service.addCriteria(new Criterion[] {website});

View full sample

Code sample not available.
 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

        // Create new website structure.
        long adGroupId = long.Parse("INSERT_AD_GROUP_ID_HERE");

        Website website = new Website();
        website.adGroupId = adGroupId;
        website.criterionTypeSpecified = true;
        website.criterionType = CriterionType.Website;
        website.url = "example.com";

        // Check new website for policy violations before adding it.
        String[] languageTarget = { "en" };
        GeoTarget geoTarget = new GeoTarget();
        CountryTargets countryTargets = new CountryTargets();
        countryTargets.countries = new String[] { "US" };
        geoTarget.countryTargets = countryTargets;
        ApiError[] errors = service.checkCriteria(
            new Criterion[] { website }, languageTarget, geoTarget);

        // Add website if there are no policy violations.
        if (errors == null) {
          Criterion[] criteria = service.addCriteria(
            new Criterion[] { website });

View full sample

Code sample not available.
 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# Create new keyword structure.
my $ad_group_id = 'INSERT_AD_GROUP_ID_HERE';
my $criterion = {
  'adGroupId' => $ad_group_id,
  'criterionType' => 'Website',
  'url' => 'example.com'
};

# Check keyword for policy violations before adding it.
my $criteria = SOAP::Data->name('criteria' => [$criterion]);
my $language_target = SOAP::Data->name('languageTarget' => {
  'languages' => ['en']});
my $geo_target = SOAP::Data->name('geoTarget' => {'countryTargets' => {
  'countries' => ['US']}});
my $response = $service->call('checkCriteria' => $criteria, $language_target,
                            $geo_target, @headers);
my @errors = ($response->result(), $response->paramsout());

# Add keyword if there are no policy violations.
unless (@errors) {
  $response = $service->call('addCriteria' => $criteria, @headers);
  my @criteria = ($response->result(), $response->paramsout());

View full sample

Code sample not available.
 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# Create new website structure.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'
website = {
  'adGroupId': SOAPpy.Types.untypedType(ad_group_id),
  'criterionType': SOAPpy.Types.untypedType('Website'),
  'url': 'example.com'
}

# Check new website for policy violations before adding it.
language_target = {'languages': ['en']}
geo_target = {'countryTargets': {'countries': ['US']}}
errors = criterion_service.checkCriteria([website], language_target, geo_target)

# Convert to a list if we get back a single object.
if len(errors) > 0 and not isinstance(errors, list):
  errors = [errors]

# Add website if there are no policy violations.
if len(errors) == 0:
  criteria = criterion_service.addCriteria([website])

View full sample

Code sample not available.
 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# Create new website structure.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
website = %{
<criteria>
  <adGroupId>#{ad_group_id}</adGroupId>
  <criterionType>Website</criterionType>
  <url>example.com</url>
</criteria>
}

# Check new website for policy violations before adding it.
language_target = '<languageTarget><languages>en</languages></languageTarget>'
geo_target = %{
<geoTarget>
  <countryTargets>
    <countries>US</countries>
  </countryTargets>
</geoTarget>
}
errors = criterion_service.checkCriteria(REXML::Document.new(
  "<checkCriteria>#{website}#{language_target}#{geo_target}</checkCriteria>"))
if errors.respond_to?('checkCriteriaReturn')
  errors = errors.checkCriteriaReturn

  # Convert to a list if we get back a single object.
  if ! errors.respond_to?('each')
    errors = [errors]
  end
end

# Add website if there were no policy violations.
if errors.empty?
  criteria = criterion_service.addCriteria(REXML::Document.new(
    "<addCriteria>#{website}</addCriteria>")).addCriteriaReturn

View full sample

Code sample not available.
 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# Create new website structure.
$ad_group_id = 'INSERT_AD_GROUP_ID_HERE';
$website =
  '<adGroupId>' . $ad_group_id . '</adGroupid>' .
  '<criterionType>Website</criterionType>' .
  '<url>example.com</url>';

# Check new website for policy violations before adding it.
$language_target =
  '<languageTarget><languages>en</languages></languageTarget>';
$geo_target =
  '<geoTarget>' .
  '<countryTargets><countries>US</countries></countryTargets>' .
  '</geoTarget>';
$request_xml =
  '<checkCriteria>' .
  '<criteria>' . $website . '</criteria>' . $language_target . $geo_target .
  '</checkCriteria>';
$errors = $criterion_service->call('checkCriteria', $request_xml);
$errors = $errors['checkCriteriaReturn'];
if ($debug) show_xml($criterion_service);
if ($criterion_service->fault) show_fault($criterion_service);

# Add website if there are no policy violations.
if (!$errors) {
  $request_xml =
    '<addCriteria>' .
    '<criteria>' . $website . '</criteria>' .
    '</addCriteria>';
  $criteria = $criterion_service->call('addCriteria', $request_xml);
  $criteria = $criteria['addCriteriaReturn'];

View full sample

Code sample not available.
 
12
13
14
15
16
17
18
19

    <!-- Creates a new website given an existing ad group. -->
    <addCriteria>
      <criteria>
        <adGroupId>INSERT_AD_GROUP_ID_HERE</adGroupId>
        <criterionType>Website</criterionType>
        <url>example.com</url>
      </criteria>
    </addCriteria>

View full sample

Select a programming language to view its sample

checkCriteria

Checks a batch of criteria for policy errors. Use this request to verify criteria before trying to add them. Checking a criterion for policy errors costs only 1 API unit per criterion, whereas a failed call to addCriteria will cost 20 API units per criterion.

Parameters

criteria Criterion[]
List of criteria to be checked. Length must be no longer than the maximum allowable number of criteria per ad group.

Required fields for Keyword criteria:

Required fields for Website criteria:

Optional fields:

Note: If adGroupId is not specified, you must set languageTarget and geoTarget.

Criterion is one of:
languageTarget LanguageTarget
Language targeting options to be used when checking for policy errors. Required if adGroupId is not specified.
geoTarget GeoTarget
Geographical targeting options to be used when checking for policy errors. Required if adGroupId is not specified.

Response

ApiError[] A list of policy errors.

Samples

Code sample not available.
 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

      // Create new website structure.
      long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");
      Website website = new Website();
      website.setAdGroupId(adGroupId);
      website.setCriterionType(CriterionType.Website);
      website.setUrl("example.com");

      // Check new website for policy violations before adding it.
      String[] languageTarget = new String[] {"en"};
      GeoTarget geoTarget = new GeoTarget();
      geoTarget.setCountryTargets(new CountryTargets(new String[] {"US"},
          new String[]{}));
      ApiError[] errors = service.checkCriteria(
          new Criterion[] {website}, languageTarget, geoTarget);

      // Add website if there are no policy violations.
      if (errors == null) {
        Criterion[] criteria = service.addCriteria(new Criterion[] {website});

View full sample

Code sample not available.
 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

        // Create new website structure.
        long adGroupId = long.Parse("INSERT_AD_GROUP_ID_HERE");

        Website website = new Website();
        website.adGroupId = adGroupId;
        website.criterionTypeSpecified = true;
        website.criterionType = CriterionType.Website;
        website.url = "example.com";

        // Check new website for policy violations before adding it.
        String[] languageTarget = { "en" };
        GeoTarget geoTarget = new GeoTarget();
        CountryTargets countryTargets = new CountryTargets();
        countryTargets.countries = new String[] { "US" };
        geoTarget.countryTargets = countryTargets;
        ApiError[] errors = service.checkCriteria(
            new Criterion[] { website }, languageTarget, geoTarget);

        // Add website if there are no policy violations.
        if (errors == null) {
          Criterion[] criteria = service.addCriteria(
            new Criterion[] { website });

View full sample

Code sample not available.
 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# Create new keyword structure.
my $ad_group_id = 'INSERT_AD_GROUP_ID_HERE';
my $criterion = {
  'adGroupId' => $ad_group_id,
  'criterionType' => 'Website',
  'url' => 'example.com'
};

# Check keyword for policy violations before adding it.
my $criteria = SOAP::Data->name('criteria' => [$criterion]);
my $language_target = SOAP::Data->name('languageTarget' => {
  'languages' => ['en']});
my $geo_target = SOAP::Data->name('geoTarget' => {'countryTargets' => {
  'countries' => ['US']}});
my $response = $service->call('checkCriteria' => $criteria, $language_target,
                            $geo_target, @headers);
my @errors = ($response->result(), $response->paramsout());

# Add keyword if there are no policy violations.
unless (@errors) {
  $response = $service->call('addCriteria' => $criteria, @headers);
  my @criteria = ($response->result(), $response->paramsout());

View full sample

Code sample not available.
 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# Create new website structure.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'
website = {
  'adGroupId': SOAPpy.Types.untypedType(ad_group_id),
  'criterionType': SOAPpy.Types.untypedType('Website'),
  'url': 'example.com'
}

# Check new website for policy violations before adding it.
language_target = {'languages': ['en']}
geo_target = {'countryTargets': {'countries': ['US']}}
errors = criterion_service.checkCriteria([website], language_target, geo_target)

# Convert to a list if we get back a single object.
if len(errors) > 0 and not isinstance(errors, list):
  errors = [errors]

# Add website if there are no policy violations.
if len(errors) == 0:
  criteria = criterion_service.addCriteria([website])

View full sample

Code sample not available.
 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

# Create new website structure.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
website = %{
<criteria>
  <adGroupId>#{ad_group_id}</adGroupId>
  <criterionType>Website</criterionType>
  <url>example.com</url>
</criteria>
}

# Check new website for policy violations before adding it.
language_target = '<languageTarget><languages>en</languages></languageTarget>'
geo_target = %{
<geoTarget>
  <countryTargets>
    <countries>US</countries>
  </countryTargets>
</geoTarget>
}
errors = criterion_service.checkCriteria(REXML::Document.new(
  "<checkCriteria>#{website}#{language_target}#{geo_target}</checkCriteria>"))
if errors.respond_to?('checkCriteriaReturn')
  errors = errors.checkCriteriaReturn

  # Convert to a list if we get back a single object.
  if ! errors.respond_to?('each')
    errors = [errors]
  end
end

# Add website if there were no policy violations.
if errors.empty?
  criteria = criterion_service.addCriteria(REXML::Document.new(
    "<addCriteria>#{website}</addCriteria>")).addCriteriaReturn

View full sample

Code sample not available.
 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# Create new website structure.
$ad_group_id = 'INSERT_AD_GROUP_ID_HERE';
$website =
  '<adGroupId>' . $ad_group_id . '</adGroupid>' .
  '<criterionType>Website</criterionType>' .
  '<url>example.com</url>';

# Check new website for policy violations before adding it.
$language_target =
  '<languageTarget><languages>en</languages></languageTarget>';
$geo_target =
  '<geoTarget>' .
  '<countryTargets><countries>US</countries></countryTargets>' .
  '</geoTarget>';
$request_xml =
  '<checkCriteria>' .
  '<criteria>' . $website . '</criteria>' . $language_target . $geo_target .
  '</checkCriteria>';
$errors = $criterion_service->call('checkCriteria', $request_xml);
$errors = $errors['checkCriteriaReturn'];
if ($debug) show_xml($criterion_service);
if ($criterion_service->fault) show_fault($criterion_service);

# Add website if there are no policy violations.
if (!$errors) {
  $request_xml =
    '<addCriteria>' .
    '<criteria>' . $website . '</criteria>' .
    '</addCriteria>';
  $criteria = $criterion_service->call('addCriteria', $request_xml);
  $criteria = $criteria['addCriteriaReturn'];

View full sample

Code sample not available.
 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

    <!-- Checks criteria for policy violations. -->
    <!-- Useful before calling addCriteria. -->
    <checkCriteria>
      <criteria>
        <adGroupId>INSERT_AD_GROUP_ID_HERE</adGroupId>
        <criterionType>Keyword</criterionType>
        <text>mars cruise</text>
        <type>Broad</type>
      </criteria>
      <languageTarget>
        <languages>en</languages>
      </languageTarget>
      <geoTarget>
        <countryTargets>
          <countries>US</countries>
        </countryTargets>
      </geoTarget>
    </checkCriteria>

View full sample

Select a programming language to view its sample

getAllCriteria

Returns the criteria associated with the specified ad group.

Parameters

adGroupId long
ID of the ad group.

Response

Criterion[] List of criteria associated with the specified ad group.

Criterion is one of:

Samples

Code sample not available.
 
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

      // Get all campaigns.
      Campaign[] campaigns = campaignService.getAllAdWordsCampaigns(0);

      int count = 0;

      if (campaigns != null) {
        for (Campaign campaign : campaigns) {
          // Get all ad groups.
          AdGroup[] adGroups = adGroupService.getAllAdGroups(campaign.getId());

          if (adGroups != null) {
            for (AdGroup adGroup : adGroups) {
              // Get all criteria.
              Criterion[] criteria =
                  criterionService.getAllCriteria(adGroup.getId());

View full sample

Code sample not available.
 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

        // Get all campaigns.
        Campaign[] campaigns = campaignService.getAllAdWordsCampaigns(0);

        int count = 0;

        if (campaigns != null) {
          for (int i = 0; i < campaigns.Length; i++) {
            // Get all ad groups.
            AdGroup[] adGroups = adGroupService.getAllAdGroups(campaigns[i].id);

            if (adGroups != null) {
              for (int j = 0; j < adGroups.Length; j++) {
                // Get all criteria.
                Criterion[] criteria =
                    criterionService.getAllCriteria(adGroups[j].id);

View full sample

Code sample not available.
 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# Get all campaigns.
my $dummy = SOAP::Data->name('dummy' => 0);
my $response = $campaign_service->call('getAllAdWordsCampaigns' => $dummy,
  @headers);
my @campaigns = ($response->result(), $response->paramsout());

my $count = 0;
foreach my $campaign (@campaigns) {
  # Get all ad groups.
  my $campaign_id = SOAP::Data->name('campaignID' => $campaign->{'id'});
  $response = $ad_group_service->call('getAllAdGroups' => $campaign_id,
    @headers);
  my @ad_groups = ($response->result(), $response->paramsout());

  for my $ad_group (@ad_groups) {
    # Get all criteria.
    my $ad_group_id = SOAP::Data->name('adGroupId' => $ad_group->{'id'});
    $response = $criterion_service->call('getAllCriteria' => $ad_group_id,
      @headers);
    my @criteria = ($response->result(), $response->paramsout());

View full sample

Code sample not available.
 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# Get all campaigns.
campaigns = campaign_service.getAllAdWordsCampaigns(0)

# Convert to a list if we get back a single object.
if len(campaigns) > 0 and not isinstance(campaigns, list):
  campaigns = [campaigns]

count = 0
for campaign in campaigns:
  # Get all ad groups.
  ad_groups = ad_group_service.getAllAdGroups(int(campaign['id']))

  # Convert to a list if we get back a single object.
  if len(ad_groups) > 0 and not isinstance(ad_groups, list):
    ad_groups = [ad_groups]

  for ad_group in ad_groups:
    # Get all criteria.
    criteria = criterion_service.getAllCriteria(
        SOAPpy.Types.untypedType(str(ad_group['id'])))

View full sample

Code sample not available.
 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# Get all campaigns.
campaigns = campaign_service.getAllAdWordsCampaigns(:dummy => 0
  ).getAllAdWordsCampaignsReturn

# Convert to a list if we get back a single object.
if ! campaigns.respond_to?('each')
  campaigns = [campaigns]
end

count = 0
campaigns.each do |campaign|
  # Get all ad groups.
  ad_groups = ad_group_service.getAllAdGroups(:campaignID => campaign['id'])
  if ad_groups.respond_to?('getAllAdGroupsReturn')
    ad_groups = ad_groups.getAllAdGroupsReturn
  end

  # Convert to a list if we get back a single object.
  if ! ad_groups.respond_to?('each')
    ad_groups = [ad_groups]
  end

  ad_groups.each do |ad_group|
    # Get all criteria.
    criteria = criterion_service.getAllCriteria(:adGroupId => ad_group['id'])
    if criteria.respond_to?('getAllCriteriaReturn')
      criteria = criteria.getAllCriteriaReturn

View full sample

Code sample not available.
 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# Get all campaigns.
$request_xml =
  '<getAllAdWordsCampaigns><dummy>0</dummy></getAllAdWordsCampaigns>';
$campaigns = $campaign_service->call('getAllAdWordsCampaigns', $request_xml);
$campaigns = $campaigns['getAllAdWordsCampaignsReturn'];
if ($debug) show_xml($campaign_service);
if ($campaign_service->fault) show_fault($campaign_service);

# Convert to a list if we get back a single object.
if (!$campaigns[0]) {
  $campaigns = array($campaigns);
}

$count = 0;
for ($i = 0; $i < count($campaigns); $i++) {
  if (!$campaigns[$i]) {
    continue;
  }

  # Get all ad groups.
  $request_xml =
    '<getAllAdGroups>' .
    '<campaignId>' . $campaigns[$i]['id'] . '</campaignId>' .
    '</getAllAdGroups>';
  $ad_groups = $ad_group_service->call('getAllAdGroups', $request_xml);
  $ad_groups = $ad_groups['getAllAdGroupsReturn'];
  if ($debug) show_xml($ad_group_service);
  if ($ad_group_service->fault) show_fault($ad_group_service);

  # Convert to a list if we get back a single object.
  if (!$ad_groups[0]) {
    $ad_groups = array($ad_groups);
  }

  for ($j = 0; $j < count($ad_groups); $j++) {
    if (!$ad_groups[$j]) {
      continue;
    }

    # Get all criteria.
    $request_xml =
      '<getAllCriteria>' .
      '<adGroupId>' . $ad_groups[$j]['id'] . '</adGroupId>' .
      '</getAllCriteria>';
    $criteria = $criterion_service->call('getAllCriteria', $request_xml);
    $criteria = $criteria['getAllCriteriaReturn'];

View full sample

Code sample not available.
 
12
13
14
15
16

    <!-- Retrieves all criteria from the AdWords account that -->
    <!-- belongs to the customer issuing the request. -->
    <getAllCriteria>
      <adGroupId>INSERT_AD_GROUP_ID_HERE</adGroupId>
    </getAllCriteria>

View full sample

Select a programming language to view its sample

getCampaignNegativeCriteria

Gets a list of the negative criteria associated with a campaign. Negative criteria determine when ads in the campaign will not be displayed.

Parameters

campaignId int
ID of the campaign for which to return negative criteria

Response

Criterion[] A list of negative criteria in the specified campaign

Criterion is one of:

getCriteria

Returns the criteria with the specified IDs associated with a given ad group. This request returns criteria associated with one AdGroup at a time. Invalid IDs are ignored.

Parameters

adGroupId long
ID of the ad group..
criterionIds long[]
IDs of the criteria.

Response

Criterion[] The criteria matching criterionIds that are associated with the specified ad group

Criterion is one of:

getCriterionStats

Gets statistics for a list of criteria in an ad group. The time granularity is one day.

Parameters

adGroupId long
Ad group that contains the criteria to be queried
criterionIds long[]
Criteria to query
startDay date
Starting day of the period for which statistics are to be collected (xsd:date).
endDay date
Ending day of the period for which statistics are to be collected, inclusive (xsd:date).

Response

StatsRecord[] List of StatsRecord objects, each containing statistics related to a criterion. The returned array may be in a different order than the IDs specified in criterionIds.

removeCriteria

Removes a list of criteria from an ad group.

Caution: Unlike campaigns and ad groups, criteria are permanently deleted and cannot be restored.

Parameters

adGroupId long
ID of the ad group
criterionIds long[]
IDs of the criteria to remove

Response

(none)

setCampaignNegativeCriteria

Removes all existing negative criteria from a campaign and sets new negative criteria for the specified campaign.

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

campaignId int
ID of the campaign
criteria Criterion[]
Negative criteria to be associated with the campaign.

Criterion is one of:

Response

(none)

updateCriteria

Updates the fields associated with the specified criteria. You can modify only these fields:

  • destinationUrl
  • maxCpc
  • maxCpm
  • paused

Parameters

criteria Criterion[]
List of Criterion objects to update.

Required fields:

  • id
  • adGroupId (adGroupId and id together uniquely identify the criterion to update.)

Optional fields:

Criterion is one of:

Response

(none)