/n software inc. - Working with the Google AdWords API

How To - Manage Adwords with Google AdWords API and IP*Works! SSL

By Lance Robinson - Technical Evangelist, /n software.
Eric Madariaga, /n software.

Requirements: IP*Works! SSL
Download Demo: Download

Managing Google AdWords Campaigns

Google has recently released the initial Beta of the Google AdWords API. The API is designed to allow programmatic access to managing Google AdWords accounts and includes features such as campaign management, keyword / traffic estimation, and campaign reporting features. Currently this API is offered as a secure web service over SOAP. In order to access the soap service you must be a current Google AdWords advertiser and sign up for a free My Client Center account which will provide you with a developer token that you will use in your SOAP requests.

This How-To article will cover how to use the IP*Works! SSL SOAPS component to connect to the AdWords webservice and manage your AdWords campaign services. In a later article I will demonstrate how to work with the keyword / traffic estimates, ad management, reporting, and more. For complete documentation of the AdWords API go to http://www.google.com/apis/adwords/developer/adwords_api_classref.html.

The code that in this How-To will be written in Microsoft Visual Basic (VB6) for simplicity and readability. However, the IP*Works SSL SOAP component is natively available for all major component technologies including the .NET / .NET CF, ASP, Delphi, C++ Builder, Windows C++, Java, J2EE, and C/C++ for Unix / Linux / Mac OS X. As the interfaces of the IP*Works! SSL components are virtually identical across platform and technology, the code in this article can be easily ported to any supported environment.

Getting Started

The first thing to do when getting started is to sign up for a My Client Center account, link your AdWords campaigns to that account, and receive your developer token. To accomplish this, follow the instructions outlined on the AdWords API Beta site .

Your developer token, as well as your My Client Center and account information will be used in your SOAP requests, so make sure the store this information.

For convenience and readability I will define a global IP*Works! SSL SOAPS object named SOAP1 . In Visual Basic this is done by simply dragging the SOAPS component onto your current application form.

Building the SOAP Header

As I mentioned previously I have already defined a global secure SOAP object SOAP1 that will be used to make SOAP requests.

The Google AdWords API requires specific information in the SOAP envelope header in order to authenticate requests. This includes your My Client Center email address and corresponding password, the account email address of the campaign you wish to manage, useragent, and your developer token. This information needs to be included in the SOAP header before making any campaign requests to the service.

I have wrapped this information, as well as the SOAP URL and the Method URI in a small function that will be called before making any campaign function calls.

Function BuildSOAPHeader()
  SOAP1.Reset
  SOAP1.MethodURI = "https://AdWords.google.com/api/AdWords/v2"
  SOAP1.ActionURI = ""
  SOAP1.URL = "https://AdWords.google.com/api/AdWords/v2/CampaignService"
  SOAP1.SOAPHeader = "<email>" & MyClientCenterEmail & "</email>" & _
                     "<clientEmail>" & AccountEmail & "</clientEmail>" & _
                     "<password>" & Password & "</password>" & _
                     "<useragent>IP*Works! SSL SOAP Component</useragent>" & _
                     "<token>" & DeveloperToken & "</token>"
End Function

Working with Campaigns

Using the IP*Works! SSL SOAP component with the AdWords API is a straightforward process. The first thing that you will typically want to do is list all of the AdWords campaigns in order to get the campaign id. The campaign id is used for accessing and modifying current campaigns.

In the code below there is dummy parameter included with the request. At least 1 parameter is required by Google for accessing campaign services, however as they really require no additional information for listing campaign information, a junk parameter has been used.

MsgBox getAllAdWordsCampaigns() 'List all campaigns
 
'Return all information about all Campaigns belonging 
'to the customer issuing the request. 
Function getAllAdWordsCampaigns() As String
  BuildSOAPHeader
    
  SOAP1.Method = "getAllAdWordsCampaigns"
  SOAP1.AddParam "dummy", "1"
  SOAP1.SendRequest

  Dim retstr As String
  SOAP1.XPath = "/Envelope/Body/getAllAdWordsCampaignsResponse/"
  For i = 1 To SOAP1.XChildren
    SOAP1.XPath = "/Envelope/Body/getAllAdWordsCampaignsResponse/[" & i & "]/"
    For j = 1 To SOAP1.XChildren
      SOAP1.XPath = "/Envelope/Body/getAllAdWordsCampaignsResponse/[" & _
                    i & "]/[" & j & "]"
      retstr = retstr + SOAP1.XElement + " = " + SOAP1.XText + vbCrLf
    Next j
  Next i
  getAllAdWordsCampaigns = retstr
