Building Your First AdWords API Application

The goal of this tutorial is to help you create a real, working AdWords API program. The program will be basic, but will use the same building blocks found in the most advanced implementations. Afterwards, you'll be able to turn your program into a full-fledged implementation of your own.

We're going to start by creating a campaign, an ad group, a creative, and a keyword — the essentials of an AdWords campaign. Then, we'll retrieve information about each of those objects. Later, we'll touch on some more advanced functionality, like generating a report of the sort you might run to find out how your account is performing.

Before You Start

We've designed the tutorial to accommodate as many programming environments as possible. In the upper-right corner, you'll find a drop-down menu with a number of programming languages. Go ahead and pick the langauge you'd like to use. We'll display all the examples that follow in that language.

You may also need to configure your machine to work with our examples. To simplify things, we rely on SOAP toolkits — code libraries that know how to interpret WSDL files and encode and decode XML request and response messages — and AdWords API client libraries — additional helper code written specifically for our services. The table below lists what's needed for each langauge. We've also packaged stubs and full source code for all of our listings into starter projects, which you can download if you'd rather not start from scratch.

Language	Client Library	Additional Dependencies	Sample Project
Java	Java Client Library	Java 1.4+	Sample Java Project
C#	.NET Client Library	.NET SDK 1.1+	Sample C# Project
Python	Python Client Library	SOAPpy Toolkit, Python 2.4+	Sample Python Project
PHP	PHP Client Library	PHP 4.4+	Sample PHP Project

Finally, logging into the AdWords API Sandbox requires a Gmail account. If you don't already have one, you can sign up here.

Logging In

The AdWords API Sandbox is a development environment for the AdWords API. It's just like the production API, except you work with dummy AdWords accounts whose ads don't really run and you aren't charged for the calls you make. Both of these things come in handy when you're writing and testing a new application.

Depending on the language you're using, you may have to do some initial setup to make sure the required libraries are imported and you're otherwise fully configured to talk to the API. This and the subsequent code snippets should be added incrementally to the same source file as you build your program.

No language selected! Choose one above.Ensure that the adwords-api JAR file is available in your CLASSPATH.


import java.util.Hashtable;
import com.google.api.adwords.lib.AdWordsServiceLogger;
import com.google.api.adwords.lib.AdWordsUser;
import com.google.api.adwords.v11.*;


public class EmptySample {
  public static void main(String[] args) throws Exception {
    // Your code here.
  }
}From your Visual Studio project, add a reference
to the standard System.Web.Services assembly.
Add a reference to the compiled client library assembly, google-api-adwords-dotnet.
Add a reference to the ICSharpCode.ShapZipLib assembly, available here.


using System;
using System.Collections.Generic;
using System.Collections;
using System.Text;
using com.google.api.adwords.lib;
using com.google.api.adwords.v11;


namespace Sample_Application {
  class EmptySample {
    static void Main(string[] args) {
      // Your code here.
    }
  }
}LIB_HOME = '.' # The path to the client library lib/ directory.
import sys
sys.path.append(LIB_HOME)
import time
from lib.AccountService import AccountService
from lib.CampaignService import CampaignService
from lib.AdGroupService import AdGroupService
from lib.AdService import AdService
from lib.CriterionService import CriterionService
from lib.Client import Client

# Your code here.Modify the settings.ini file to enable the following:

Use_Sandbox = yes
Exchange_Rate = 1
Display_Error_Style = XML


Ensure that the apility.php library is in a location readable by your code,
such as the same directory. In your PHP code, require the library:

<?php
require_once("apility.php");

# Your code here.
?>

