Date Range Examples
  • 5 Minutes to read

    Date Range Examples


      Article summary

      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).

      ID

      Interval Type

      Description

      1

      Cumulative

      One row, where each column in the row provides data for the entire range. For example, for a two-week date range, a Cumulative report provides 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 provides the 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.

      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 provides 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 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:

      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-3

      Etc/GMT

      UTC+0

      Europe/London

      UTC+0

      Europe/Paris

      UTC+1

      Asia/Jerusalem

      UTC+2

      Asia/Dubai

      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


      Was this article helpful?

      What's Next