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 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, see Recent Data Limitations.

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 by hour (5), day (2), week (4), month (3), or cumulative (1).

ID Interval Type Description
1 Cumulative One row, where each column in the row shows data for the entire range. For example, for a two-week date range, a Cumulative report shows two weeks worth of impressions, clicks, and conversions in a single row.
2 Day The number of rows depends on the date range, and one row represents one calendar day. Each row in a Day report shows the data for a specific date. For example, for a two-week date range, each of the 14 rows shows one day’s worth of impressions, clicks, and conversions.
3 Month The number of rows depends on the date range, and one row represents one full or partial calendar month.
4 Week The number of rows depends on the date range, and one row represents one calendar week. For example, for a two-week date range, each row in a Week report shows the impressions, clicks, and conversions for a specific week.
5 Hour There will be one row for each individual hour that has data. Each row represents a single pair of date and hour. For example, if the date range of the report is two full days, and we group by Hour, there will be 48 rows.

Hourly Reports

An hourly report displays report data aggregated on a 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 providee day-by-day performance statistics.

Each row in daily report shows the data for a specific date.

For example, for a two-week date range, each of the 14 rows shows 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, see Reporting API Limitations.

All Time Reports

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

The Report payload specifies a cumulaive 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 (fileterOptions) 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. The 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 date range of the report excludes data from the six hours prior to the report date. To learn more, see 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:

Table 12 Offset Values
Value Offset
America/Los_Angeles UTC-8
America/Denver UTC-7
America/Chicago UTC-6
America/El_Salvador UTC-6
America/Mexico_City UTC-6
America/New_York UTC-5
America/Bogota UTC-5
America/Lima UTC-5
America/Halifax UTC-4
America/Puerto_Rico UTC-4
America/Argentina/Buenos_Aires UTC-3
America/Santiago UTC-3
America/Sao_Paulo UTC-2
Etc/GMT UTC+0
Europe/London UTC+0
Europe/Paris UTC+1
Asia/Jerusalem UTC+2
Asia/Debai UTC+4
Asia/Karachi UTC+5
Asia/Dhaka UTC+6
Asia/Jakarta UTC+7
Australia/Perth UTC+8
Asia/Shanghai UTC+8
Asia/Tokyo UTC+9
Australia/Sydney UTC+11
Pacific/Auckland UTC+13