API Reference
The Reference provides descriptions of:
- services
The reference pages for the services list the requests that the service handles. Requests take input parameters and return a response. Both the input parameters and the response might be a simple type (such as a long) or a data object, such as a Campaign.
- data objects
The reference pages for the data objects list the fields on the object.
How you construct request and input parameters depends on the toolkit and language you are using, or whether you are coding directly in XML.
When reading the reference pages, you will need to map the objects and fields to your own particular situation. For example, consider the estimateKeywordList request on the TrafficEstimatorService, which is documented as follows:
estimateKeywordList
Returns traffic estimates for the requested set of new keywords.
All of the keywords must be new. New keywords are estimated as if they were part of a single new ad group in a single new campaign with global targeting.
Parameters
| Parameter name |
Parameter type |
Parameter description |
| keywordRequests |
KeywordRequest[] |
The set of keywords to estimate. |
Response
KeywordEstimate[]
The traffic estimates for the requested keywords.
NOTE: Brackets([]) indicate that a type is unbounded. For example: KeywordRequest[].
If you are coding in Java using the Axis toolkit, you instantiate data objects (such as KeywordRequest), use setter methods to set values on the object, and send the request to a proxy for the web service.
The following Java fragment shows how to construct the input parameters for the estimateKeywordList request. (This fragment does not include setting the header elements of the request.)
// Set the attributes of the keywords to be estimated
KeywordRequest myKeyword = new KeywordRequest();
myKeyword.setText(keywordtest);
Long fiveCents = new Long("50000");
myKeyword.setMaxCpc(fiveCents);
myKeyword.setType(KeywordType.Broad);
// Make an array of the keywordrequests
KeywordRequest[] myKeywordList = {myKeyword};
// Send the request to the TrafficEstimator service
KeywordEstimate[] estimates =
adwordsService.estimateKeywordList(myKeywordList);
When using a SOAP toolkit for a dynamically typed language, such as Perl, you typically construct a data structure for the input parameters. For example:
# Construct the keyword request
my $param = {
"type" => "Broad",
"text" => "flowers",
"maxCpc" => 50000,
};
# Call the service method.
# @headers was defined previously
my $estimate = $service->estimateKeywordList($param, @headers);
In this case, the keywordRequest input parameter is an untyped data structure. With dynamically typed languages such as Perl, you typically do not need to specify the type of input parameters unless you are creating a report job.
Note: When creating a report job as an input parameter to the scheduleReport request on ReportService, you must specify the type of report. See the sample code for examples.
If you are constructing SOAP messages directly in XML, you would specify the estimateKeywordList request as:
<estimateKeywordList>
...
</estimateKeywordList>
You would specify the input parameters as:
<keywordRequests>
...
</keywordRequests>
and you would specify each individual field on the input
keywordRequests inside its own tag, for example:
<estimateKeywordList>
<keywordRequests>
<type>Broad</type>
<text>flowers</text>
<maxCpc>50000</maxCpc>
</keywordRequests>
</estimateKeywordList>
The upshot of the outcome is that you need to apply the information in the Reference to your own particular situation. When in doubt, consult the relevant WSDL. You will find links to the WSDL on the reference page for each service.
Note:The data services provide most operations in two forms: one for a single operation and one for a batch operation. Using a batch operation is more efficient than multiple calls to a single operation; therefore, you are encouraged to use the batch operations wherever possible.
API Reference
