Reporting on Yahoo Search Marketing API

This article tells us about how the Yahoo Search Marketing API service provide us to get the reports from Yahoo Search Engine. Currently mentioned on this article, based on Yahoo Enterprise Web Service version 7. And its various stages with a short description on each are depicted below. The communication between your client software and Yahoo server is possible through SOAP request and response. If we want to make a SOAP request to the server, first we need an API account in Yahoo Search Marketing API. Once we have enough access and credentials with us we can start adding different advertising entities like Campaigs, AdGroups, etc… to the Yahoo search engine. And similar like other search engines Yahoo also providing a test environment called Sandbox and for real or live work environment called as Production environment.

Different processing stages like create a report request and what are the things we have to pass to the Yahoo SE for getting a report all these cases explained below. In very simple words we can say like this, imagine we have all the access credentials with us now. First thing is send a report request to Yahoo, we have to mention the required parameters along with the request. If the request was successful it will try to poll our request on server. During first time the request will be in pending status. After few more polling, say 2-3 minutes, we will get the report Download URL as a response and the status become completed. And one more thing we have to taking care of the report download URL, its life span is five minutes. We could not download the report after five minutes from the generation of URL. If so we have to request for a new report download URL and download the report. And the reports are available in CSV, CSV_EXCEL, TSV, and XML formats. More over we can get the report details for the duration of yearly, monthly, weekly or daily even its possible on hourly basis.

About 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:

• Summary Reports: Includes performance data from your Yahoo! Search Marketing campaigns, either Sponsored Search or Content Match traffic, or both.

• Advanced Reports: Includes the performance data as well as conversion and advanced analytics data from your tagged web sites.

• Multi-Channel Reports: Includes the performance data, the conversion and advanced analytics data from your tagged web sites, and additional marketing activity you have uploaded using the web application. Multi-Channel reports are only available for accounts where tagging is enabled with Full Analytics at the master account level.

Yahoo Search Marketing supports the following list of reports:-

• AccountSummary – AccountSummaryByDay
• AdGroupSummary – AdGroupSummaryByDay
• AdKeywordSummary – AdKeywordSummaryByDay
• AdSummary – AdSummaryByDay
• AdDeliverySummary – AdDeliverySummaryByDay
• AdvancedAdKeywordPerformance – AdvancedAdKeywordPerformanceByDay
• AdvancedAdPerformance – AdvancedAdPerformanceByDay
• BillingTransactionDetail
• CampaignSummary – CampaignSummaryByDay
• ClickFilterAccountSummary – ClickFilterAccountSummaryByDay
• ClickFilterCampaignSummary – ClickFilterCampaignSummaryByDay
• DailySummary
• DayPartingAdGroupSummary – DayPartingAdGroupSummaryByDay
• DayPartingCampaignSummary – DayPartingCampaignSummaryByDay
• DemoAgeAdGroupSummary – DemoAgeAdGroupSummaryByDay
• DemoAgeCampaignSummary – DemoAgeCampaignSummary
• DemoGenderAdGroupSummary – DemoGenderAdGroupSummaryByDay
• DemoGenderCampaignSummary – DemoGenderCampaignSummaryByDay
• NetworkDistributionCampaignSummary – NetworkDistributionCampaignSummaryByDay
• NetworkDistributionAdGroupSummary – NetworkDistributionAdGroupSummaryByDay
• NetworkDistributionKeywordSummary – NetworkDistributionKeywordSummaryByDay
• GeoLocationAdGroupSummary – GeoLocationAdGroupSummaryByDay
• GeoLocationSummary – GeoLocationSummaryByDay
• KeywordSummary – KeywordSummaryByDay
• MultiChannelAccount – MultiChannelAccountByDay
• MultiChannelAdGroup – MultiChannelAdGroupByDay
• MultiChannelCampaign – MultiChannelCampaignByDay
• MultiChannelDaily
• MultiChannelMarketingActivity – MultiChannelMarketingActivityByDay

Report Management

BasicReportService provides operations for managing reports. This includes adding report requests, retrieving or checking the status of a report, and deleting reports.

Request a New Report

To request a new report, use the addReportRequest operation.This operation takes spend account ID as a optional parameter. If the spend account ID parameter is specified as null, the operation generates a report that aggregates metrics for all of the accounts that you have access to in the master account. Otherwise, the operation generates a report that aggregates metrics for the specified spend account.

The file output format of the report should be specified when using this operation. The FileOutputType enumeration lists the available file types for the report. When the boolean parameter zipped is set to true, the report is returned in zipped format. The actual report will be stored inside this zip file.

