Google AdWords API – Part 2

Part two is about how to get data from Google AdWords.

Structure

An AdWords account is hierarchically structured:

• AdWords account
  An AdWords account is unique with its AdWords ID and is a Google account.
  
• Campaign
  The main thing here. A campaign defines everything to advertise from something. It can be active, inactive or paused. Campaigns costs money and they generate clicks by getting people to your site.
• Adgroup
  A campaign is structured by adgroups. These are grouped advertising goods. An adgroup belongs to a campaign and has different ads, keywords and placements.
• Ads (AdText)
  This are textual ads by Google. One ad consists of an headline and two textrows. You can find such ads on the right side of your Google search results.
• Keyword
  A keyword is a search value that is put into Googles search field to find a site. You can pay money, that you site can be found/higher ranked with certain keywords.
• Placement
  This is a graphical ad. It is also called image ad and can be found on websites that use Google AdSense.

Campaigns

Our first goal is to get all campaigns from an AdWords account. For this we have created a AdWords user object that is needed for each individual AdWords account.

You can get campaigns with the CampaignService. For this I used the sample code from the client library and modified it to fits my needs. This function returns an array with campaigns:

function GetCampaigns(AdWordsUser $user, $adwords_version) {

    // Get the service, which loads the required classes.
    $campaignService = $user->GetService('CampaignService', $adwords_version);

    // Create selector.
    $selector = new Selector();
    $selector->fields = array('Id', 'Name', 'Status');
    $selector->ordering[] = new OrderBy('Name', 'ASCENDING');

    // Filter out deleted criteria.
    $selector->predicates[] = new Predicate('Status', 'NOT_IN', array('DELETED', 'PAUSED'));

    // Create paging controls.
    $selector->paging = new Paging(0, AdWordsConstants::RECOMMENDED_PAGE_SIZE);

    $ret = array();
    do {
        // Make the get request.
        $page = $campaignService->get($selector);

        // Display results.
        if (isset($page->entries)) {
            foreach ($page->entries as $campaign) {
                //printf("Campaign with name '%s' and id '%s' was found with Status: '%s'\n",
                // $campaign->name, $campaign->id, $campaign->status);
                $ret[] = array(
                    'name' => $campaign->name,
                    'id' => $campaign->id,
                    'active' => (strcmp($campaign->status,'ACTIVE')==0)?1:0
                );
            }
        } else {
            //print " No campaigns were found.\n";
        }
        // Advance the paging index.
        $selector->paging->startIndex += AdWordsConstants::RECOMMENDED_PAGE_SIZE;
    } while ($page->totalNumEntries > $selector->paging->startIndex);
    return $ret;
}

This function uses the user object defined in part 1 of my article series. Another param is the AdWords Version. The current version is ‚v201209‘.

With the user object we can get the CampaignService. With it we can define and limit our query:

• Selector
  With a selector we can define which columns need to be returned from the API. A list of all columns per service can be found here. With a selector we can also define which columns are used for sorting.
  
• Predicate
  With a predicate object we can limit our query result. For this example we only want campaigns that are active. So we do not want deleted or paused campaigns.
• Paging
  With the paging object we can get and step through the search result. We run through a loop and store everything we need into an array and return it.

Adgroups

You can get adgroups with the AdGroupService. This is similar to the CampaignService:

function GetAdGroup(AdWordsUser $user, $adwords_version) {
    // Get the service, which loads the required classes.
    $adgroupService = $user->GetService('AdGroupService', $adwords_version);

    // Create selector.
    $selector = new Selector();
    $selector->fields = array('Id', 'Name', 'CampaignId', 'Status');
    $selector->ordering[] = new OrderBy('CampaignId', 'ASCENDING');

    // Filter out deleted criteria.
    $selector->predicates[] = new Predicate('Status', 'NOT_IN', array('DELETED', 'PAUSED'));

    // Create paging controls.
    $selector->paging = new Paging(0, AdWordsConstants::RECOMMENDED_PAGE_SIZE);

    $ret = array();
    do {
        // Make the get request.
        $page = $adgroupService->get($selector);

        // Display results.
        if (isset($page->entries)) {
            foreach ($page->entries as $adgroup) {
                //printf("AdGroup with name '%s' and id '%s' was found for Campaign: '%s' and Status: '%s'\n",
                // $adgroup->name, $adgroup->id, $adgroup->campaignId, $adgroup->status);
                $ret[] = array(
                    'name' => $adgroup->name,
                    'id' => $adgroup->id,
                    'campaignId' => $adgroup->campaignId,
                    'active' => (strcmp($adgroup->status,'ENABLED')==0)?1:0
                );
            }
        } else {
            //print "No adgroups were found.\n";
        }
        // Advance the paging index.
        $selector->paging->startIndex += AdWordsConstants::RECOMMENDED_PAGE_SIZE;
    } while ($page->totalNumEntries > $selector->paging->startIndex);
    return $ret;
}

The next article is about keywords, adtexts and placements.

Part 1 | Part 3 | Part 4 | Part 5 | Part 6