ReportService
ReportService provides operations for getting reports about
your AdWords account. The reports are in XML format.
To create, validate, schedule and download a report:
- Create report job -
Create a data object that corresponds to the type of report job you
want. These are different for v10 and v11.
ReportJob is one of:
For v11, the report types are listed at
report rules
For statically typed languages, such as Java, create an instance of a
specific report job. For dynamically typed languages such as Perl and
Python, create a ReportJob data object and specify its xsi:type attribute
to be the type of the report job.
- Validate report job -
For v11 or later, you should call
validateReportJob
with your DefinedReportJob before scheduling the report. This tests the
validity of your report and is important because if this request fails,
it costs only 1 unit, while if scheduleReportJob fails, it costs
substantially more.
- Schedule report job -
Send a
scheduleReportJob request to ReportService, passing the
ReportJob data object. The response is an ID for the scheduled report job.
The Report Center stores up to five reports. When the sixth report is
generated, the Report Center deletes the oldest one. Therefore, you should
be sure to download the reports that you want to keep.
- Get status of report job -
Send a
getReportJobStatus request. The status is Completed,
Pending, InProgress, or Failed.
- Get download URL -
When the status is Completed, get the download URL for the
report by sending the
getReportDownloadUrl request.
The returned URL is valid for five minutes. If you need to obtain another
URL, simply send another getReportDownloadUrl request. Be sure to keep the
returned URL confidential since it allows access to the report without the
need to login.
- Download report -
Download the report by sending an HTTP GET request to the download
URL using any HTTP client library.
Note: The keyword status values in the reports reflect
the new status values such as active and inactive. For details of keyword
status values, see the topic
Impact of the
New Keyword Evaluation System in the AdWords Help Center.
For more information about reports,
see the
Report Center section of the
AdWords Help Center -- this help covers the new v11 report types.
For more information about how to use the ReportService, see the overview section.
Requests
Deletes a report job along with the report it produced, if any.
Can delete a pending report job, but cannot delete a job in progress.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| reportJobId |
long |
The ID of the report job. |
Response
| Response type | Response description |
|---|
(none) |
|
Returns an array consisting of all jobs the user has scheduled.
Response
| Response type | Response description |
|---|
ReportJob[] |
an array of report jobs.
ReportJob is one of:
|
Returns a URL from which a compressed report with the given job ID can be
downloaded (in Gzip format). After invoking this method, the caller can
do a regular HTTP GET on the returned URL to retrieve the report.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| reportJobId |
long |
The ID of the report job. |
Response
| Response type | Response description |
|---|
string |
A URL from which the compressed report can be downloaded. |
Returns a URL from which the report with the given job ID can be
downloaded. After invoking this method, the caller can do a regular
HTTP GET on the returned URL to retrieve the report.
The reports are in XML format.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| reportJobId |
long |
The ID of the report job. |
Response
| Response type | Response description |
|---|
string |
A URL from which the report can be downloaded. |
Returns the status of the report job with the given reportJobId.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| reportJobId |
long |
The ID of the report job. |
Response
| Response type | Response description |
|---|
ReportJobStatus |
The report job status.
Values are:
- Pending
- InProgress
- Completed
- Failed
|
Schedules a report job for execution.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| job |
ReportJob |
The report job object that defines the options for the report.
For statically typed languages, such as Java, create an instance of a specific
report job.
For dynamically typed languages such as Perl and Python,
create a ReportJob data object and specify its xsi:type attribute to be the
type of the report job.
See the
Sample Code for examples of how to schedule reports in various
client languages.
ReportJob is one of:
|
Response
| Response type | Response description |
|---|
long |
The ID of the scheduled report job. |
This method takes a ReportJob and runs the validation logic against it.
If there are no problems, the method returns normally, otherwise
the appropriate exception is thrown.
Parameters
| Parameter name | Parameter type | Parameter description |
|---|
| job |
ReportJob |
the report job to validate
ReportJob is one of:
|
Response
| Response type | Response description |
|---|
(none) |
|
API Reference
