Working with the Google AdWords API
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 IPWorks 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 IPWorks SOAP component is natively available for all major component technologies including the .NET, ASP, Delphi, C++ Builder, Windows C++, Java, J2EE, and C/C++ for Unix / Linux / Mac OS X. As the interfaces of the IPWorks components are virtually identical across platform and technology, the code in this article can be easily ported to any supported environment.
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 IPWorks 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>IPWorks SOAP Component</useragent>" & _ "<token>" & DeveloperToken & "</token>" End Function
Working with Campaigns
Using the IPWorks 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//" For i = 1 To SOAP1.XChildren SOAP1.XPath = "/Envelope/Body/getCampaignResponse//[" & 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
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//" For i = 1 To SOAP1.XChildren SOAP1.XPath = "/Envelope/Body/addCampaignResponse//[" & 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 IPWorks SOAP component and the Google AdWords API for managing your AdWords accounts. IPWorks 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 firstname.lastname@example.org.