The Marketing API supports these reports.
Reports are available in CSV, CSV_EXCEL, TSV, and XML formats (CSV and CSV_EXCEL reports are referred to collectively as CSV reports).
CSV, TSV, and XML reports have report headers, which provide general information about the report. The XML report headers are described under Report Headers. CSV and TSV reports will include similar header information.
CSV, TSV, and XML reports have report elements, which provide the report data. XML report elements are referred to as attributes. CSV and TSV report elements are referred to as column names. The XML attributes and corresponding CSV and TVS column names are described under Report Elements. The tables in the sections below list all possible XML attributes for each report.
CSV and TSV reports will include all possible report elements (column headers). For non-US markets, the report elements are translated using the market's default locale or the market locale set per user per master account (see Setting Locales).
XML reports will include only those report elements (attributes) for which there is data or for which the value is not null.
If you require a consistent set of attributes in your XML reports, you must implement an in-line processing step during (or post-processing step after) the XML parsing. You will need to create a list of the desired attributes, determine your default values for these attributes (probably 0 or null), and then insert these attributes and default values into your XML reports when the actual attributes are not returned in the EWS response.
Concerning null data, non-computed attributes such as cost, numConv, and revenue are never null. If there is data in the mart at any selected aggregation, these attributes will always be 0 or greater. However, analytic attributes that are computed (via the non-computed attributes) are assigned the null value - and will not appear in the XML report - when the divisor is 0.
| Computed Attribute | Computation |
Value |
|---|---|---|
costPerConv |
(cost / numConv) |
null if numConv=0, non-null otherwise |
roas |
(revenue / cost) |
null if cost=0, non-null otherwise |
clickConvRate |
(numConv / numClick) |
null if numClick=0, non-null otherwise |
You can use the XSD schema definition file to validate the attributes in an XML report. However, the column names in CSV and TSV reports may not agree with the XSD file. First, the column names in these reports are localized into the market language. And second, the column names are designed to be human-readable; for example, the accountName XML attribute will appear as the "Account" column name.
For information on how to run reports, see the BasicReportService Overview.
Generated reports that contain a pre-determined set of metrics aggregated for the account.
| XML Attributes | ||
|---|---|---|
| accountID | cpc | numConv |
| accountName | ctr | numImpr |
| clickConvRate | date (ByDay report only) | revenue |
| cost | numAssist | roas |
| costPerConv | numClick | |
See Report Headers, Report Elements.
Generated reports that contain a pre-determined set of metrics aggregated for each ad group.
| XML Attributes | ||
|---|---|---|
| accountID | cost | numConv |
| accountName | costPerConv | numImpr |
| adGrpID | cpc | revenue |
| adGrpName | ctr | roas |
| clickConvRate | date (ByDay report only) | tacticID |
| cmpgnID | numAssist | |
| cmpgnName | numClick | |
See Report Headers, Report Elements.
Generated reports that contain a pre-determined set of metrics aggregated for each unique combination of ad and keyword in an ad group.
| XML Attributes | ||
|---|---|---|
| accountID | cmpgnName | numImpr |
| accountName | cost | numClick |
| adGrpID | costPerConv | numConv |
| adGrpName | cpc | qualityScore |
| adID | ctr | revenue |
| adName | date (ByDay report only) | roas |
| averagePosition | keywordID | urlID |
| clickConvRate | keywordName | url |
| cmpgnID | numAssist | |
See Report Headers, Report Elements.
Generated reports that contain a pre-determined set of metrics aggregated for each ad.
| XML Attributes | ||
|---|---|---|
| accountID | cmpgnID | numClick |
| accountName | cost | qualityScore |
| adGrpID | costPerConv | revenue |
| adGrpName | cpc | roas |
| adID | ctr | tacticID |
| adName | date (ByDay report only) | urlID |
| averagePosition | numAssist | url |
| clickConvRate | numClick | |
| cmpgnID | numConv | |
See Report Headers, Report Elements.
These generated reports, only available to accounts with tagging, are aggregated by unique combination of ad and keyword and contain metrics associated with the tags.
| XML Attributes | ||
|---|---|---|
| accountID | costPerConv | numProspect |
| accountName | costPerLead | qualityScore |
| adGrpID | costPerProspect | revenue |
| adGrpName | date (ByDay report only) | revPerAssist |
| adID | keywordID | revPerBrowser |
| adName | keywordName | revPerConv |
| cmpgnID | leadConvRate | revPerLead |
| cmpgnName | numAssist | revPerProspect |
| cost | numBrowser | roas |
| costPerAssist | numConv | urlID |
| costPerBrowser | numLead | url |
See Report Headers, Report Elements.
These generated reports, only available to accounts with tagging, are aggregated by ad and contain metrics associated with the tags.
| XML Attributes | ||
|---|---|---|
| accountID | costPerConv | revenue |
| accountName | costPerLead | revPerAssist |
| adGrpID | costPerProspect | revPerBrowser |
| adGrpName | date (ByDay report only) | revPerConv |
| adID | leadConvRate | revPerLead |
| adName | numAssist | revPerProspect |
| cmpgnID | numBrowser | roas |
| cmpgnName | numConv | tacticID |
| cost | numLead | urlID |
| costPerAssist | numProspect | url |
| costPerBrowser | qualityScore | |
See Report Headers, Report Elements.
A generated report that contains historical billing transaction data aggregated by account. The reporting period is restricted to the previous six calendar months.
| XML Attributes | ||
|---|---|---|
| accountID | transAmtTotal | transTime |
| ccNumber | transAmtVat | transType |
| transAmtGross | transDate | transTypeNls |
| transAmtNet | transNumber | |
See Report Headers, Report Elements.
Generated reports that contain a pre-determined set of metrics aggregated for each campaign.
| XML Attributes | ||
|---|---|---|
| accountID | costPerConv | numConv |
| accountName | cpc | numImpr |
| clickConvRate | ctr | revenue |
| cmpgnID | date (ByDay report only) | roas |
| cmpgnName | numAssist | |
| cost | numClick | |
See Report Headers, Report Elements.
Generated reports that contain a pre-determined set of metrics for the account aggregated by day.
| XML Attributes | ||
|---|---|---|
| clickConvRate | ctr | numConv |
| cost | date | numImpr |
| costPerConv | numAssist | revenue |
| cpc | numClick | roas |
See Report Headers, Report Elements.
Generated reports that contain a pre-determined set of metrics for each keyword.
| XML Attributes | ||
|---|---|---|
| accountID | cost | numClick |
| accountName | costPerConv | numConv |
| adGrpID | cpc | numImpr |
| adGrpName | ctr | revenue |
| averagePosition | date (ByDay report only) | roas |
| clickConvRate | keywordID | urlID |
| cmpgnID | keywordName | url |
| cmpgnName | numAssist | |
See Report Headers, Report Elements.
These generated reports, only available to accounts with tagging, are aggregated by account and contain metrics associated with the tags.
| XML Attributes | ||
|---|---|---|
| accountID | date (ByDay report only) | revPerAssist |
| accountName | leadConvRate | revPerBrowser |
| cost | numAssist | revPerConv |
| costPerAssist | numBrowser | revPerLead |
| costPerBrowser | numConv | revPerProspect |
| costPerConv | numLead | roas |
| costPerLead | numProspect | |
| costPerProspect | revenue | |
See Report Headers, Report Elements.
These reports, only available to accounts with tagging, are aggregated by ad group and contain metrics associated with the tags.
| XML Attributes | ||
|---|---|---|
| accountID | costPerConv | numProspect |
| accountName | costPerLead | revenue |
| adGrpID | costPerProspect | revPerAssist |
| adGrpName | date (ByDay report only) | revPerBrowser |
| cmpgnID | leadConvRate | revPerConv |
| cmpgnName | numAssist | revPerLead |
| cost | numBrowser | revPerProspect |
| costPerAssist | numConv | roas |
| costPerBrowser | numLead | tacticID |
See Report Headers, Report Elements.
These generated reports, only available to accounts with tagging, are aggregated by campaign and contain metrics associated with the tags.
| XML Attributes | ||
|---|---|---|
| accountID | costPerLead | numProspect |
| accountName | costPerProspect | revenue |
| cmpgnID | date (ByDay report only) | revPerAssist |
| cmpgnName | leadConvRate | revPerBrowser |
| cost | numAssist | revPerConv |
| costPerAssist | numBrowser | revPerLead |
| costPerBrowser | numConv | revPerProspect |
| costPerConv | numLead | roas |
See Report Headers, Report Elements.
This generated report, only available to accounts with tagging, is aggregated by day and contains metrics associated with the tags.
| XML Attributes | ||
|---|---|---|
| cost | leadConvRate | revPerAssist |
| costPerAssist | numAssist | revPerBrowser |
| costPerBrowser | numBrowser | revPerConv |
| costPerConv | numConv | revPerLead |
| costPerLead | numLead | revPerProspect |
| costPerProspect | numProspect | roas |
| date | revenue | |
See Report Headers, Report Elements.
These generated reports, only available to accounts with tagging, are aggregated by marketing activity and contain analytics for the marketing activities in the specified channels and tactics.
| XML Attributes | ||
|---|---|---|
| accountID | costPerLead | numProspect |
| accountName | costPerProspect | revenue |
| adGrpID | date (ByDay report only) | revPerAssist |
| adGrpName | leadConvRate | revPerBrowser |
| cmpgnID | mktActID | revPerConv |
| cmpgnName | mktActName | revPerLead |
| cost | numAssist | revPerProspect |
| costPerAssist | numBrowser | roas |
| costPerBrowser | numConv | urlID |
| costPerConv | numLead | url |
See Report Headers, Report Elements.
XML report headers are described here. CVS and TVS reports will contain similar header information.
| XML Attribute | Description |
|---|---|
| booksClosed | Indicates if the books were closed (true) or not closed (false) when the report was run (see Books Closed). For CVS and TVS reports, the report header will include a warning message if the books were not closed (if the warning message does not appear, you may assume the books were closed). |
| booksClosedTimeStamp | The last date for which the data is complete for the account. |
| createDate | The date the report was created. |
| dateEnd | The end date of the report. |
| dateStart | The start date of the report. |
| masterAccountID | The master account ID. |
| masterAccountName | The master account name. |
| name | The report name. |
| sortColumn | The primary sort or aggregation column. |
| sortOrder | The sort order, either ascending (asc) or descending (dsc). |
XML and CSV/TSV report elements are described here.
| XML Attribute | CSV/TSV Column Name | Description |
|---|---|---|
| accountID | Account ID | The unique ID of the account. |
| accountName | Account Name | The name of the account. |
| adGrpID | Ad Group ID | The unique ID of the ad group. |
| adGrpName | Ad Group Name | The name of the ad group. |
| adID | Ad ID | The unique ID of the ad. |
| adName | Ad Name | The name of the ad. |
| averagePosition | Average Position | The position in which your ad is displayed, on average, on the search results page. |
| ccNumber | Credit Card Number | The credit card number used for the transaction. |
| clickConvRate | Conversion Rate | A percentage describing the number of conversions compared to the number of clicks. |
| cmpgnID | Campaign ID | The unique ID of the campaign. |
| cmpgnName | Campaign Name | The user-specified name of a campaign. |
| cost | Cost | The actual amount you paid for a click. |
| costPerAssist | Cost Per Assist | Your cost, divided by the number of assists. |
| costPerBrowser | Cost Per Browser | Your cost, divided by the number of browsers. |
| costPerConv | Cost Per Conversion | Your cost, divided by the number of conversions. |
| costPerLead | Cost Per Lead | Your cost, divided by the number of leads. |
| costPerProspect | Cost Per Prospect | Your cost, divided by the number of prospects. |
| cpc | Cost Per Click | Your cost, divided by the number of clicks received. |
| ctr | Click-Through Rate | The number of times an ad was clicked divided by the number of times it was displayed. Example: An ad that was clicked 25 times out of 100 times displayed has a click-through rate of 25%. |
| date | Date | The activity date. |
| keywordID | Keyword ID | The unique ID of the keyword. |
| keywordName | Keyword Text | The keyword or keyword phrase you are bidding on. |
| leadConvRate | Conversion Rate | A percentage describing the number of conversions compared to the number of leads. |
| mktActID | Marketing Activity ID | The unique ID for the user-defined marketing activity. If the marketing activity is Sponsored Search, the mktActID will contain the keyword ID. |
| mktActName | Marketing Activity Name | The name of the user-defined marketing activity. If the marketing activity is Sponsored Search, the mktActName will contain the keyword text. |
| numAssist | Number of Assists | When a keyword indirectly contributes to a conversion, an assist is recorded. |
| numBrowser | Number of Browsers | A user who clicks one level past the landing page on your site. |
| numClick | Number of Clicks | When your ad is selected, a click occurs. |
| numConv | Number of Conversions | The number of times a click leads to a conversion (the completion of an action on your site that you value). |
| numImpr | Number of Ad Impressions | The number of times an ad was displayed and available to be clicked. |
| numLead | Number of Leads | A user who reaches a pre-determined page on your web site. |
| numProspect | Number of Prospects | A user who reaches the page on your web site just before conversion. |
| qualityScore | Quality Index | A relative measure of your ad's performance. The quality score (quality index) takes into account the click-through rate and other relevancy factors. |
| revenue | Revenue | The amount of money that this marketing activity has generated for your business. |
| revPerAssist | Revenue Per Assist | The revenue earned for each assist. |
| revPerBrowser | Revenue Per Browser | The revenue earned per browser. |
| revPerConv | Revenue Per Conversion | The revenue earned on a conversion. |
| revPerLead | Revenue Per Lead | The revenue earned per lead. |
| revPerProspect | Revenue Per Prospect | The revenue earned per prospect. |
| roas | Return on Ad Spend | A percentage describing the amount of money earned per currency unit spent: dollars, yen, Euros, or other. |
| tacticID | Tactic ID | The unique identifier for the tacticName reported for the ad. 21 - Sponsored Search; 24 - Content Match. |
| transAmtGross | Gross Amount | The amount before VAT. |
| transAmtNet | Net Amount | The amount including VAT. |
| transAmtTotal | Amount Attempted | The attempted charge amount. |
| transAmtVat | VAT Amount | The Value Added Tax (VAT) amount. Inclusion is conditional, depending on the market. |
| transDate | Date | The date of the transaction. |
| transNumber | Trans Number | The transaction number. |
| transTime | Trans Time | The time of the transaction. |
| transType | Type | The transaction type. |
| transTypeNls | NLS Type | The "National Language Support" type which contains the local language description of the transaction type. |
| urlID | URL ID | The unique identifier for the URL. |
| url | URL | The URL served with the ad. |