Use Relative Date Keywords

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

  • today
  • startOfMonth
  • startOfYear
  • latest

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

ReportsStart dateEnd date
Last 7 days’ performancetoday-6dtoday
Last month’s performancestartOfMonth-1mstartOfMonth-1d
Previous six monthsstartOfMonth-6mstartOfMonth-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