The Google AdSense Host API is no longer available for new partners and is in maintenance mode. AdSense for Platforms is a new product offering similar to the Google AdSense Host API, with additional functionality.

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