The BasicReportService provides operations for requesting and managing reports.
The BasicReportService provides operations for requesting and managing reports that contain information about the performance of your accounts, campaigns, ad groups, ads, and keywords.
Three types of reports are available:
Many of the reports have two versions, allowing you to run a report either by reporting period or by day (see Report Details).
The general procedure to run a report is:
Depending on which operations you use, steps 3 and 4 may overlap.
We recommend that you wait until the books are closed before running a report. Use the isBooksClosed operation to periodically check the status of books closed. After the report is run, you may also check the information in the report header (see Report Headers).
isBooksClosed = (Books Closed Time > Inclusive End Date)
If the books closed time is greater than the inclusive end date (the full 24 hours of the report end date), then isBooksClosed is true and the data in the report is considered complete. If the books closed time is less than the inclusive end date, then isBooksClosed is false and the data in the report is considered incomplete.
In this example, the books are not closed indicating the data is not complete. The books closed time is prior to 3/24 12:00 AM (the inclusive end date), indicating that analytics still need to be collected for the calendar day 3/23.
Report Request
In this example, the books are closed and the data is considered complete. The books closed time is after 3/24 12:00 AM (the inclusive end date), therefore all data has been collected for the calendar day 3/23.
Report Request
BasicReportService provides operations to request, retrieve or check the status of, and delete reports.
To request a new report, use the addReportRequestForAccountID or addReportRequestWithAccountAggregation operation. The first operation aggregates metrics by account. The second operation aggregates metrics for all of the accounts that you have access to in the master account.
Both operations return a report ID. You will need this ID to retrieve or delete the report.
To obtain information about the reports you have requested, use the getReportList operation. When the boolean parameter onlyCompleted is set to true, only reports with the status COMPLETE are returned.
To retrieve a secure report URL or to check the status of a report, use the getReportOutputURL operation or getReportOutputURLs operation. Both operations return either the report URL of a completed report or the status of an incomplete report.
As noted, the Marketing API does not return report data. Rather, you use the report URL to download the data, in the format you requested, using the HTTP GET method.
For security reasons, report URLs are valid for 5 minutes only. When you request a URL, you should use it immediately to fetch the report. If the URL expires you can request a new one and try again.
Note: A report is finished running and considered "complete" when the status of the report is COMPLETE (see ReportInfo). However, the data in a report is considered "complete" only if books closed is true (see Books Closed).
To delete a report, use the deleteReport operation or the deleteReports operation. The first operation deletes one report. The second operation deletes a list of reports.
EWS stores up to five completed reports per master account per user. You can manually delete reports using the delete operations; otherwise, the system automatically removes reports in a first-in first-out fashion as new reports are generated. Reports that are not deleted or rolled over with the five report limit remain available for up to 30 days.