End Function

All of the important information is returned as a delimited string. If I were building a real application it would probably be easiest to instead return a hashtable of name-value pairs. Here is a sample output of what is returned:

 id = 413393
 name = Test
 status = Deleted
 startDate = 2002-09-09T14:39:23.000Z
 endDate = 2005-01-11T14:58:05.000Z
 dailyBudget = 20000000
 optInSearchNetwork = true
 optInContentNetwork = true
 languageTargeting = 
 geoTargeting = 

 ...

Calling getAllAdWordsCampaigns() will return this information for each of the campaigns available. As you can see, there are a number of important properties that are returned from this call. I won't go into detail about all of the returned values as you can read the Google documentation for more detailed API information, however the most important thing to retrieve from these values is the campaign id. The campaign id is a unique identifier used as a parameter for most campaign transactions.

The other important thing to notice is that all dollar amounts are actually returned in micro units of currency, where $.05 = 50000 micros (minimum cpc bid for ad group)

In order to retrieve information about specific campaigns in the future (once I know the campaign id), I can do the following:

MsgBox getCampaign ("413393") ' Information about a single campaign 

'Getting Information about a single campaign - can be called with 
'a single id, and will return a string of campaign info.
Function getCampaign(id As String) As String
  BuildSOAPHeader
    
  SOAP1.AddParam "id", id
  SOAP1.Method = "getCampaign"
  SOAP1.SendRequest
    
  Dim retstr As String
  SOAP1.XPath = "/Envelope/Body/getCampaignResponse/[1]/"
  For i = 1 To SOAP1.XChildren
    SOAP1.XPath = "/Envelope/Body/getCampaignResponse/[1]/[" & i & "]"
    retstr = retstr + SOAP1.XElement + " = " + SOAP1.XText + vbCrLf
  Next i
  getCampaign = retstr
End Function

----------




MsgBox getCampaignList ("413393 311394") ' Info about a multiple campaigns

'Getting Information about multiple campaigns - can be called with 
'a space delimited list of ids, and will return a string of campaign info.
Function getCampaignList(ids As String) As String
  BuildSOAPHeader
    
  SOAP1.Method = "getCampaignList"
  id = Split(ids, " ")
  For i = LBound(id) To UBound(id)
    SOAP1.AddParam "ids", id(i)
  Next i
  SOAP1.SendRequest
    
  Dim retstr As String
  SOAP1.XPath = "/Envelope/Body/getCampaignListResponse/"
  For i = 1 To SOAP1.XChildren
    SOAP1.XPath = "/Envelope/Body/getCampaignListResponse/[" & i & "]/"
    For j = 1 To SOAP1.XChildren
      SOAP1.XPath = "/Envelope/Body/getCampaignListResponse/[" & _
                    i & "]/[" & j & "]"
      retstr = retstr + SOAP1.XElement + " = " + SOAP1.XText + vbCrLf
    Next j
  Next i
  getCampaignList = retstr
End Function

Adding Campaigns

In addition to working with current campaigns, the AdWords API offers the ability to add new campaigns to an account as well. Adding a campaign requires specifying it's name and daily budget. In addition to specifying these properties I'm going to set the status of this campaign to paused as well.

'Add a new AdWords campaign to the account
'1000000 = $1/day
MsgBox addCampaign("<dailyBudget>1000000</dailyBudget>" & _
                   "<name>APITestAdd</name><status>Paused</status>")

Function addCampaign(campaign As String) As String
  BuildSOAPHeader
  
  SOAP1.Method = "addCampaign"
  SOAP1.ValueFormat = vfXML
  SOAP1.AddParam "campaign", campaign
  SOAP1.BuildPacket
  SOAP1.SendRequest
  
  Dim retstr As String
  SOAP1.XPath = "/Envelope/Body/addCampaignResponse/[1]/"
  For i = 1 To SOAP1.XChildren
    SOAP1.XPath = "/Envelope/Body/addCampaignResponse/[1]/[" & i & "]"
    retstr = retstr + SOAP1.XElement + " = " + SOAP1.XText + vbCrLf
  Next i
  addCampaign = retstr
