Previously, we got you set up to make your first API call, and we reviewed the configuration ingredients required for making calls to the API.
In this guide, we'll take a look at the structure of a typical AdWords API code sample.
Then we'll examine a few common use cases that illustrate how the code samples can be used to integrate practically any API functionality into your app.
Anatomy of an API code sample
The code samples provided with the client libraries cover the most common API functions. They handle most back-end tasks automatically and greatly simplify AdWords API apps development.
Let's take a look at the typical structure of an AdWords API code example. Click the tab below for the language of your choice:
Java
In your IDE, open the sample file we used in the previous guide: GetCampaigns.java.
In GetCampaigns.java, you'll notice some boilerplate code in
main
that does the following:
- Credential generation
- Session creation
- Services instantiation

You'll become familiar with these as you explore the code samples in the client library.
There's one other line in the GetCampaigns sample you might need: Recall that in the previous guide, we set the client customer ID in the ads.properties file.
But what if you have many client customer accounts under your manager
account? In that case, you can remove the client customer ID from the
ads.properties file, and programmatically set it via the session object.
After the object is built, call setClientCustomerID
to dynamically
set it.
// Construct an AdWordsSession. AdWordsSession session = new AdWordsSession.Builder() .fromFile() .withOAuth2Credential(oAuth2Credential) .build(); session.setClientCustomerID("123-456-7890"); AdWordsServices adWordsServices = new AdWordsServices(); runExample(adWordsServices, session);
C#
In your IDE, open the sample file we used in the previous guide: GetCampaigns.cs.
You'll see some boilerplate code inmain
that references
AdWordsUser
:
public static void Main(string[] args) { GetCampaigns codeExample = new GetCampaigns(); Console.WriteLine(codeExample.Description); try { codeExample.Run(new AdWordsUser()); } }
The most important classes in the C# library are the AdsUser classes. AdsUser classes typically encapsulate a single Ads account, in this case a Google Ads account.
The AdWordsUser
class allows you to create a pre-configured
service class that can be used for making API calls, using the settings
specified in your application's app.config
file.
// Create a new AdWordsUser with the App.config settings. AdWordsUser user = new AdWordsUser();
But what if you have many client customer accounts under your manager
account? In that case, you can set it programmatically using the Config property
of the AdsUser
object to configure that user at runtime:
// Create a default AdWordsUser instance. If any configuration // is available in App.config, those will be used. AdWordsUser user = new AdWordsUser(); // Override a specific setting at runtime. AdWordsAppConfig config = (AdWordsAppConfig) user.Config; user.Config.clientCustomerId = "123-456-7890";
Another option is to use the constructor that accepts an AdWordsAppConfig instance, for example:
// Create a config object with the values in App.config. AdWordsAppConfig config = new AdWordsAppConfig(); // Override any specific setting you wish to change. user.Config.clientCustomerId = "123-456-7890"; AdWordsUser user = new AdWordsUser(config);
Python
In your IDE, open the sample file we used in the previous guide: get_campaigns.py.
In the sample, the comments indicate that the LoadFromStorage
method is pulling credentials and properties from the googleads.yaml
file. Recall that in the previous guide, we set the
client customer ID in googleads.yaml. The LoadFromStorage
method
defaults to looking for a file with this name in your home directory, though
you could pass in a path to any file with the correct yaml contents:
To use the default location - your home directory:
adwords_client = adwords.AdWordsClient.LoadFromStorage()
To pass in the location of the file:
adwords_client = adwords.AdWordsClient.LoadFromStorage('C:\My\Directory\googleads.yaml')
But what if you have many client customer accounts under your manager account? In that case, you can programmatically set the client customer ID at runtime with the following code:
adwords_client = AdWordsClient.LoadFromStorage() adwords_client.SetClientCustomerId('123-456-7890')
PHP
In your IDE, open the sample file GetCampaigns.php.
The example first generates an OAuth token:
// Generate a refreshable OAuth2 credential for authentication. $oAuth2Credential = (new OAuth2TokenBuilder()) ->fromFile() ->build();
It then uses the token to construct an API session wherein the
runExample()
function is executed:
// Construct an API session configured from a properties file and the OAuth2 // credentials above. $session = (new AdWordsSessionBuilder()) ->fromFile() ->withOAuth2Credential($oAuth2Credential) ->build(); self::runExample(new AdWordsServices(), $session);
runExample()
is the primary function in this example; it
retrieves campaign IDs and names through the use of a selector from
CampaignService.
Perl
In your IDE, open the sample file we used in the previous guide: get_campaigns.pl.
In the sample, you'll notice some code that gets credential info from your configuration file, adwords.properties:
# Get AdWords API Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
Recall that in the previous guide, we set the client customer ID in the adwords.properties file.
But what if you have many client customer accounts under your manager
account? In that case, you can remove the client customer ID from
adwords.properties
, and programmatically set it by calling
set_client_id
:
# Get AdWords API Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"}); $client->set_client_id("123-456-7890");
Ruby
Open the sample file we used in the previous guide: get_campaigns.rb.
In the sample, you'll notice some boilerplate code in main
that
handles pulling credential info from the adwords_api.yml
configuration file.
# AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new
There's one other line in the sample you might need: Recall that in the previous guide, we set the client customer ID in the adwords_api.yml configuration file.
But what if you have many client customer accounts under your manager
account? In that case, you can remove the client customer ID from the
adwords_api.yml file, and programmatically set it via the AdWords session
object. After the object is built, call adwords.config.set
to
dynamically set it.
# Set a new CID value adwords.config.set("authentication.client_customer_id", "123-456-7890")
Accessing the code samples
You can browse all the AdWords API code samples on our client library and samples pages. The samples cover all the main areas of API functionality, including:
- Account management
- Campaign management
- Error handling
- Optimization
- Reporting
- Targeting
Now that you understand the structure of a typical AdWords API code sample, we'll look at some use cases that demonstrate how the code samples can be used for almost any API function.
The two main buckets of the API's functionality are reporting and automation. Let's start with reporting.
Using code samples for reporting
We'll begin with a code sample that downloads a criteria performance report:
Java
Go to your IDE and open DownloadCriteriaReport.java.
You'll see the same boilerplate code in main
that we looked at
earlier:
public static void main(String[] args) throws Exception { // Generate a refreshable OAuth2 credential. Credential oAuth2Credential = new OfflineCredentials.Builder() .forApi(Api.ADWORDS) .fromFile() .build() .generateCredential(); // Construct an AdWordsSession. AdWordsSession session = new AdWordsSession.Builder() .fromFile() .withOAuth2Credential(oAuth2Credential) .build();
But it's the RunExample
method that has the interesting code in
this class. Here we create an object hierarchy defining the report we want:
// Create report definition. ReportDefinition reportDefinition = new ReportDefinition(); reportDefinition.setReportName("Criteria performance report #" + System.currentTimeMillis()); reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.YESTERDAY); reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT); reportDefinition.setDownloadFormat(DownloadFormat.CSV);
We then pass it to an instance of ReportDownloader
:
ReportDownloadResponse response = new ReportDownloader(session).downloadReport(reportDefinition); response.saveToFile(reportFile);
Go ahead and run DownloadCriteriaReport.java
.
The IDE console will print the location of the downloaded file.
You'll notice the sample code specifies a report type, in this case a criteria performance report.
reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);
The sample also specifies some fields to retrieve for the report.
Selector selector = new Selector(); selector.getFields().addAll(Lists.newArrayList("CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria", "FinalUrls", "Impressions", "Clicks", "Cost"));
C#
Go to your IDE and open DownloadCriteriaReport.cs.
You'll see the same boilerplate code we saw in the previous example, that handles authentication by pulling values from the app.config file:
public static void Main(string[] args) { GetCampaigns codeExample = new GetCampaigns(); Console.WriteLine(codeExample.Description); try { codeExample.Run(new AdWordsUser()); } }
But the interesting code in this sample is where we create an object hierarchy defining the report we want:
public void Run(AdWordsUser user, string fileName) { ReportDefinition definition = new ReportDefinition() { reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT", reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT, downloadFormat = DownloadFormat.GZIPPED_CSV, dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS, } }
Go ahead and run DownloadCriteriaReport.cs.
The console will print the location of the downloaded file.
You'll notice the sample code specifies a report type, in this case a criteria performance report.
reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,
The sample also specifies some fields to retrieve for the report.
selector = new Selector() { fields = new string[] {"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria", "FinalUrls", "Clicks", "Impressions", "Cost"}, predicates = new Predicate[] { Predicate.In("Status", new string[] {"ENABLED", "PAUSED"}) } }
Python
Go to your IDE and open download_criteria_report_with_selector.py.
You'll see the same boilerplate code we saw in the previous example, that handles authentication by pulling values from the googleads.yaml config file:
adwords_client = adwords.AdWordsClient.LoadFromStorage() main(adwords_client)
But the interesting code in this sample is the object hierarchy defining the report we want:
# Create report definition. report = { 'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT', 'dateRangeType': 'LAST_7_DAYS', 'reportType': 'CRITERIA_PERFORMANCE_REPORT', 'downloadFormat': 'CSV', 'selector': { 'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType', 'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost'] } }
We then pass it to an instance of ReportDownloader
:
report_downloader.DownloadReport( report, sys.stdout, skip_report_header=False, skip_column_header=False, skip_report_summary=False)
Go ahead and run download_criteria_report_with_selector.py
.
Your console will print the location of the downloaded file.
You'll notice the sample code specifies a report type, in this case a criteria performance report.
The sample also specifies some fields to retrieve for the report in the 'selector' section, for example, 'CampaignId', 'AdGroupId', etc.
PHP
Go to your IDE and open DownloadCriteriaReportWithSelector.php.
The example has the standard code for authentication and building an AdWords
API session. It's in the primary function runExample()
where a
selector is constructed and the report defined:
// Create selector. $selector = new Selector(); $selector->setFields(['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType', 'Impressions', 'Clicks', 'Cost']); // Create report definition. $reportDefinition = new ReportDefinition(); $reportDefinition->setSelector($selector); $reportDefinition->setReportName( 'Criteria performance report #' . uniqid()); $reportDefinition->setDateRangeType( ReportDefinitionDateRangeType::LAST_7_DAYS); $reportDefinition->setReportType( ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT); $reportDefinition->setDownloadFormat(DownloadFormat::CSV);
Note that the example specifies a CRITERIA_PERFORMANCE_REPORT for the report type and also the fields to retrieve for the report.
The report definition is then passed to a report downloader:
// Download report. $reportDownloader = new ReportDownloader($session); $reportDownloadResult = $reportDownloader->downloadReport($reportDefinition); $reportDownloadResult->saveToFile($filePath); printf("Report with name '%s' was downloaded to '%s'.\n", $reportDefinition->getReportName(), $filePath);
Run DownloadCriteriaReportWithSelector.php
and the console will
print the location of the downloaded file.
Perl
Go to your IDE and open download_criteria_report_with_selector.pl.
You'll see the same boilerplate code that we saw in the previous example, that handles authentication by pulling values from the adwords.properties configuration file:
# Get AdWords API Client, credentials will be read from ~/adwords.properties. my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
But the interesting code in this sample is where we create a selector and report definition, defining the report we want:
my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({ reportName => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today, dateRangeType => "LAST_7_DAYS", reportType => "CRITERIA_PERFORMANCE_REPORT", downloadFormat => "CSV", selector => $selector });
We then pass it to an instance of ReportDownloader
:
# Download the report using the appropriate method on ReportDownloadHandler. my $result; if ($output_file) { $result = $report_handler->save($output_file); } else { $result = $report_handler->get_as_string(); }
Go ahead and run download_criteria_report_with_selector.pl
.
The console will print the location of the downloaded file.
You'll notice the sample code specifies a report type, in this case a criteria performance report.
reportType => "CRITERIA_PERFORMANCE_REPORT",
The sample also specifies some fields to retrieve for the report.
# Create selector. my $selector = Google::Ads::AdWords::Reports::Selector->new({ fields => [ "CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria", "FinalUrls", "Impressions", "Clicks", "Cost" ] });
Ruby
Open download_criteria_report_with_selector.rb.
You'll see the same boilerplate code that we looked in the previous example, that handles authentication by pulling values from the adwords_api.yml configuration file:
def download_criteria_report_with_selector(file_name) # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new
But the interesting code in this sample is where we create an object hierarchy defining the report we want:
# Define report definition. You can also pass your own XML text as a string. report_definition = { :selector => { :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType', 'FinalUrls', 'Impressions', 'Clicks', 'Cost'], }, ... :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT', :report_type => 'CRITERIA_PERFORMANCE_REPORT', :download_format => 'CSV', :date_range_type => 'LAST_7_DAYS', }
We then pass it to the report_utils.download_report_as_file
method:
# Download report, using "download_report_as_file" utility method. # To retrieve the report as return value, use "download_report" method. report_utils.download_report_as_file(report_definition, file_name) puts "Report was downloaded to '%s'." % file_name end
Go ahead and run download_criteria_report_with_selector.rb
. The
location of the downloaded file will be printed out on the console.
You'll notice the sample code specifies a report type, in this case a criteria performance report.
:report_type => 'CRITERIA_PERFORMANCE_REPORT',
The sample also specifies some fields to retrieve for the report.
:fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType', 'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
See the Report Types page for the complete list of report types and the fields they contain.
You can use this code sample, along with the information on the Report Types page, to define, create, and download any kind of reports you need.
AdWords Query Language (AWQL)
In addition to defining reports with an object hierarchy, you could also use the AdWords Query Language (AWQL). This is a SQL-like language that allows you to build reports in a less verbose way than through objects.
Java
Compare the sample code we just ran with DownloadCriteriaReportWithAWQL.java: They retrieve the same report, but the AWQL is more concise. The report types and fields are the same for either approach.
String query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " + "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " + "WHERE Status IN [ENABLED, PAUSED] " + "DURING YESTERDAY";
C#
Compare the sample code we just ran with DownloadCriteriaReportWithAWQL.cs: They retrieve the same report, but the AWQL is more concise. The report types and fields are the same for either approach.
string query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, Impressions, " + "Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] " + "DURING LAST_7_DAYS";
Python
Compare the sample code we just ran with download_criteria_report_with_awql.py: They retrieve the same report, but the AWQL is more concise. The report types and fields are the same for either approach.
report_query = ('SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' 'FinalUrls, Impressions, Clicks, Cost ' 'FROM CRITERIA_PERFORMANCE_REPORT ' 'WHERE Status IN [ENABLED, PAUSED] ' 'DURING LAST_7_DAYS')
PHP
Compare the selector report download example with DownloadCriteriaReportWithAwql.php. Both define the same report types and fields and retrieve the same report, but the AWQL approach is more concise:
// Create report query to get the data for last 7 days. $reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' . 'WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS';
Perl
Compare the sample code we just ran with download_criteria_report_with_awql.pl: They retrieve the same report, but the AWQL is more concise. The report types and fields are the same for either approach.
my $report_query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " . "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " . "WHERE Status IN [ENABLED, PAUSED] " . "DURING $last_4_days, $yesterday";
In this case, the date range for the report is defined in the code directly preceding the AWQL:
# Create report query. my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24); my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday); (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24 * 4); my $last_4_days = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
Ruby
Compare the sample code we just ran with download_criteria_report_with_awql.rb: They retrieve the same report, but the AWQL is more concise. The report types and fields are the same for either approach.
report_query = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' + 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' + 'WHERE Status IN [ENABLED, PAUSED] ' + 'DURING %s' % date_range
In this case, the date range is defined in the code directly preceding the AWQL:
# Prepare a date range for the last week. Instead you can use 'LAST_7_DAYS'. date_range = '%s,%s' % [ DateTime.parse((Date.today - 7).to_s).strftime('%Y%m%d'), DateTime.parse((Date.today - 1).to_s).strftime('%Y%m%d') ]
Now that you understand the fundamentals of reporting, you have the tools needed to start building your own custom reporting platform.
Using code samples for automation
Here we'll examine how you can use the code samples to make updates to your Google Ads accounts, and a few other popular use cases, and see how these examples serve as the basis for almost any kind of automation.
Pause and resume ad groups
One of the most common API use cases is to pause and resume ad groups. For example, you could pause an ad when inventory for an item is depleted, resulting in better use of your advertising budget.
This use case highlights the power of integrating your own systems, such as inventory tracking, with the AdWords API.
We'll use the code samples to pause and resume an ad group:
Java
Start your IDE and open the UpdateAdGroup.java sample.
We see again the typical boilerplate code in main
that we saw
before. This time main
has a placeholder string near the bottom for
the ID of the ad group.
public static void main(String[] args) throws Exception { // Generate a refreshable OAuth2 credential. Credential oAuth2Credential = new OfflineCredentials.Builder() .forApi(Api.ADWORDS) .fromFile() .build() .generateCredential(); // Construct an AdWordsSession. AdWordsSession session = new AdWordsSession.Builder() .fromFile() .withOAuth2Credential(oAuth2Credential) .build(); Long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE"); }
Where would you get that ID? You could get it programmatically, through the
get()
method of the
AdGroupService
interface. A shortcut for getting the ID is to grab it from the URL of the
Google Ads UI when viewing that ad group.
Once again the runExample
method has the interesting code. Let's
see what it's doing, step by step:
First it gets a reference to the AdGroupService
interface
because it will be updating an ad group. To update other entities you would use
their corresponding service. A full list of services is available in
Objects,
Methods, and Services.
// Get the AdGroupService. AdGroupServiceInterface adGroupService = adWordsServices.get(session, AdGroupServiceInterface.class);
Then, it creates a new ad group object and sets the ID of the new object to the ID of the ad group it wants to update.
// Create ad group with updated status. AdGroup adGroup = new AdGroup(); adGroup.setId(adGroupId);
Then it sets the status to PAUSED
.
adGroup.setStatus(AdGroupStatus.PAUSED);
It then creates an AdGroupOperation
using the newly created ad
group object as the operand, and SET
as the operator.
// Create operations. AdGroupOperation operation = new AdGroupOperation(); operation.setOperand(adGroup); operation.setOperator(Operator.SET);
Last, it calls the mutate()
method of the
AdGroupService
interface, passing in the ad group operation
object.
// Update ad group. AdGroupReturnValue result = adGroupService.mutate(operations);
Go ahead and replace the placeholder with an adgroup ID from your test client account and try running the code. After it runs, log in to the test account in the Google Ads UI, and confirm the status has been changed.
C#
In your IDE, and open the UpdateAdGroup.cs sample.
We see again the typical boilerplate code in main
that we saw
in the earlier sections. This time main
has a placeholder string
near the bottom for the ID of the ad group.
public static void Main(string[] args) { UpdateAdGroup codeExample = new UpdateAdGroup(); Console.WriteLine(codeExample.Description); try { long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE"); codeExample.Run(new AdWordsUser(), adGroupId); } }
Where would you get that ID? You could get it programmatically, through the
get()
method of the AdGroupService
interface. A shortcut for getting the ID is to grab it from the URL of the
Google Ads UI when viewing that ad group.
Once again the runExample
method has the interesting code.
Let's see what it's doing, step by step:
First it gets a reference to the AdGroupService
interface
because it will be updating an ad group. To update other entities you would use
their corresponding service. A full list of services is available in the Objects,
Methods, and Services guide.
public void Run(AdWordsUser user, long adGroupId) { // Get the AdGroupService. AdGroupService adGroupService = (AdGroupService) user.GetService(AdWordsService.v201809.AdGroupService); }
Then, it creates a new AdGroup
object and sets the ID of the
new object to the ID of the ad group it wants to update.
// Create the ad group. AdGroup adGroup = new AdGroup(); adGroup.status = AdGroupStatus.PAUSED; adGroup.id = adGroupId;
It also sets the status to PAUSED
.
adGroup.status = AdGroupStatus.PAUSED;
It then creates an AdGroupOperation
using the newly created
adGroup
object as the operand, and SET
as the
operator.
// Create the operation. AdGroupOperation operation = new AdGroupOperation(); operation.@operator = Operator.SET; operation.operand = adGroup;
Last, it calls the mutate()
method of the
AdGroupService
interface, passing in the
AdGroupOperation
object.
// Update the ad group. AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});
Go ahead and replace the placeholder with an ad group ID from your test client account and try running the code. After it runs, log in to the test account in the Google Ads UI, and confirm the status has been changed.
Python
In your IDE, open the update_ad_group.py sample.
We see again the typical boilerplate code where the
LoadFromStorage
method is pulling credentials and properties from
the googleads.yaml
config file. This time a placeholder string is added for the ID of the ad
group.
AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'
Where would you get that ID? You could get it programmatically, through the
get()
method of the AdGroupService
interface. A shortcut for getting the ID is to grab it from the URL of the
Google Ads UI when viewing that ad group.
The interesting code comes after. Let's see what it's doing, step by step:
First it gets a reference to the AdGroupService
interface
because it will be updating an ad group. To update other entities you would use
their corresponding service. A full list of services is available in the Objects,
Methods, and Services guide.
def main(client, ad_group_id): # Initialize appropriate service. ad_group_service = client.GetService('AdGroupService', version='v201809')
Then, it sets the ID to the ID of the ad group it wants to update, and sets
the status to PAUSED
.
# Construct operations and update an ad group. operations = [{ 'operator': 'SET', 'operand': { 'id': ad_group_id, 'status': 'PAUSED'
It then creates an ad group operation using the newly created ad group
object as the operand, and SET
as the operator, and sets the
status to PAUSED
.
# Construct operations and update an ad group. operations = [{ 'operator': 'SET', 'operand': { 'id': ad_group_id, 'status': 'PAUSED'
Last, it calls the mutate()
method of the ad group service
interface, passing in the ad group operation object.
ad_groups = ad_group_service.mutate(operations)
Go ahead and replace the placeholder with an adgroup ID from your test client account and try running the code. After it runs, log in to the test account in the Google Ads UI, and confirm the status has been changed.
PHP
In your IDE, open PauseAd.php.
The particular ad is identified through the ad group and ad IDs:
const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'; const AD_ID = 'INSERT_AD_ID_HERE';
The ad group ID can be retrieved through the get()
method
from AdGroupService,
or from the URL of the Google Ads UI when viewing the ad group.
Let's now go through runExample()
step-by-step:
- Get a reference to
AdGroupService
since we're updating an ad group.$adGroupAdService = $adWordsServices->get($session, AdGroupAdService::class);
- Create an ad object.
$ad = new Ad(); $ad->setId($adId);
- Creates an ad group ad object and set its ad group ID and ad.
$adGroupAd = new AdGroupAd(); $adGroupAd->setAdGroupId($adGroupId); $adGroupAd->setAd($ad);
- Set the status of the ad group ad to
PAUSED
.$adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
- Set up an operation and send it off to AdGroupAdService through the
mutate()
method.// Create ad group ad operation and add it to the list. $operation = new AdGroupAdOperation(); $operation->setOperand($adGroupAd); $operation->setOperator(Operator::SET); $operations[] = $operation; // Pause the ad on the server. $result = $adGroupAdService->mutate($operations);
Replace the placeholders with appropriate IDs from your test client account and run the code. After it completes, log in to the test account from the Google Ads UI and verify that the status was changed.
Perl
In your IDE, open the update_ad_group.pl sample.
We see again at the bottom the typical boilerplate code we saw before, that pulls credentials from the adwords.properties configuration file.
In this sample, a placeholder string is added for the ID of the ad group and ad you want to pause.
# Replace with valid values of your account. my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";
Where would you get that ID? You could get it programmatically, through the
get()
method of the AdGroupService
interface. A shortcut for getting the ID is to grab it from the URL of the
Google Ads UI when viewing that ad group.
The interesting code in this sample comes when the example is run. Let's see what it's doing, step by step:
First it creates an ad group with updated status using the specified
adGroupID
. To update other entities you would use their
corresponding service. A full list of services is available in the Objects,
Methods, and Services guide. It then sets the status to
PAUSED
.
# Create ad group with updated status. my $ad_group = Google::Ads::AdWords::v201809::AdGroup->new({ id => $ad_group_id, status => "PAUSED" });
It then creates an ad group operation using the newly created ad group
object as the operand, and SET
as the operator.
# Create operation. my $operation = Google::Ads::AdWords::v201809::AdGroupOperation->new({ operand => $ad_group, operator => "SET" });
Last, it calls the mutate()
method of the
AdGroupService
interface, passing in the ad group operation
object.
# Update ad group. my $result = $client->AdGroupService()->mutate({operations => [$operation]});
Go ahead and replace the placeholder with an adgroup ID from your test client account and try running the code. After it runs, log in to the test account in the Google Ads UI, and confirm the status has been changed.
Ruby
Open the update_ad_group.rb sample.
We see again the typical boilerplate code in that we saw before, that pulls credentials from the adwords_api.yml configuration file. We see a little further down a placeholder string for the ID of the ad group.
# ID of an ad group to update. ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
Where would you get that ID? You could get it programmatically, through the
get()
method of the AdGroupService
interface. A shortcut for getting the ID is to grab it from the URL of the
Google Ads UI when viewing that ad group.
Once again the interesting code is where the sample is run. Let's see what it's doing, step by step:
First it gets a reference to the AdGroup
service interface
because it will be updating an ad group. To update other entities you would
use their corresponding service. A full list of services is available in the Objects,
Methods, and Services guide.
ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
Then, it creates a new ad group object and sets the ID of the new object to
the ID of the ad group it wants to update, and sets its status to
PAUSED
, using SET
as the operator.
# Prepare for updating ad group. operation = { :operator => 'SET', :operand => { :status => 'PAUSED', :id => ad_group_id } }
Last, it calls the mutate()
method of the
AdGroupService
interface, passing in the ad group operation
object.
# Update ad group. response = ad_group_srv.mutate([operation])
Go ahead and replace the placeholder with an adgroup ID from your test client account and try running the code. After it runs, log in to the test account in the Google Ads UI, and confirm the status has been changed.
Reviewing the pattern
The same process and pattern we used to pause and resume the ad group above is used for most updates through the API, so it's worth reviewing the steps:
- Create a new object.
- Set its ID to be the ID of the entity you want to modify.
- Set the new value of the property on that new object.
- Create an operation object with
SET
as the operator and this new entity object as the operand. - Pass the operation object into the
mutate()
method of the appropriate service.
This was an update, so we used the SET
operator. Adds or removals would use
the ADD
or REMOVE
operators.
If this seems confusing, take a look at other code samples and you'll quickly see the pattern.
Now that you know the pattern, you can easily make many other updates, for example modifying the bid for an ad group.
Modify bids for an ad group
Another popular use case is programmatically modifying a bid. The canonical example is raising the bid for an umbrella ad when its raining. Your app could consume a weather web service, and then use the AdWords API to increase the bid for this ad group.
You could modify the same UpdateAdGroup sample we looked at above to make this
update: Instead of setting AdGroupStatus
you would set the bidding
strategy. See the Bidding guide for more
information.
Create new campaigns
Another use case:
Java
In your IDE look at AddCampaigns.java.
It's a lot of code but follows the same pattern as above. In this case, once
the object hierarchy is created we use the ADD
operator to add a
new budget via the BudgetService
, and new campaigns via the
CampaignService
.
We don't need to set the IDs here because these are new entities that don't have IDs yet.
C#
In your IDE, look at AddCampaigns.cs.
It's a lot of code but follows the same pattern as above. In this case, once
the object hierarchy is created we use the ADD
operator to add a
new budget via the BudgetService
, and new campaigns via the
CampaignService
.
We don't need to set the IDs here because these are new entities that don't have IDs yet.
Python
In your IDE, look at add_campaigns.py.
It's a lot of code but follows the same pattern as above. In this case, once
the object hierarchy is created we use the ADD
operator to add a
new budget via the BudgetService
, and new campaigns via the
CampaignService
.
We don't need to set the IDs here because these are new entities that don't have IDs yet.
PHP
In your IDE, open AddCampaigns.php.
As usual, the bulk of the logic is in runExample()
. We set up a
budget, campaign, bidding strategy, and optional settings such as network
targeting and frequency cap. Finally, we wrap the campaign with an ADD operator
and send off the operation to CampaignService via mutate()
.
Perl
In your IDE, look at add_campaigns.pl.
It's a lot of code but follows the same pattern as above. In this case, once
the object hierarchy is created we use the ADD
operator to add a
new budget via the BudgetService
, and new campaigns via the
CampaignService
.
We don't need to set the IDs here because these are new entities that don't have IDs yet.
Ruby
Take a look at add_campaigns.rb.
It's a lot of code but follows the same pattern as above. In this case, once
the object hierarchy is created we use the ADD
operator to add a
new budget via the BudgetService
, and new campaigns via the
CampaignService
.
We don't need to set the IDs here because these are new entities that don't have IDs yet.
Next steps
Now that you've got the basics, you'll want to see Objects, Methods, and Services and related guides to learn more about the API's architecture, services, and features.
You'll then be ready to start building your own app, taking full advantage of the increased efficiency through automation, and greater visibility through custom reporting, that the AdWords API offers.