Common pitfalls

The AdSense APIs have calls to generate new and saved reports. They can contain simple analytics like earnings per day or very complex tables of click-through rates per custom channel per country. This guide presents a list of edge cases that should be correctly handled for a solid integration with the APIs.

Report structure

A report in JSON looks like this:

{
  "kind": "adsense#report",
  "totalMatchedRows": long,
  "headers": [
    {
      "name": string,
      "type": string,
      "currency": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "totals": [
    string
  ],
  "averages": [
    string
  ],
  "warnings": [
    string
  ],
  "startDate": string,
  "endDate": string
}

Descriptions of these attributes can be found in the reports.generate method’s documentation.

Using chronological dimensions: DATE, WEEK and MONTH

Reports can be empty or have gaps

If there was no activity during the time period specified in the request, no ad requests are generated and the report service won’t show rows for those time periods. This is important if you are, for example, plotting a graph.

Check out the Filling in Dates guide for more information.

Requesting MONTH and WEEK dimensions in the same report

This report will probably have negative or unexpected consequences. If a week belongs to two different months it will show two rows for the same week: one for each month.

Example:

Dimensions	Metrics	Start date	End date
WEEK MONTH	CLICKS	2014-04-28	2014-05-03

Returns:

MONTH	WEEK*	CLICKS
2014-04	2014-04-27	50
2014-05	2014-04-27	43

*first day of the week

Solution

Remove MONTH from the report.

WEEK	CLICKS
2014-04-27	93

Collating dimension values

When requesting dimensions like the ones related to, for example, platforms (desktop, high-end mobile devices...), only the platforms with activity will be shown. If a given day, week or month has no visits from high-end mobile devices, it will have no information for that category.

Example:

Dimensions	Metrics	Start date	End date
PLATFORM_TYPE_NAME MONTH	AD_REQUESTS	2014-02-01	2014-03-31

Returns:

MONTH	PLATFORM_TYPE_NAME	AD_REQUESTS
2014-03	Desktop	100
2014-03	High-end mobile devices	5
2014-04	Desktop	75

Solution

When processing the report results, assume a value of zero for any dimension values that do not appear in the results:

MONTH	PLATFORM_TYPE_NAME	AD_REQUESTS
2014-03	Desktop	100
2014-03	High-end mobile devices	5
2014-04	Desktop	75
2014-04	High-end mobile devices	0

Combining multiple contiguous reports

Sometimes a report is too large to be generated all at once and it has to be split. If your app does this, consider these cases:

1. If you’re using WEEK or MONTH dimensions and you’re splitting the report in the middle of a week or month, each report will have duplicated entries with different data.
2. Make sure all the reports have the same metrics and dimensions, as data might not be combinable using different dimensions.

Special accounts

Some of your users might have AdSense accounts with attributes that you don’t expect or know about. Make sure to take into account:

1. Publishers with thousands of domains or sites
2. Publishers with thousands of ad units or custom channels
3. Publishers that would like to report on multiple ad clients (AdSense for Search, AdSense for Video, etc.)

Multiple accounts

Users can have access to more than one AdSense account. An account ID has to be specified for every call to the API for this reason. A call to accounts.list fetches a list of accounts and an account chooser dialog should be displayed to the user. It can be bypassed if the number of fetched accounts is one.

Time zone changes

AdSense Publishers can change their timezone at any time and this can produce spikes or dips in the reports.