Section 16.2. Keyword Requests and Estimates

16.2. Keyword Requests and Estimates

The Keyword request, message, and response are probably the most useful of the KeywordEstimatorService methods; it is much more common to change a keyword than an ad or an entire campaign based on performance estimates.

To make a keyword request, the required information about the keyword must be put together in the right format. Then one or more keywords are assembled into a request message. The fields of the response to the message contain the estimate information.

16.2.1. The Request Object

A KeywordRequest object represents a keyword to be estimated. The six fields of the KeywordRequest object are shown in Table 16-2.

Table 16-2. You use a KeywordRequest object to specify the details of the keyword you want to estimate

Field	Type	Comments
id	Long integer	If the id is omitted, then a new keyword is being estimated.
maxCpc	Long integer	Value in micros of the maximum you are willing to pay for a click; required field unless the id refers to an existing keyword. The minimum bid is 50,000 micros ($.05 in U.S. dollars). Entering a maxCPC of less than 50,000 throws an error.
negative	Boolean	Optional. If this field is True (the default is False), then a negative match is indicated.
text	String	The text of a keyword or phrase; can be omitted if the request concerns an existing keyword and its id was supplied.
type	KeywordType (enumeration)	Match type. The possible values of this enumeration are Broad, Phrase, and Exact. Required unless the request refers to an existing keyword by id.

For more information about micros as a unit of currency, see Chapter 14. Match types are explained in Chapter 11.

16.2.2. The Response Object

A KeywordEstimate contains the actual estimate information that is returned once a request message that contains one or more KeywordRequest objects has been sent. The fields of a KeywordEstimate are shown in Table 16-3.

Table 16-3. The details of the results of a keyword traffic estimation are shown in the fields of a KeywordEstimate object

Field	Type	Comments
avgPosition	Float	Estimated average position for an ad that targets this keyword
cpc	Long integer	Estimated cost per click (CPC) in micros of an ad targeting this keyword
ctr	Float	Estimated click-through rate (CTR)
id	Integer	ID of a keyword contained in an existing AdGroup; -1 if the keyword is new
impressions	Integer	Estimated number of impressions for an ad targeted to this keyword
notShownPerDay	Integer	Estimated number of times an ad targeted to this keyword will not be shown despite a keyword match

If you raise the maxCpc input in an estimate request and keep everything else the same, the notShownPerDay will go down in the response, because the more you are willing to pay, everything else being equal, the more your ad will be shown.