My favorites | English | Sign in

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

CampaignService

Link to this version

CampaignService provides operations for accessing, modifying, and creating AdWords Campaigns.

More Information

Requests

addCampaign

Creates a new campaign.

Parameters

campaign Campaign
Information for the new campaign.

These fields are required:

These fields are optional and default to the values documented below:

  • name, default is "Campaign #n"
  • status, default is «Active»
  • startDay, default is current day in parent account's local timezone.
  • endDay, default is 2037-12-30, indicating the campaign will not end.
  • networkTargeting, targets search network and content network by default..
  • languageTargeting, targets all languages by default.
  • geoTargeting, targets no specific location by default.

Note: id is ignored if specified. CampaignService sets id when the campaign is created.

Response

Campaign The new Campaign object, with its ID set.

Samples

Code sample not available.
 
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
101
102
103
104
105
106
107

      // Create new campaign structure with ad scheduling set to show ads on
      // Monday, Wednesday, and Friday from 8:00am to 5:00pm. Each bid is
      // multiplied by 1.0.
      SchedulingInterval intervalMonday = new SchedulingInterval();
      intervalMonday.setDay(DayOfWeek.Monday);
      intervalMonday.setEndHour(17);
      intervalMonday.setEndMinute(0);
      intervalMonday.setMultiplier(1.0);
      intervalMonday.setStartHour(8);
      intervalMonday.setStartMinute(0);
      SchedulingInterval intervalWednesday = new SchedulingInterval();
      intervalWednesday.setDay(DayOfWeek.Wednesday);
      intervalWednesday.setEndHour(17);
      intervalWednesday.setEndMinute(0);
      intervalWednesday.setMultiplier(1.0);
      intervalWednesday.setStartHour(8);
      intervalWednesday.setStartMinute(0);
      SchedulingInterval intervalFriday = new SchedulingInterval();
      intervalFriday.setDay(DayOfWeek.Friday);
      intervalFriday.setEndHour(17);
      intervalFriday.setEndMinute(0);
      intervalFriday.setMultiplier(1.0);
      intervalFriday.setStartHour(8);
      intervalFriday.setStartMinute(0);

      AdSchedule schedule = new AdSchedule();
      schedule.setIntervals(new SchedulingInterval[] {
          intervalMonday, intervalWednesday, intervalFriday});
      schedule.setStatus(AdScheduleStatus.Enabled);

      // Create new campaign structure.
      Campaign campaign = new Campaign();
      campaign.setName("Sample Campaign");
      campaign.setBudgetAmount(new Long(100000));
      campaign.setBudgetPeriod(BudgetPeriod.Daily);
      GeoTarget geoTargeting = new GeoTarget();
      geoTargeting.setCountryTargets(new CountryTargets(new String[] {"US"},
          new String[]{}));
      campaign.setGeoTargeting(geoTargeting);
      campaign.setLanguageTargeting(new String[] {"en"});
      campaign.setSchedule(schedule);

      // Add campaign.
      campaign = service.addCampaign(campaign);

View full sample

