Section 16.4. Returning the Keyword Estimate

16.4. Returning the Keyword Estimate

The information returned from a keyword estimate can be pretty valuable for making decisions about whether you want to target a keyword or whether you want to raise your bid for the keyword. All the example in this chapter does is display the raw data, but it's easy to see how this data could be used to provide intelligence for a business application that divides resources among different keywords.

Using the other estimation capabilities of the KeywordEstimatorService, similar kinds of decisions about campaigns and AdGroups could also be automated.

If you want to do something with the information that the response to a keyword estimate request provides, you need to follow a number of steps to retrieve the data. These steps are not that complex, although it is a bit tricky to construct XML-wrapped keyword requests and request messages that don't cause the NuSOAP library to generate a SOAP error.

The proxy class generated by Visual Studio.NET or the Axis SOAP library for Java makes programming the KeywordEstimatorService and the other AdWords API web services much simpler than in PHP.

To return a keyword estimate:

1. Connect to the WSDL file for the Google API web service.

2. Instantiate a client web service object.

3. Use the header information to authenticate the web service object.

4. Construct a keyword request.

5. Use one or more keyword requests to construct a request message.

6. Send the request message to the web service object.

7. Display the estimate information using the service's response (the Keyword-Estimate).

16.4.1. Creating a Service Object

You can use the NuSoap soapclient class to create a new client service object by supplying the WSDL file for the web service. Once you have instantiated the client object, you can authenticate it and then send it messages and use the responses.

Here's the code for creating a new client object based on the WSDL file:

     $wsdl =        "https://adwords.google.com/api/adwords/v2/TrafficEstimatorService?wsdl";        $client = new soapclient($wsdl, 'wsdl');

16.4.2. Using the Header Information for Authentication

Authentication works the same way for all of the AdWords API web services, but it must be done each time a new client based on one of the services is created.

The header information consists of the email address for an AdWords account, the password for the account, an arbitrary UserAgent string, and a developer key. In this example, the user has supplied all this information.

The $header variable stores the authentication information supplied by the user, wrapped in XML, and concatenated together. The $header variable is used to authenticate the service:

     $client->setHeaders($header);