To log into the sandbox, you provide some credentials in the form of SOAP headers. (When you're ready to log into the production environment, you do the same, only you pass in an AdWords username and password — which you can obtain here — and a real developer and application token — which you can obtain here.) Once you've set your login info, invoking any old method, like getClientAccounts, prompts the sandbox to create 5 dummy AdWords accounts for you.

No language selected! Choose one above....

Hashtable<String, String> headers = new Hashtable<String, String>();
headers.put("email", "awapi.demo@gmail.com");
headers.put("password", "developer_day");
headers.put("useragent", "Java Demo Application");
headers.put("developerToken", "awapi.demo@gmail.com++USD");
headers.put("applicationToken", "1234567890123456789012");
headers.put("alternateUrl", "https://sandbox.google.com/");
AdWordsUser mccUser = new AdWordsUser(headers);
headers.put("clientId", "client_1+awapi.demo@gmail.com");
AdWordsUser adWordsUser = new AdWordsUser(headers);

AccountInterface accountService =
  (AccountInterface)mccUser.getService(AdWordsUser.ACCOUNT_SERVICE);
String[] clientAccounts = accountService.getClientAccounts();
for(String clientAccount : clientAccounts) {
  System.out.println("Client account: " + clientAccount);
}

......

Hashtable headers = new Hashtable();
headers.Add("email", "awapi.demo@gmail.com");
headers.Add("password", "developer_day");
headers.Add("useragent", "C# Demo Application");
headers.Add("developerToken", "awapi.demo@gmail.com++USD");
headers.Add("applicationToken", "1234567890123456789012");
headers.Add("alternateUrl", "https://sandbox.google.com/");
AdWordsUser mccUser = new AdWordsUser(headers);
headers.Add("clientEmail", "client_1+awapi.demo@gmail.com");
AdWordsUser adWordsUser = new AdWordsUser(headers);

AccountService accountService =
  (AccountService)mccUser.getService("AccountService");
String[] clientAccounts = accountService.getClientAccounts();
foreach (String clientAccount in clientAccounts) {
  Console.Out.WriteLine("Client account: " + clientAccount);
}

......

headers = {
  'email': 'awapi.demo@gmail.com',
  'password': 'developer_day',
  'useragent': 'Python Demo Application',
  'developerToken': 'awapi.demo@gmail.com++USD',
  'applicationToken': '1234567890123456789012',
}

user = Client(headers=headers, path=LIB_HOME)
user.UseMcc(True)

account_service = user.GetAccountService('https://sandbox.google.com')
client_accounts = account_service.GetClientAccounts()
for client_account in client_accounts:
  print('Client account: %s' % client_account)

......

$headers = array();
$headers["Email"] = "awapi.demo@gmail.com";
$headers["Client_Email"] = "client_1+awapi.demo@gmail.com";
$headers["Password"] = "developer_day";
$headers["User_Agent"] = "PHP Demo Application";
$headers["Developer_Token"] = "awapi.demo@gmail.com++USD";
$headers["Application_Token"] = "1234567890123456789012";
$user = new APIlityUser();
$user->setContext($headers);

$clientAccounts = getManagersClientAccounts();
foreach($clientAccounts as $clientAccount) {
  print("Client account: $clientAccount\n");
}

...

Congratulations! You've just developed a runnable AdWords API program. Executing the program on a command line should produce the following output.

Client account: client_1+awapi.demo@gmail.com
Client account: client_2+awapi.demo@gmail.com
Client account: client_3+awapi.demo@gmail.com
Client account: client_4+awapi.demo@gmail.com
Client account: client_5+awapi.demo@gmail.com

If, at any point, the results you get don't match the expected results, you can turn debugging on to view the underlying SOAP transactions.

No language selected! Choose one above.import com.google.api.adwords.lib.AdWordsServiceLogger;

AdWordsServiceLogger.log();In your app.config configuration file:

<configuration>
  <configSections>
    <section name="adwordsHeaders"
             type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <adwordsHeaders>
    <add key="logPath" value="C:\\Logs"/> <!-- or directory of your choice -->
  </adwordsHeaders>
  <system.web>
    <webServices>
      <soapExtensionTypes>
        <add type="com.google.api.adwords.lib.TraceExtension,
                   google-api-adwords-dotnet" priority="1" group="0"/>
      </soapExtensionTypes>
    </webServices>
  </system.web>
</configuration>user.SetDebug(True)In settings.ini configuration file:

Enable_Debug_Mode = yes
; Enable_Debug_Mode = no


print_r($user->getLastSoapRequests());
print_r($user->getLastSoapResponses());

Creating a Campaign

Now, we'll add some elements that make up an AdWords campaign. The top-level container of an AdWords campaign is called, naturally enough, a campaign. A campaign describes budget and targeting information, such as what web properties to run on, for a set of ads.

All monetary values in the API, for instance the daily budget below, are specified in what we term micros. One million micros is equal to one fundamental unit of the local currency for the AdWords account. For example, if the currency is US Dollars, 1,000,000 micros is equal to 1 USD and 10,000 micros is equal to 0.01 USD, or 1 cent.

To create a campaign, you call addCampaign.

No language selected! Choose one above....

CampaignInterface campaignService =
  (CampaignInterface)adWordsUser.getService(AdWordsUser.CAMPAIGN_SERVICE);
Campaign newCampaign = new Campaign();
newCampaign.setName("Sample Campaign - " + java.lang.System.currentTimeMillis());
newCampaign.setStatus(CampaignStatus.Active);
newCampaign.setDailyBudget(500 * 10000L);
newCampaign.setNetworkTargeting(new NetworkType[] {
  NetworkType.SearchNetwork
});
newCampaign = campaignService.addCampaign(newCampaign);
int campaignId = newCampaign.getId();

Campaign[] campaigns = campaignService.getAllAdWordsCampaigns(0);
for(Campaign campaign : campaigns) {
  System.out.println("Campaign: " + campaign.getName());
}

......

CampaignService campaignService =
  (CampaignService)adWordsUser.getService("CampaignService");
Campaign newCampaign = new Campaign();
newCampaign.name = "Sample Campaign - " + System.DateTime.Now.Ticks;
newCampaign.status = CampaignStatus.Active;
newCampaign.dailyBudget = 500 * 10000L;
newCampaign.dailyBudgetSpecified = true;
newCampaign.networkTargeting = new NetworkType[] {
  NetworkType.SearchNetwork
};
newCampaign = campaignService.addCampaign(newCampaign);
int campaignId = newCampaign.id;

Campaign[] campaigns = campaignService.getAllAdWordsCampaigns(0);
foreach (Campaign campaign in campaigns) {
  Console.Out.WriteLine("Campaign: " + campaign.name);
}

......

user.UseMcc(False)
user.SetClientEmail('client_1+awapi.demo@gmail.com')

campaign_service = user.GetCampaignService('https://sandbox.google.com')
new_campaign = {
  'name': 'Sample Campaign - ' + str(time.time()),
  'status': 'Active',
  'dailyBudget': str(500 * 10000),
  'networkTargeting': ['SearchNetwork'],
  }
new_campaign = campaign_service.AddCampaign(new_campaign)[0]
campaign_id = new_campaign['id']

campaigns = campaign_service.GetAllAdWordsCampaigns()
for campaign in campaigns:
  print('Campaign: %s' % campaign['name'])

......

$newCampaign = addCampaign(
  "Sample Campaign - " . time(), //name
  "Active", // status
  null, // startDate
  null, // endDate
  500 * 10000, // dailyBudget
  array("SearchNetwork"), // networkTargeting
  array(), // languages
  null, // geoTargets
  null, // isEnabledSeparateContentBids
  null, // adScheduling
  null // budgetOptimizerSettings
);
$campaignId = $newCampaign->getId();

$campaigns = getAllCampaigns();
foreach($campaigns as $campaign) {
  $campaignName = $campaign->getName();
  print("Campaign: $campaignName\n"); 
}

...

This code should print the name of your new campaign.

Campaign: Sample Campaign

Creating an Ad Group

The second-level container of an AdWords campaign is called an ad group. An ad group bundles a related set of keywords and creatives that will run together. To create an ad group, you call addAdGroup.

No language selected! Choose one above....

AdGroupInterface adGroupService =
  (AdGroupInterface)adWordsUser.getService(AdWordsUser.AD_GROUP_SERVICE);
AdGroup newAdGroup = new AdGroup();
newAdGroup.setName("Sample Ad Group");
newAdGroup.setStatus(AdGroupStatus.Enabled);
newAdGroup.setKeywordMaxCpc(25 * 10000L);
newAdGroup = adGroupService.addAdGroup(campaignId, newAdGroup);
int adGroupId = newAdGroup.getId();

AdGroup[] adGroups = adGroupService.getAllAdGroups(campaignId);
for(AdGroup adGroup : adGroups) {
  System.out.println("Ad group: " + adGroup.getName());
}

......

AdGroupService adGroupService =
  (AdGroupService)adWordsUser.getService("AdGroupService");
AdGroup newAdGroup = new AdGroup();
newAdGroup.name = "Sample Ad Group";
newAdGroup.keywordMaxCpc = 25 * 10000L;
newAdGroup.keywordMaxCpcSpecified = true;
newAdGroup = adGroupService.addAdGroup(campaignId, newAdGroup);
int adGroupId = newAdGroup.id;

AdGroup[] adGroups = adGroupService.getAllAdGroups(campaignId);
foreach (AdGroup adGroup in adGroups) {
  Console.Out.WriteLine("Ad group: " + adGroup.name);
}

......

ad_group_service = user.GetAdGroupService('https://sandbox.google.com')
new_ad_group = {
  'name': 'Sample Ad Group',
  'status': 'Enabled',
  'keywordMaxCpc': str(25 * 10000),
  }
new_ad_group = ad_group_service.AddAdGroup(campaign_id, new_ad_group)[0]
ad_group_id = new_ad_group['id']

ad_groups = ad_group_service.GetAllAdGroups(campaign_id)
for ad_group in ad_groups:
  print('Ad group: %s' % ad_group['name'])

......

$newAdGroup = addAdGroup(
  "Sample Ad Group", // name
  $campaignId, // campaign id
  "Enabled", // status
  25 * 10000, // default keyword max cpc
  0 // site max cpm
);
$adGroupId = $newAdGroup->getId();

$adGroups = getAllAdGroups($campaignId);
foreach($adGroups as $adGroup) {
  $adGroupName = $adGroup->getName();
  print("Ad group: $adGroupName\n");
}

...

This code should print the name of your new ad group.

Ad group: Sample Ad Group

Creating an Ad

With a campaign and ad group in hand, you're ready to create ads themselves. A basic AdWords ad consists of an ad — the creative, i.e. what a user sees — and a keyword the search query or page content that triggers the ad. There are different types of ads. The most common is a text ad, which has a headline, two additional lines of text, and a link. An ad group can contain multiple ads and keywords. To create ads, you call addAds.

No language selected! Choose one above....

AdInterface adService = (AdInterface)adWordsUser.getService(AdWordsUser.AD_SERVICE);
TextAd newAd = new TextAd();
newAd.setAdGroupId(adGroupId);
newAd.setHeadline("Headline Goes Here!");
newAd.setDescription1("First line of description.");
newAd.setDescription2("Second line of description.");
newAd.setDestinationUrl("http://www.example.com/demo.html");
newAd.setDisplayUrl("www.example.com");
newAd.setStatus(AdStatus.Enabled);
Ad[] newAds = adService.addAds(new Ad[] { newAd });

Ad[] ads = adService.getAllAds(new int[] { adGroupId });
for(Ad ad : ads) {
  if(ad instanceof TextAd) {
    TextAd textAd = (TextAd)ad;
    System.out.println("Text ad: " + textAd.getHeadline());
  }
}

......

AdService adService = (AdService)adWordsUser.getService("AdService");
TextAd newAd = new TextAd();
newAd.adGroupId = adGroupId;
newAd.status = AdStatus.Enabled;
newAd.headline = "Headline Goes Here!";
newAd.description1 = "First line of description.";
newAd.description2 = "Second line of description.";
newAd.destinationUrl = "http://www.example.com/demo.html";
newAd.displayUrl = "www.example.com";
Ad[] newAds = adService.addAds(new Ad[] { newAd });

Ad[] ads = adService.getAllAds(new int[] { adGroupId });
foreach (Ad ad in ads) {
  if (ad is TextAd) {
    TextAd textAd = (TextAd)ad;
    Console.Out.WriteLine("Text ad: " + textAd.headline);
  }
}

......

ad_service = user.GetAdService('https://sandbox.google.com')
new_ad = {
  'adType': 'TextAd',
  'headline': 'Headline goes here!',
  'description1': 'First line of description',
  'description2': 'Second line of description',
  'adGroupId': ad_group_id,
  'status': 'Enabled',
  'displayUrl': 'www.example.com',
  'destinationUrl': 'http://www.example.com/demo.html',
}
new_ad = ad_service.AddAds([new_ad])

ads = ad_service.GetAllAds([ad_group_id])
for ad in ads:
  if ad['adType'] == 'TextAd':
    print('Text ad: %s' % ad['headline'])

......

$newAd = addTextAd(
  $adGroupId, // ad group id
  "Headline goes here!", // headline
  "First line of description.", // description line 1
  "Second line of description.", // description line 2
  "Enabled", // status
  "www.example.com", // display url
  "http://www.example.com/demo.html" // destination url
);
  
$ads = getAllAds(array($adGroupId));
foreach($ads as $ad) {
  if($ad->getAdType() == "TextAd") {
    $headline = $ad->getHeadline();
    print("Text ad: $headline\n");
  }
}

...

Running this code should output your text ad headline.

Text ad: Headline goes here!

Creating a Keyword

To create keywords, you call addCriteria.

No language selected! Choose one above....

CriterionInterface criterionService =
  (CriterionInterface)adWordsUser.getService(AdWordsUser.CRITERION_SERVICE);
Keyword newKeyword = new Keyword();
newKeyword.setAdGroupId(adGroupId);
newKeyword.setType(KeywordType.Broad);
newKeyword.setText("keywordtext");
Criterion[] newCriteria =
  criterionService.addCriteria(new Criterion[] { newKeyword });

Criterion[] criteria = criterionService.getAllCriteria(adGroupId);
for(Criterion criterion : criteria) {
  if(criterion instanceof Keyword) {
    Keyword keyword = (Keyword)criterion;
    System.out.println("Keyword: " + keyword.getText());
  }
}

......

CriterionService criterionService =
  (CriterionService)adWordsUser.getService("CriterionService");
Keyword newKeyword = new Keyword();
newKeyword.adGroupId = adGroupId;
newKeyword.type = KeywordType.Broad;
newKeyword.text = "keywordtext";
Criterion[] newCriteria =
  criterionService.addCriteria(new Criterion[] { newKeyword });

Criterion[] criteria = criterionService.getAllCriteria(adGroupId);
foreach (Criterion criterion in criteria) {
  if (criterion is Keyword) {
    Keyword keyword = (Keyword)criterion;
    Console.Out.WriteLine("Keyword: " + keyword.text);
  }
}

......

criterion_service = user.GetCriterionService('https://sandbox.google.com')
new_keyword = {
  'criterionType': 'Keyword',
  'text': 'keywordtext',
  'adGroupId': ad_group_id,
  'type': 'Broad',
  'negative': 'False',
}
new_keyword = criterion_service.AddCriteria([new_keyword])

criteria = criterion_service.GetAllCriteria(ad_group_id)
for criterion in criteria:
  if criterion['criterionType'] == 'Keyword':
    print('Keyword: %s' % criterion['text'])

......

$newKeyword = addKeywordCriterion(
  "keywordtext", // keyword text
  $adGroupId, // ad group id
  "Broad", // keyword type
  false, // is negative
  null, // keyword max cpc
  null, // language
  null // destination url
);

$criteria = getAllCriteria($adGroupId);
foreach($criteria as $criterion) {
  if($criterion->getCriterionType() == "Keyword") {
    $keywordText = $criterion->getText();
    print("Keyword: $keywordText\n");
  }
}

...

Running this code should output your keyword text.

Keyword: keywordtext

Further Topics

This tutorial just scratches the surface of what's available in the AdWords API. The Developer Guide contains full documentation for the API's various services and methods and the campanion sample code can serve as a jumping off point for building a larger application on top of the API.

More advanced AdWords API functionality includes:

Creating detailed account performance and structure reports with the Report Service.
Using the Keyword Tool Service to automatically generate suggested keywords given a seed keyword or text on a website.
Estimating the amount of traffic and expected cost per click of keywords before adding them to your ad groups with the Traffic Estimator Service.
Generating lists of potential sites for placement-targeted campaigns with the Site Suggestion Service.
Tracking your API usage, including usage for client accounts within an MCC, using the Info Service.

AdWords API Tutorial