Google AdWords API – Part 3

The third article is about how to get adtexts, placements and keywords from Google AdWords API.

Adtext

You can get adtexts from the AdGroupAdService. The difference to campaigns and adgroups is, that we can get now actual data that is used by AdWords. This data is displayed at the Google AdWords user interface from Google:

• Klicks
• Impressionen
• CPC (Cost per Click)
• Conversions
• CTR (Click trough rate)
• Position
• …

The whole list can be found here.

You can get the values the following way:

function GetTextAds(AdWordsUser $user, $adGroupId, $days, $adwords_version) {
    // Get the service, which loads the required classes.
    $adGroupAdService = $user->GetService('AdGroupAdService', $adwords_version);

    // Create selector.
    $selector = new Selector();
    $selector->fields = array('Headline', 'Id', 'Description1', 'Description2', 'DisplayUrl', 'Url', 'Status', 'AverageCpc', 'AveragePosition', 'Clicks', 'Conversions', 'Cost', 'Ctr', 'Impressions');
    $selector->ordering[] = new OrderBy('Headline', 'ASCENDING');

    // Create predicates.
    $selector->predicates[] = new Predicate('AdGroupId', 'IN', array($adGroupId));
    $selector->predicates[] = new Predicate('AdType', 'IN', array('TEXT_AD'));
    // By default disabled ads aren't returned by the selector. To return them
    // include the DISABLED status in a predicate.
    $selector->predicates[] = new Predicate('Status', 'NOT_IN', array('DISABLED', 'PAUSED'));
    $selector->predicates[] = new Predicate('Impressions', 'GREATER_THAN', array('1'));
    $dateRange = new DateRange();
    $str1 = '-1 days';
    $str2 = '-1 days';
    if($days > 0)
    {
        $str1 = '-'.$days.' days';
        $str2 = '-'.$days.' days';
    }
    $dateRange->min = date('Ymd', strtotime($str1));
    $dateRange->max = date('Ymd', strtotime($str2));
    $selector->dateRange = $dateRange;

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

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

        // Display results.
        if (isset($page->entries)) {
            foreach ($page->entries as $adGroupAd) {
                $cr = 0;
                if($adGroupAd->stats->clicks > 0)
                    $cr = $adGroupAd->stats->conversions / $adGroupAd->stats->clicks;

                $ret[] = array(
                    'headline' => $adGroupAd->ad->headline,
                    'id' => $adGroupAd->ad->id,
                    'textrow1' => $adGroupAd->ad->description1,
                    'textrow2' => $adGroupAd->ad->description2,
                    'view_url' => $adGroupAd->ad->displayUrl,
                    'target_url' => $adGroupAd->ad->url,
                    'active' => (strcmp($adGroupAd->status,'ENABLED')==0)?1:0,
                    'clicks' => $adGroupAd->stats->clicks,
                    'cpc' => $adGroupAd->stats->averageCpc->microAmount / 1000000,
                    'conversions' => $adGroupAd->stats->conversions,
                    'cost' => $adGroupAd->stats->cost->microAmount / 1000000,
                    'ctr' => $adGroupAd->stats->ctr,
                    'impressions' => $adGroupAd->stats->impressions,
                    'cr' => $cr,
                    'position' => $adGroupAd->stats->averagePosition
                );
                }
            } else {
                //print "No text ads were found.\n";
            }

            // Advance the paging index.
            $selector->paging->startIndex += AdWordsConstants::RECOMMENDED_PAGE_SIZE;
        } while ($page->totalNumEntries > $selector->paging->startIndex);
    return $ret;
}

At the selector I also use a dateRange. So for this example, I only get daily values (I only want data from one day). For this you can also define date ranges like a week or so. If you do, you will get summed values.

An adtext is defined by:

• Headline
  A headline for the text ad.
  
• Description1
  The first row of text.
• Description2
  The second row of text.
• DisplayUrl
  The URL which is displayed to the user.
• Url
  A URL which is used. Can be different than the URL that is displayed.

Keywords/Placements

You can get keywords and playemenct with the same Service (AdGroupCriterionService). It is very similar to the adtext code:

function GetKeywords(AdWordsUser $user, $adGroupId, $days, $adwords_version) {
    // Get the service, which loads the required classes.
    $adGroupCriterionService =
    $user->GetService('AdGroupCriterionService', $adwords_version);

    // Create selector.
    $selector = new Selector();

    $selector->fields = array('KeywordText', 'KeywordMatchType', 'Id', 'AverageCpc', 'AveragePosition', 'Clicks', 'Conversions', 'Cost', 'Ctr', 'Impressions', 'QualityScore', 'Status');
    $selector->ordering[] = new OrderBy('KeywordText', 'ASCENDING');

    // Create predicates.
    $selector->predicates[] = new Predicate('AdGroupId', 'IN', array($adGroupId));
    $selector->predicates[] = new Predicate('CriteriaType', 'IN', array('KEYWORD'));
    $selector->predicates[] = new Predicate('Status', 'IN', array('ACTIVE'));
    $selector->predicates[] = new Predicate('Impressions', 'GREATER_THAN', array('1'));

    $dateRange = new DateRange();
    $str1 = '-1 days';
    $str2 = '-1 days';
    if($days > 0)
    {
        $str1 = '-'.$days.' days';
        $str2 = '-'.$days.' days';
    }
    $dateRange->min = date('Ymd', strtotime($str1));
    $dateRange->max = date('Ymd', strtotime($str2));
    $selector->dateRange = $dateRange;

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

    $ret = array();

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

        // Display results.
        if (isset($page->entries)) {
            foreach ($page->entries as $adGroupCriterion) {
                $cr = 0;
                if($adGroupCriterion->stats->clicks > 0)
                    $cr = $adGroupCriterion->stats->conversions / $adGroupCriterion->stats->clicks;

                $ret[] = array(
                    'name' => $adGroupCriterion->criterion->text,
                    'type' => $adGroupCriterion->criterion->matchType,
                    'id' => $adGroupCriterion->criterion->id,
                    'clicks' => $adGroupCriterion->stats->clicks,
                    'cpc' => $adGroupCriterion->stats->averageCpc->microAmount / 1000000,
                    'conversions' => $adGroupCriterion->stats->conversions,
                    'cost' => $adGroupCriterion->stats->cost->microAmount / 1000000,
                    'ctr' => $adGroupCriterion->stats->ctr,
                    'impressions' => $adGroupCriterion->stats->impressions,
                    'qualityfactor' => $adGroupCriterion->qualityInfo->qualityScore,
                    'cr' => $cr,
                    'position' => $adGroupCriterion->stats->averagePosition
                );
                }
            } else {
                //print "No keywords were found.\n";
            }

            // Advance the paging index.
            $selector->paging->startIndex += AdWordsConstants::RECOMMENDED_PAGE_SIZE;
        } while ($page->totalNumEntries > $selector->paging->startIndex);
    return $ret;
}

For placements you can additionally get name and url of it.

Thats all. You can get all data from Google. I use this method to get daily values and store it into database. There I can compute weekly and monthly values. If you want to see campaign or adgroup values, you have to sum up keywords and placements or adtexts.

Part 1 | Part 2 | Part 4 | Part 5 | Part 6