If you are requesting a large report in CSV Excel file type and unzipped format, please note that the report download will not work if the report has more than 64,000 rows. Please ensure you use zipped format for this use case.

The report request will be rejected if there is a similar report request in pending status. Please wait for the report to be processed before adding the same report request again.

Following attributes of a report request are not considered when identifying duplicate report requests. This means that even if you change the values of these attributes and resubmit the report request, it will still be identified as a duplicate, provided the original report request is in pending status:

• Report name
• Zip/Unzip format

This operation returns a report ID. You can use this ID to retrieve or delete the report.

A sample SOAP request to generate Yahoo Search Marketing API report is show below.

[xml]
<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://marketing.ews.yahooapis.com/V7" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2=" https://global.marketing.ews.yahooapis.com/V7">

<SOAP-ENV:Header>

<ns2:username>username</ns2:username>

<ns2:password>password</ns2:password>

<ns2:masterAccountID>masterAccountID</ns2:masterAccountID>

<ns2:accountID>accountID</ns2:accountID>

<ns2:license>license</ns2:license>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

<ns1:addReportRequest>

<ns1:accountID>accountID</ns1:accountID>

<ns1:reportRequest>

<ns1:campaignIDsxsi:nil="true"/>

<ns1:dateRange>Yesterday</ns1:dateRange>

<ns1:endDate xsi:nil="true"/>

<ns1:reportName>YahooCampaignReport</ns1:reportName>

<ns1:reportType>CampaignSummary</ns1:reportType>

<ns1:startDate xsi:nil="true"/>

</ns1:reportRequest>

<ns1:fileOutputFormat>

<ns1:fileOutputType>XML</ns1:fileOutputType>

<ns1:zipped>true</ns1:zipped>

</ns1:fileOutputFormat>

</ns1:addReportRequest>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>
[/xml]

Retrieve or Check the Status of a Report

To obtain information about the reports you have requested, use the getReportList operation. When the boolean parameter onlyCompleted is set to true, this operation returns only reports that are in completed state.

To retrieve a secure URL for downloading the report, or to check the status of a report, use the getReportDownloadUrl or getReportDownloadUrls operation. Both operations return a response object (or list of response objects) ReportDownloadInfo, that contains information required for downloading the report. This includes the status, download URL and file output format of the report. The download URL and file output format is available only if the report has been processed and is in completed status.

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 another one for the same report ID and try again.

The Marketing API does not return report data. Rather, use the report download URL to download the data, in the format you requested, using the HTTP GET method.

Running a Report

The general procedure to run a report is:

1. Check if the books are closed (optional).
2. Submit a request for a new report.
3. Check the status of the report to determine if it executed completely.
4. Obtain the URL for the completed report.
5. Use the URL to download the report using the HTTP GET method.

Depending on which operations you use, steps 3 and 4 may overlap.

What is Books Closed?

It is recommended that you wait until the books are closed before running a report. Use the isBooksClosed operation to periodically check the status of books. After the report is run, you may also check the information in the report header.

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.

Example 1

In this example, the books are not closed indicating that data is not complete. The books closed time is prior to 3/24 12:00 AM, inclusive of the end date, indicating that analytics still need to be collected for the calendar day 3/23.

Report Request

Report Start: 3/21/2007

Report End: 3/23/2007

Books Closed: 3/23/2007 7:15 PM

isBooksClosed = (Books Closed Time > Inclusive End Date) = false

Image from: Developer.searchmarketing.yahoo.com

Example 2

In this example, the books are closed and the data is considered complete. The books closed time is after 3/24 12:00 AM, inclusive of the end date, therefore all data has been collected for the calendar day 3/23.

Report Request

Report Start: 3/21/2007

Report End: 3/23/2007

Books Closed: 3/24/07 9:15 AM

isBooksClosed = (Books Closed Time > Inclusive End Date) = true

Image from: Developer.searchmarketing.yahoo.com

Delete a Report

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 50 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 manner as new reports are generated. Reports that are not deleted or rolled over with the 50 report limit remain available for upto 2 days.

Conclusion

Yahoo Search Marketing API service providing an easy method to get the reports from its server to our system with an efficient software. We have seen many of the features and the ease of usability to fetch any type of reports, which permits, from Yahoo search engine. We have the option to get this report with multi duration and multi type. So we can say that Yahoo Search Marketing API report process is an easy method to get the reports based on our requirement.