Segmented Reports

The new Search Ads 360 Reporting API is now available. The new API provides enhanced flexibility to build custom reports and integrate the data into your reporting applications and processes. Learn more about migrating to and using the new Search Ads 360 Reporting API.

The Search Ads 360 API returns only aggregated data unless you request more detailed, segmented data. For example, the clicks column in a keyword report lists the total number of clicks on a keyword during the time range you specify.

keywordText	keywordLandingPage	clicks
widgets	http://www.example.com	6000

But if you request a keyword report that segments by quarter, for each keyword you'll see one row for each quarter, and the clicks column will list the quarterly totals.

keywordText	keywordLandingPage	quarterStart	quarterEnd	clicks
widgets	http://www.example.com	2012-01-01	2012-03-31	1000
widgets	http://www.example.com	2012-04-01	2012-06-30	1000
widgets	http://www.example.com	2012-07-01	2012-09-30	1000
widgets	http://www.example.com	2012-10-01	2012-12-31	3000

Note that a segmented report returns a row only if data is available for a segment. For example, in a keyword report with the floodlightActivity column, a keyword and Floodlight activity pair will not appear in the report if there are no metrics attributed to it for the report date range.

Some segments are incompatible with specific columns

Some segments may cause specific columns to return invalid data. For example, segmenting by floodlightActivity is meaningful only if you include columns that report Floodlight data, such as dfaActions, dfaRevenue, dfaTransactions, and dfaWeightedActions. Other types of conversion columns (such as adWordsConversions), or columns that report engine metrics (such as clicks and impressions), don't contain data reported by Floodlight, so they return invalid values if you segment a report by floodlightActivity.

How to request a segmented report

To request a segmented report, include a column that lists segment as its behavior in the Types of Reports reference.

The following asynchronous request is for a keyword report segmented by quarter. The clicks column in each row will contain the total number of clicks for the quarter:

{
  "reportScope": {
    "agencyId": "20700000000000123", // Replace with your IDs
    "advertiserId": "2170000012345" // Replace with your IDs
  },
  "reportType": "keyword",

  "columns": [
     { "columnName": "campaignId" },
     { "columnName": "keywordText" },
     { "columnName": "keywordLandingPage" },

     { "columnName": "quarterStart" },
     { "columnName": "quarterEnd" },
     { "columnName": "clicks" },
  ]
  "timeRange" : {
    "startDate" : "2012-01-01",
    "endDate" : "2012-12-31"
  },
  "downloadFormat": "csv",
  "maxRowsPerFile": 5000000,
  "statisticsCurrency": "agency",
  "verifySingleTimeZone": false,
  "includeRemovedEntities": false
}
  

Note: Be careful with dates. If you're requesting a quarterly report, make sure that the report's timeRange includes the entire quarter. Otherwise you'll get only partial results, which might make people think there's been a drastic reduction in clicks, revenue, and so on.

Requesting multiple segments

You can include more than one segment column in a request. Note the following:

• If you segment by week, month, or quarter, we recommend that you include both the start and end columns in your request. For example, in a quarterly report, include both the quarterStart and quarterEnd columns. Including both of these columns will output the period's start and end dates, which will help confirm that you've included data for each full period.

• You cannot include different types of time-related segments in the same request. For example, you cannot segment by quarter and month in the same request.

• The number of rows could increase exponentially with each additional segment.