You should check to see that this worked by checking for SOAP errors:

     if($client->fault) {        showErrors($client);        echo '<a href="estimate_keyword.php">Try again</a>';     }     else{        // construct the keyword request       ...

If there are no SOAP faults displayed, the program can move on and construct the keyword request.

16.4.3. Constructing the Keyword Request

To construct the keyword request, the fields of the request need to be wrapped in XML to meet the requirements of the NuSOAP library and document literal SOAP (see Chapter 14 for details):

     $keyword = makeDocLit ("text", $keyword);     $maxCpc = makeDocLit ("maxCpc", $maxCpc);

In addition, information that in this case was not requested of the user (the type of match) needs to be added:

     $otherinfo = $maxCpc . "<type>Broad</type>";     $keywordRequest = $keyword . $otherinfo;

Then the entire request is, itself, wrapped in XML:

     $keywordxml = makeDocLit ("KeywordRequest", $keywordRequest);

16.4.4. Send a Request Message

To send the request message, wrap the keyword requests (in this case, there is only one keyword request) in XML as an estimateKeywordList object:

     $param = makeDocLit ("estimateKeywordList", $keywordxml);

Call the web service client estimateKeywordList method:

     $response = $client->call("estimateKeywordList", $param);

The response will contain the estimate information:

     $response = $response['estimateKeywordListReturn'];

16.4.5. Displaying Information Using the Keyword Estimate

Before attempting to display the estimate information, check to see if there were any SOAP faults:

     if($client->fault) {        showErrors($client);        echo '<a href="estimate_keyword.php">Try again</a>';     }     else{        // display estimate information       ...

If there are no errors, go ahead and display the results element fields:

     echo "<h2>Here is your keyword estimate:</h2>";     echo "<h3>" . $keyword . "</h3>";     printResults($response);     ...     function printResults ($estimate) {        echo "\n<br>cpc = " . $estimate['cpc'] . " in micro-units";        echo "\n<br>clicks = " . $estimate['ctr'] * $estimate['impressions'];        echo "\n<br>ctr = " . ($estimate['ctr'] * 100) . "%";        echo "\n<br>impressions = " . $estimate['impressions'];        echo "\n<br>notShown = " . $estimate['notShownPerDay'];        echo "\n<br>position = " . $estimate['avgPosition'];     }

When this code is run, depending on the keyword entered, the display will look like that shown in Figure 16-4.

Figure 16-4. Keyword estimation statistics, simply displayed here, can be used as part of an automated keyword selection process

If you enter a keyword for estimation that doesn't generate much traffic, the estimate won't have as much statistical validity as for a higher traffic keywords, and fields such as clicks and impressions may show zero as their value.

Example 16-3 shows the library functions that add XML to a variable, required by the NuSOAP library and document literal SOAP, and the function that displays errors (see Chapter 14 for a detailed explanation).

Example 16-3. Adding XML and Displaying Errors (hd_lib.inc)

 <?php function makeDocLit($xml, $var) {     return '<' . $xml . '>' . $var . '</' . $xml . '>'; } function showErrors($client) {     echo "FAULT:  {$client->fault}<br>\n";     echo "Code: {$client->faultcode}<br>\n";     echo "String: {$client->faultstring}<br>\n";     echo "Detail: {$client->faultdetail}<br>\n"; } ?>

Example 16-4 shows the code required to construct the request object and request message, and then to display the fields of the request response.

Example 16-4. Constructing the Request and Displaying the Response (show_estimate.php)

 <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Show Keyword Estimate</title> </head> <body> <?php require_once('NuSOAP/nusoap.php'); require_once('hd_lib.inc'); echo "<h1>Show Keyword Estimate</h1>"; $keyword = $_POST['keyword']; $maxCpc = $_POST['maxCpc']; if ($keyword == null){    echo 'You must enter a keyword to estimate it! <br>    <a href="estimate_keyword.php">Try again</a>'; } else {    // Connect to the WSDL for the TrafficEstimatorService    $wsdl =       "https://adwords.google.com/api/adwords/v2/TrafficEstimatorService?wsdl";    $client = new soapclient($wsdl, 'wsdl');      // Set the headers for the client    $client->setHeaders($header);      // Handle any SOAP errors    if($client->fault) {       showErrors($client);       echo '<a href="estimate_keyword.php">Try again</a>';    }    else{       $keyword = makeDocLit ("text", $keyword);       $maxCpc = makeDocLit ("maxCpc", $maxCpc);       $otherinfo = $maxCpc . "<type>Broad</type>";       $keywordRequest = $keyword . $otherinfo;       $keywordxml = makeDocLit ("KeywordRequest", $keywordRequest);       $param = makeDocLit ("estimateKeywordList", $keywordxml);       // Make the request to estimate the keyword       $response = $client->call("estimateKeywordList", $param);       $response = $response['estimateKeywordListReturn'];       if($client->fault) {          showErrors($client);          echo '<a href="estimate_keyword.php">Try again</a>';       }       else{          echo "<h2>Here is your keyword estimate:</h2>";          echo "<h3>" . $keyword . "</h3>";          printResults($response);       }    } } function printResults ($estimate) {    echo "\n<br>cpc = " . $estimate['cpc'] . " in micro-units";    echo "\n<br>clicks = " . $estimate['ctr'] * $estimate['impressions'];    echo "\n<br>ctr = " . ($estimate['ctr'] * 100) . "%";    echo "\n<br>impressions = " . $estimate['impressions'];    echo "\n<br>notShown = " . $estimate['notShownPerDay'];    echo "\n<br>position = " . $estimate['avgPosition']; } ?> </body> </html>