Date Range Examples¶

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

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.