Code sample not available.
 
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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

        // Create new campaign structure with ad scheduling set to show ads on
        // Monday, Wednesday, and Friday from 8:00am to 5:00pm. Each bid is
        // multiplied by 1.0.

        SchedulingInterval intervalMonday = new SchedulingInterval();
        intervalMonday.day = DayOfWeek.Monday;
        intervalMonday.endHour = 17;
        intervalMonday.endMinute = 0;
        intervalMonday.multiplier = 1.0;
        intervalMonday.startHour = 8;
        intervalMonday.startMinute = 0;
        SchedulingInterval intervalWednesday = new SchedulingInterval();
        intervalWednesday.day = DayOfWeek.Wednesday;
        intervalWednesday.endHour = 17;
        intervalWednesday.endMinute = 0;
        intervalWednesday.multiplier = 1.0;
        intervalWednesday.startHour = 8;
        intervalWednesday.startMinute = 0;
        SchedulingInterval intervalFriday = new SchedulingInterval();
        intervalFriday.day = DayOfWeek.Friday;
        intervalFriday.endHour = 17;
        intervalFriday.endMinute = 0;
        intervalFriday.multiplier = 1.0;
        intervalFriday.startHour = 8;
        intervalFriday.startMinute = 0;

        AdSchedule schedule = new AdSchedule();
        schedule.intervals = new SchedulingInterval[] {
          intervalMonday, intervalWednesday, intervalFriday};
        schedule.status = AdScheduleStatus.Enabled;

        // Create new campaign structure.
        Campaign campaign = new Campaign();
        campaign.name = "Sample Campaign US";
        campaign.budgetAmount = 100000L;
        campaign.budgetAmountSpecified = true;
        campaign.budgetPeriod = BudgetPeriod.Daily;
        campaign.budgetPeriodSpecified = true;
        GeoTarget geoTargeting = new GeoTarget();
        CountryTargets countryTargets = new CountryTargets();
        countryTargets.countries = new String[] { "US" };
        geoTargeting.countryTargets = countryTargets;
        campaign.geoTargeting = geoTargeting;
        campaign.languageTargeting = new String[] { "en" };
        campaign.schedule = schedule;

        // Add campaign.
        campaign = service.addCampaign(campaign);

View full sample

Code sample not available.
 
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

# Create new campaign structure with ad scheduling set to show ads on Monday,
# Wednesday, and Friday from 8:00 a.m. to 5:00 p.m. Each bid is multiplied by
# 1.0.
my @days = qw(Monday Wednesday Friday);
my %interval_template = (
  'endHour' => 17,
  'endMinute' => 0,
  'multiplier' => '1.0',
  'startHour' => 8,
  'startMinute' => 0
);
my @intervals;

foreach my $day (@days) {
  $interval_template{'day'} = $day;
  push(@intervals, {%interval_template});
}

my $schedule = {
  'intervals' => \@intervals,
  'status' => 'Enabled'
};
my $campaign = SOAP::Data->name('campaign' => {
  'name' => 'Sample Campaign',
  'budgetAmount' => 100000,
  'budgetPeriod' => 'Daily',
  'geoTargeting' => {'countryTargets' => {'countries' => ['US']}},
  'languageTargeting' => {'languages' => ['en']},
  'schedule' => $schedule
});

# Add campaign.
$campaign = $service->call('addCampaign' => $campaign, @headers)->result();

View full sample

Code sample not available.
 
47
48
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

# Create new campaign structure with ad scheduling set to show ads on Monday,
# Wednesday, and Friday from 8:00am to 5:00pm. Each bid is multiplied by 1.0.
interval_template = """
  <intervals>
    <day>%s</day>
    <endHour>%s</endHour>
    <endMinute>%s</endMinute>
    <multiplier>%s</multiplier>
    <startHour>%s</startHour>
    <startMinute>%s</startMinute>
  </intervals>"""
schedule_template = """
  %s
  <status>%s</status>"""
days = ['Monday', 'Wednesday', 'Friday']
intervals = ''
for index in range(len(days)):
  intervals += interval_template % (days[index], '17', '0', '1.0', '8', '0')
schedule = SOAPpy.Types.untypedType(schedule_template % (intervals, 'Enabled'))

# Create new campaign structure.
campaign = {
  'name': 'Sample Campaign',
  'budgetAmount': SOAPpy.Types.untypedType('100000'),
  'budgetPeriod': SOAPpy.Types.untypedType('Daily'),
  'geoTargeting': {'countryTargets': {'countries': ['US']}},
  'languageTargeting': {'languages': ['en']},
  'schedule': schedule
}

# Add campaign.
campaign = campaign_service.addCampaign(campaign)

View full sample

Code sample not available.
 
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

# Create new campaign structure with ad scheduling set to show ads on Monday,
# Wednesday, and Friday from 8:00am to 5:00pm. Each bid is multiplied by 1.0.
intervals = []
['Monday', 'Wednesday', 'Friday'].each do |day|
  intervals << {
    :day => day,
    :endHour => 17,
    :endMinute => 0,
    :multiplier => 1.0,
    :startHour => 8,
    :startMinute => 0,
  }
