Date Range Examples

This article provides guidelines for specifying hourly, daily, and cumulative reports and for improving performance by reducing the size of reports.

Overview

The report payload specifies the data returned in a report.

The Report payload includes reportOption object, which enables you to filter report data based on dimension and metric values and the dateTypeId and intervalTypeId attributes, which enable you to control the range of data returned based on the age of the data.

• The dateTypeId specifies the date range for the data returned in the report. Data may be from the previous day, week, month, all time, or from a custom date range among other options.

• The intervalTypeId specifies the granularity of the data within the specified date range. The granularity of report data is defined by an interval type.

Note

For best results, ensure that the report excludes data from the six hours prior to the report date. To learn more, refer to Rate Limits.

The following examples demonstrate how you can specify dateTypeId and intervalTypeId attributes to return a variety of report data.

Report Intervals

The Report object’s intervalTypeId attribute specifies the granularity of data in a report; that is, the intervals at which the data is aggregated and reported.

The intervalTypeId attribute enables you to group report data by hour (5), day (2), week (4), month (3), or cumulative (1).

Hourly Reports

An hourly report displays report data aggregated on an hourly basis to provide day-by-day performance statistics.

Each row in an hourly report represents a single hour in the reporting period and displays data aggregates and metrics for that hour.

If the reporting period has a custom range of two days (dateTypeId = 11) and the data is grouped by hour (intervalTypeId: 5), the report returns 48 rows of data.

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds":  [ 5 ],
    "metricTypeIds": [ 44, 1, 2, 23, 11, 41, 43 ]
  },
  "dateTypeId": 6,
  "intervalTypeId": 2
}

Report data is grouped by order ID (dimensionTypeId: 5). The metricTypeIds array specifies the following report metrics: Impression, Click, Conversion, CTR, AdvertiserSpending, CPC, and CPA.

Daily Reports

A daily report displays report data aggregated on a daily basis to provide day-by-day performance statistics.

Each row in a daily report provides data for a specific date.

For example, for a two-week date range, each of the 14 rows provides one day’s worth of impressions, clicks, and conversions. The Report payload specifies a daily report (intervalTypeId: 2) of the previous two weeks of data (dateTypeId: 6).

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [ 5 ],
    "metricTypeIds": [ 44, 1, 2, 23, 11, 41, 43 ]
  },
  "dateTypeId": 6,
  "intervalTypeId": 5
}

Report data is grouped by order ID (dimensionTypeId: 5). The metricTypeIds array specifies the following report metrics: Impression, Click, Conversion, CTR, AdvertiserSpending, CPC, and CPA.

Cumulative Reports

A cumulative report displays report data aggregated into a single row of data providing a summary of an entire range of data.

The Report payload specifies a cumulative report (intervalTypeId: 1) of the previous two weeks of data (dateTypeId: 6).

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [5],
    "metricTypeIds": [ 44, 1, 2, 23, 11, 41, 43 ]
  },
  "dateTypeId": 6,
  "intervalTypeId": 1
}

Report data is grouped by order ID (dimensionTypeId: 5). The metricTypeIds array specifies the following report metrics: Impression, Click, Conversion, CTR, AdvertiserSpending, CPC, and CPA.

Reporting Periods

The dateTypeId specifies the reporting period.

Note

Option 10 (All Time) returns extremely large reports. Use it with a filter, and/or cumulative interval type.

For best results, ensure that the report excludes data from the six hours prior to the report date. To learn more, refer to Reporting API Limitations.

All Time Reports

An All Time report returns all of the data associated with the account from the time that a seat was activated.

The Report payload specifies a cumulative report (intervalTypeId: 1) of all data associated with the seat (dateTypeId: 6).

{
  "reportOption": {
    "timezone": "America/Los_Angeles",
    "currency": 4,
    "dimensionTypeIds": [],
    "metricTypeIds": [ 44, 1, 2, 23, 11, 41, 43 ]
  },
  "dateTypeId": 10,
  "intervalTypeId": 1
}

Because all time reports can return an extremely large amount of data, you should always specify the intervalTypeId as 1 (cumulative) or use a filter (filterOptions) to limit the data returned.

Custom Range Reports

The reportOption object enables you to define reports with custom date ranges (dateTypeId = 11), which are defined by custom start dates (startDate) and end dates (endDate).

If you do specify a custom date range, you must ensure that the startDate and endDate values include the correct offsets for the specified timezone.

In the following example, the reportOption object specifies that report data use the Asia/Shanghai time zone. Asia/Shanghai requires an offset of UTC+8. Consequently, an offset value of +08:00 is appended to the specified startDate and endDate values.

For best results, ensure that the date range of the report excludes data from the six hours prior to the report date. To learn more, check out Reporting API Limitations.

{
  "reportOption": {
    "timezone": "Asia/Shanghai",
    "currency": 3,
    "dimensionTypeIds": [ 1, 3, 4, 5, 6, 64 ],
    "filterOptions": [
      {
        "dimensionTypeId": 64,
        "isExcluded": false,
        "includeValues": [ {"id": 7} ]
      }
    ],
    "metricTypeIds": [ 1, 2, 23, 44, 46 ]
  },
  "intervalTypeId": 1,
  "dateTypeId": 11,
  "startDate": "2016-11-06T00:00:00+08:00",
  "endDate": "2016-11-06T23:59:59+08:00"
}

If you specify an offset, ensure that it is equivalent to the timezone value.

• The startDate attribute specifies the start time of date range of the report in the format yyyy-MM-dd'T'HH:mm:ss. For example: 2016-08-01T00:00:00.

• The endDate attribute specifies the end time of date range of the report in the format yyyy-MM-dd'T'HH:mm:ss. For example: 2016-08-01T00:00:00.

Time Zones

The timezone attribute specifies the time zone used for generating the reporting data.

If no timezone value is specified, America/New_York is used as the default.

timezone attribute values include: