Report Option Examples

This section describes strategies for maximizing the performance for reports that are large in size (large number of rows) or expanse (long reporting period).

Overview

  • Timeframe and Granularity. Highly granular reports that cover long reporting periods (such as a year-to-date daily reports) are not supported in a single API call. If you require long reports that have a high level of granularity, break up the report into several smaller reporting periods using multiple API calls.

Filter Options

Use the filterOptions array to reduce the scope of your reports by identifying specific dimensions of data that are of interest. Dimensions may be included in or excluded from reports.

The array comprises one or more Filter objects that consist of an includedValues object, an includedValues attribute, and a dimensionTypeId attribute. While the dimensionTypeId identifies dimension, the includedValues array identifies one or more dimension-value filters, and the isExcluded attribute determines whether the matching data is returned.

The dimension-value filters (includedValues array) enable you to reduce the size of your reports by specifying the dimensions returned or specifying the dimensions that are not returned.

{
  "reportOption": {
    "dimensionTypeIds": [ 5 ],
    "filterOptions": [
      {
        "includeValues": [
          {
            "name": "France",
            "id": "250"
          }
        ],
       "isExcluded": "false",
        "dimensionTypeId": 19
      }
    ],
    ...

Top-N Reports

Use Top-N reports to return the top few (specified by the “limit” parameter) results sorted by a specific metric. Specify the metric id in the “metricTypeId” field.

To define a top-N report, specify a single dimension type ID in the dimensionTypeIds array and a limit value.

The following object generates a report that returns the top ten cities with the most ad spend within the time period you specify:

{
  "dimensionTypeIds": [21],
  "limitSpec": {
    "columns": [
      {
        "metricTypeId": 44
      }
    ],
    "limit": 10,
  }
}