v1.4 of the AdSense Management API is now deprecated. This version will stop returning data on October 12, 2021. Please migrate to v2 as soon as possible.

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