End Function

One thing to note about sending XML as a parameter is that I have to set the SOAP objects ValueFormat to XML. If the ValueFormat is not set to XML then the XML contained in all SOAP parameters gets escaped and I send an invalid request.

Calling addCampaign() will set and return a new campaign id that can me used to update the campaign.

I have the Campaign ID, now what?

Now that I have a campaign id for the specific campaign that I want to edit, I have a number of options:

'Update campaign information
MsgBox updateCampaign("<id>5542491</id><dailyBudget>1000000</dailyBudget>" & _
                      "<status>Deleted</status>")

Function updateCampaign(campaign As String) As String
  BuildSOAPHeader
  
  SOAP1.Method = "updateCampaign"
  SOAP1.ValueFormat = vfXML
  SOAP1.AddParam "campaign", campaign
  SOAP1.BuildPacket
  SOAP1.SendRequest
  updateCampaign = "Updated."
End Function

----------

MsgBox getOptimizeAdServing("5542371") 'Get optimized add settings

Function getOptimizeAdServing(id As String) As String
  BuildSOAPHeader
  
  SOAP1.Method = "getOptimizeAdServing"
  SOAP1.AddParam "id", id
  SOAP1.SendRequest
  
  Dim retstr As String
  SOAP1.XPath = "/Envelope/Body/getOptimizeAdServingResponse/"
  For i = 1 To SOAP1.XChildren
    SOAP1.XPath = "/Envelope/Body/getOptimizeAdServingResponse/[" & i & "]"
    retstr = retstr + SOAP1.XElement + " = " + SOAP1.XText + vbCrLf
  Next i
  getOptimizeAdServing = retstr
End Function

----------

MsgBox setOptimizeAdServing("", False) 'Set optimized add settings

Function setOptimizeAdServing(id As String, enable As Boolean) As String
  BuildSOAPHeader
  
  SOAP1.Method = "setOptimizeAdServing"
  SOAP1.AddParam "id", id
  SOAP1.AddParam "enable", CStr(enable)
  SOAP1.SendRequest
  SOAP1.XPath = "/Envelope/Body/setOptimizeAdServingResponse/"
  setOptimizeAdServing = "Set to " + CStr(enable)
End Function

----------

'Get current campaign statistics
MsgBox getCampaignStats("413393", "2005-01-31T00:00:00Z", _
                         "2005-02-01T00:00:00Z")

Function getCampaignStats(id As String, starttime As String, _
                          endtime As String) As String
  BuildSOAPHeader
  
  SOAP1.Method = "getCampaignStats"
  SOAP1.AddParam "id", id
  SOAP1.AddParam "start", starttime
  SOAP1.AddParam "end", endtime
  SOAP1.SendRequest
  
  Dim retstr As String
  SOAP1.XPath = "/Envelope/Body/getCampaignStatsResponse/getCampaignStatsReturn/"
  For i = 1 To SOAP1.XChildren
    SOAP1.XPath = 
      "/Envelope/Body/getCampaignStatsResponse/getCampaignStatsReturn/[" & i & "]"
    retstr = retstr + SOAP1.XElement + " = " + SOAP1.XText + vbCrLf
  Next i
  getCampaignStats = retstr
End Function

Tip of the Iceberg

In addition to the basic campaign management features available through the Google AdWords API, Google has exposed most, if not all, of the features that you will find through their web interface. Using the API you can programmatically access all of the great features of AdWords including the keyword / traffic tool and the reporting services. I am very excited that Google has decided to produce an API for their customers and I look forward to seeing some exciting application integrations in the near future.

Hopefully this How-To article has demonstrated to you how easy it is to use the IP*Works! SSL SOAP component and the Google AdWords API for managing your AdWords accounts. IP*Works! SSL makes secure communication easy, regardless of platform, development technology, or communications protocol.

Thanks for reading! If you'd like to see the full demo showing how to integrate AdWords campaign management into your VB applications you can download the full demo here.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.