end

schedule = {
  :intervals => intervals,
  :status => 'Enabled',
}

# Create a new campaign structure.
campaign_data = {
  :name => 'Sample Campaign',
  :budgetAmount => 100000,
  :budgetOptimizerSettings => SOAP::SOAPNil.new,
  :budgetPeriod => 'Daily',
  :contentTargeting => SOAP::SOAPNil.new,
  :geoTargeting => {:countryTargets => {:countries => ['US']},
    :targetAll => false},
  :id => SOAP::SOAPNil.new,
  :languageTargeting => {:languages => ['en']},
  :networkTargeting => {:networkTypes => ['SearchNetwork', 'ContentNetwork']},
  :schedule => schedule,
  :status => 'Active',
}

# Add campaign.
campaign = campaign_service.addCampaign(:campaign => campaign_data
  ).addCampaignReturn

View full sample

Code sample not available.
 
46
47
48
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
80
81
82
83
84
85

# Create new campaign structure with ad scheduling set to show ads on Monday,
# Wednesday, and Friday from 8:00am to 5:00pm. Each bid is multiplied by 1.0.
$schedule =
  '<schedule>' .
  '<intervals>' .
  '<day>Monday</day><endHour>17</endHour><endMinute>0</endMinute>' .
  '<multiplier>1.0</multiplier><startHour>8</startHour>' .
  '<startMinute>0</startMinute>' .
  '</intervals>' .
  '<intervals>' .
  '<day>Wednesday</day><endHour>17</endHour><endMinute>0</endMinute>' .
  '<multiplier>1.0</multiplier><startHour>8</startHour>' .
  '<startMinute>0</startMinute>' .
  '</intervals>' .
  '<intervals>' .
  '<day>Friday</day><endHour>17</endHour><endMinute>0</endMinute>' .
  '<multiplier>1.0</multiplier><startHour>8</startHour>' .
  '<startMinute>0</startMinute>' .
  '</intervals>' .
  '<status>Enabled</status>' .
  '</schedule>';

# Create new campaign structure.
$campaign =
  '<campaign>' .
  '<name>Sample Campaign</name>' .
  '<budgetAmount>100000</budgetAmount>' .
  '<budgetPeriod>Daily</budgetPeriod>' .
  '<geoTargeting>' .
  '<countryTargets><countries>US</countries></countryTargets>' .
  '</geoTargeting>' .
  '<languageTargeting><languages>en</languages></languageTargeting>' .
  $schedule .
  '</campaign>';
$request_xml =
  '<addCampaign>' . $campaign . '</addCampaign>';

# Add campaign.
$campaign = $campaign_service->call('addCampaign', $request_xml);
$campaign = $campaign['addCampaignReturn'];

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

    <!-- Creates a new campaign with ad scheduling. -->
    <addCampaign>
      <campaign>
        <budgetAmount>100000</budgetAmount>
        <budgetPeriod>Daily</budgetPeriod>
        <geoTargeting>
          <countryTargets>
            <countries>US</countries>
          </countryTargets>
        </geoTargeting>
        <languageTargeting>
          <languages>en</languages>
        </languageTargeting>
        <name>Sample Campaign</name>
        <networkTargeting>
          <networkTypes>SearchNetwork</networkTypes>
          <networkTypes>ContentNetwork</networkTypes>
        </networkTargeting>
        <schedule>
          <intervals>
            <day>Monday</day>
            <endHour>17</endHour>
            <endMinute>0</endMinute>
            <multiplier>1.0</multiplier>
            <startHour>8</startHour>
            <startMinute>0</startMinute>
          </intervals>
          <intervals>
            <day>Wednesday</day>
            <endHour>17</endHour>
            <endMinute>0</endMinute>
            <multiplier>1.0</multiplier>
            <startHour>8</startHour>
            <startMinute>0</startMinute>
          </intervals>
          <intervals>
            <day>Friday</day>
            <endHour>17</endHour>
            <endMinute>0</endMinute>
            <multiplier>1.0</multiplier>
            <startHour>8</startHour>
            <startMinute>0</startMinute>
          </intervals>
          <status>Enabled</status>
        </schedule>
        <status>Active</status>
      </campaign>
    </addCampaign>

