Friday, December 21, 2012

Using advanced date ranges in AdSense APIs

In the AdSense Management API and AdSense Host API, you can let us manage date calculations for you. Apart from the standard YYYY-MM-DD format, all date fields accept the following special keywords:
  • today
  • startOfMonth
  • startOfYear
With these keywords you can define useful date ranges such as the following:

Start date End date
This month’s performance so far startOfMonth today
This year’s performance so far startOfYear today

But here is the really useful part: there is a handy feature that you can use to calculate relative dates by adding or subtracting days, weeks, months, or years:

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

You can use up to two operations per date. Let’s say we need to compare last month with the same period last year. We would need two requests like these two requests with these start and end dates:

Start date End date
Last month’s performance startOfMonth-1m startOfMonth-1d
Same month last year startOfMonth-1m-1y startOfMonth-1d-1y

If you want to try these out, we recommend using the APIs explorer. You’ll find it at the bottom of each method documentation page:
If you have any questions about this post or the AdSense APIs in general, visit the AdSense API Forum. You can also follow our Google Ads Developers G+ page for ad-related updates.