--- title: "Date Range Examples" slug: "date-range-examples" updated: 2025-02-20T16:40:06Z published: 2025-02-20T16:40:06Z canonical: "help.yahooinc.com/date-range-examples" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt > Use this file to discover all available pages before exploring further. # 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] > 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](https://help.yahooinc.com/dsp-api/docs/limits#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. ```plaintext {  "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`). ```plaintext {  "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`). ```plaintext {  "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] > 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](/dsp-api/docs/limits). ### 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`). ```plaintext {  "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/Shangha`i 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](/dsp-api/docs/limits). ```plaintext {  "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. > [!WARNING] > Important > > - If no timezone value is specified, America/New_York is used as the default. > - Ensure that the startDate and endDate offsets account for **daylight savings time** if applicable. > > For example, for timezone=America/Los_Angeles (PST) and is not the default timezone, which is EST. > - During DST, offset needs to -07:00. > - After DST, offset needs to -08:00. > - If startDate is outside DST and endDate is within DST, then startDate offset is -08:00 and endDate offset is -07:00. > - If startDate is within DST and endDate is outside DST, then startDate offset is -07:00 and endDate offset is -08:00. 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 |