View full sample

Select a programming language to view its sample

addCampaignList

Creates multiple new campaigns. If any of the new campaigns are invalid, none will be added.

Parameters

campaigns Campaign[]
Information for the new campaigns. See addCampaign for information on setting fields on new Campaign objects.

Response

Campaign[] The new Campaign objects with their IDs set, in the same order as the input data.

getActiveAdWordsCampaigns +v13

Returns all information about active campaigns belonging to the customer issuing the request. Ad Automator campaigns will not be included in the list of returned campaigns.

Response

Campaign[] List of Campaign objects

getAllAdWordsCampaigns

Returns all information about all campaigns belonging to the customer issuing the request. Ad Automator campaigns will not be included in the list of returned campaigns.

Parameters

dummy int
Ignored. This parameter is present because some SOAP toolkits have a hard time calling a function with headers but no parameters.

Response

Campaign[] List of campaigns

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 information about all campaigns that belong to -->
    <!-- the customer issuing the request. -->
    <getAllAdWordsCampaigns>
      <dummy>0</dummy>
    </getAllAdWordsCampaigns>

View full sample

Select a programming language to view its sample

getCampaign

Returns all information about a specified campaign.

Parameters

id int
ID of the campaign, which must already exist.

Response

Campaign A Campaign object

getCampaignList

Returns all information about multiple campaigns.

Parameters

ids int[]
List of campaign IDs to retrieve. If any IDs are invalid, an exception is thrown.

Response

Campaign[] List of Campaign objects, in the same order as the input list.

getCampaignStats

Returns statistics for a list of campaigns. See StatsRecord for details about the statistics returned. The time granularity is one day, and is always with respect to the account's local timezone.

Parameters

campaignIds int[]
IDs of the campaigns to query for statistics
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 containing information about the activity on the campaign. The order of StatsRecord objects returned may be different from the order in which the id's were requested.

getConversionOptimizerEligibility

Checks if the specified campaigns are eligible to use conversion optimizer. To be eligible, a campaign must satisfy the following criteria:

  • All ad groups within the campaign must be CPC-based and keyword-targeted.
  • Budget optimizer is not enabled
  • Must have conversion tracking enabled with at least 200 conversions in the past 30 days.

For more information, see What is the Conversion Optimizer? in the AdWords Help Center.

Parameters

campaignIds int[]
The list of campaigns to check.

Response

ConversionOptimizerEligibility[] An array of ConversionOptimizerEligibility objects, containing information about whether the given campaigns are eligible to use conversion optimizer.

See Also

getOptimizeAdServing

Returns true if optimized ad serving is enabled for the specified campaign. If optimized ad serving is enabled, ads with the highest clickthrough rates are favored. This setting applies to all ad groups in the campaign.

More Information

.

Parameters

campaignId int
ID of the campaign to return settings for

Response

boolean True if optimization is enabled, false otherwise.

getRecommendedBudgetList +v13

Returns the recommended budgets for the specified campaigns.

Parameters

campaignIds int[]
List of campaign ids to check. If any IDs are invalid, an exception is thrown.

Response

CampaignBudget[] A list of CampaignBudget objects, in the same order as the input list.

setOptimizeAdServing

Enables or disables optimized ad serving for the specified campaign. New campaigns have optimized ad serving enabled by default. This setting can only be toggled for campaigns that have at least one ad associated with them.

Parameters

campaignId int
ID of the campaign to update
enable boolean
If true, optimization will be turned on; if false, optimization will be turned off.

Response

(none)

See Also

updateCampaign

Updates the settings for an existing campaign.

Parameters

campaign Campaign
Campaign to update. id is required and must refer to an existing campaign. id cannot be changed. startDay cannot be changed if the campaign has already started. Unspecified fields will not be modified.

Response

(none)

updateCampaignList

Updates the settings for multiple existing campaigns.

Parameters

campaigns Campaign[]
A list of Campaign objects. See updateCampaign.

Response

(none)