Use Relative Date Keywords

Relative dates in v2

Report queries have a date_range field for specifying the dates for which to include data in the report. The following values can be set on date_range:

  • TODAY
  • YESTERDAY
  • MONTH_TO_DATE
  • YEAR_TO_DATE
  • LAST_7_DAYS
  • LAST_30_DAYS
  • CUSTOM

When date_range is set to CUSTOM or is unspecified, you should set start_date and end_date on the report query.

In your API request's query parameters, the start date parameters will look like this:

startDate.year=2021&startDate.month=3&startDate.day=1

Similarly, the end date parameters will look like this:

endDate.year=2021&endDate.month=3&endDate.day=3

Relative dates in v1.4

For convenience, the startDate and endDate parameters contain the following special keywords in place of the standard YYYY-MM-DD format:

  • today
  • startOfMonth
  • startOfYear
  • latest

These enable generation of reports relative to the current date. Also, they can be modified:

ReportsStart dateEnd date
Last 7 days’ performance today-6d today
Last month’s performance startOfMonth-1m startOfMonth-1d
Previous six months startOfMonth-6m startOfMonth-1d

The available operations are addition (+) and subtraction (-) and the ranges are (y)ears, (m)onths, (w)eeks, and (d)ays.

The latest keyword

The latest keyword works a bit differently. You can use it in place of YYYY or MM in the YYYY-MM-DD date format. For example, the latest 14th of March would be latest-03-14, whereas the latest 14th of the month would be latest-latest-14. These never return dates in the future.

Here are a few examples to make it clearer:

RequestedCurrent dateResult
latest-03-142014-03-152014-03-14
latest-03-142014-03-142014-03-14
latest-03-142014-03-132013-03-14
latest-latest-142014-03-152014-03-14
latest-latest-142014-03-142014-03-14
latest-latest-142014-03-132013-02-14

And here are some examples of date ranges using relative dates:

ReportsStart dateEnd date
The latest 14th of Marchlatest-03-14latest-03-14
The current US fiscal year so far (US fiscal years run from Oct 1 to Sep 30)latest-10-01today
The period since the last paycheck, for someone who is paid on the 25th of each monthlatest-latest-25today

An example report

Here's an example of report showing us the monthly performance of an account for the last six months.

Example report: Monthly earnings and clicks, last six months, show last month first
Start date:startOfMonth-6m
End date:startOfMonth-1d
Dimensions:MONTH
Metrics:EARNINGS, CLICKS
Sort:-MONTH

Result:

{
  "kind": "adsense#report",
  "totalMatchedRows": "6",
  "headers": [
    {"name": "MONTH", "type": "DIMENSION" }
    {"name": "EARNINGS", "type": "METRIC_CURRENCY", "currency": "USD"}
    {"name": "PAGE_VIEWS", "type": "METRIC_TALLY"}
  ],
  "rows": [
    ["2013-03", "285", "46320"],
    ...
    ["2012-10", "298", "49201"]
  ],
  "totals": ["", "1841", "300278"],
  "averages": ["", "288", "47501", ]
}
Example report
Figure 3: Example report

Next steps