Google Ads Developer Blog

Announcing Three New Reporting Dimensions for AdMob Publishers

2015-06-11T10:51:00.000-07:00

Today we’re announcing the availability of three new reporting dimensions created specifically for AdMob publishers: APP_ID, APP_NAME, and APP_PLATFORM.

Here’s how they work:

APP_ID - This dimension matches the store ID of an application. It will be prefixed with “1:” for an App Store ID (iOS) and “2:” for a Google Play ID (Android). For example, “1:476954712” or “2:com.labpixies.lineup”.
APP_NAME - Matches the name of an application, like “Flood-It!” or “Line Up”.
APP_PLATFORM - This dimension can partition results by platform (e.g. “Android” or “iOS”).

These new dimensions are available now in the AdSense Management API. If you’re unfamiliar with it, the AdSense Management API is a web-based API that you can query to get information about your AdSense account. There are client libraries for a number of platforms, though any standard HTTP client can send requests to it and parse the responses. With a little code and these new dimensions, you can create custom reports about a single app, a family of them, or even your entire platform lineup!

For more information on building and customizing AdMob reports, check out the reporting section of the AdMob developer site. You can also use the API Explorer to test out queries that include these fields.

- Andrew Brogdon, Mobile Ads Developer Relations

Accounts.name changes in the AdSense APIs

2014-10-06T09:38:00.000-07:00

We recently deprecated the default namespace in the AdSense Management API so now you should show an account picker to your users and add an account ID to all requests.

The Accounts resource offers both a name and an ID but for most accounts these were showing the same string (something like "pub-12345678901234"). To make the process more intuitive for users, we are improving the logic behind the name.

From now on, the account.name property will have the company name or, in its absence, the contact name. If you still want to show the account ID, just use the id field.

This also applies to the Host API, although the default namespace can still be used.

As always, if you have any questions, feel free to drop us a line on our API forums.

- Jose Alcérreca, AdSense API Team

Deprecation of the default namespace in the AdSense Management API

2014-02-20T02:47:00.001-08:00

TL;DR Projects using the AdSense Management API should now check for accounts with multiple AdSense/AdX accounts and let users pick instead of using the default namespace, as it will be disabled for some accounts.

API users with access to more than one AdSense or AdX accounts will receive an error when using the default namespace due to cases of ambiguity. We expect a very small percentage of users to have this problem, as this functionality is restricted to a limited set of accounts.

To avoid complications, make sure you're not using the default account namespace adclients.list, adunits.getAdCode, etc. and specify an account ID for every call. For that, use accounts.adclients.list, accounts.adunits.getAdCode, etc. You’ll find the whole list of calls in the API reference pages.

The flow you should always use from now on is:

Authenticate
Call accounts.list
Show a publisher account picker if there's more than one account
Do the rest of the requests using the account ID

If you have questions about this change or need help with updating your code, please let us know on the AdSense API forum or our Google+ page.

- Jose Alcérreca, AdSense API Team

AdSense Management API v1.4 released

2013-12-10T13:08:00.000-08:00

Version 1.4 of the AdSense Management API is now available and comes with new features mainly based on suggestions and requests from developers:

List your AdSense account payments: Now you can list your payments in the corresponding currency.
Dismiss alerts: If an alert is dismissible, you can now call the delete method that will hide it in the API and AdSense web interface.
Added start and end dates to the reports response: Specially important if you’re using relative dates when generating reports (today, yesterday, firstDayOfMonth-1m, etc.), the response now includes the date range you requested.

If you are new to the API, check out the new getting started video that covers everything you need to know to start your integration with the AdSense Management API.

Remember to visit the AdSense API forum or our Google+ page if you need any help implementing these new features!

- Jose Alcérreca, AdSense API Team

Metrics and dimensions in the AdSense and Ad Exchange Seller REST APIs

2013-07-11T09:37:00.001-07:00

We have recently published several new resources to help developers build reporting calls to the API:

1. Metrics and dimensions reference pages, with each defined by the relevant values, formats and limits.

2. New metadata calls in the AdSense Management API V1.3 that allow developers to fetch the list of available dimensions and metrics, check compatibility between each other and find out what products are supported. A sample response might be:

{
  "kind": "adsense#reportingMetadataEntry",
  "id": "EXAMPLE_DIMENSION",
  "compatibleDimensions": [
    "1",
    "2",
    "4",
    ...
  ],
  "compatibleMetrics": [
    "AD_REQUESTS",
    "AD_REQUESTS_COVERAGE",
    "AD_REQUESTS_CTR",
    ...
  ],
  "supportedProducts": [
    "AFMC",
    "AFC",
    "AFV"
  ]
},

The compatibleDimensions field shows a list where each item is an integer representing a group of compatible dimensions. As there is no one-to-one relation between compatible dimensions, they are represented as groups (as shown below).

Examples

Group #1	Group #2	Group #3	Group #4
AD_CLIENT_ID AD_FORMAT_CODE AD_FORMAT_NAME BID_TYPE_CODE BID_TYPE_NAME DATE DOMAIN_NAME MONTH PLATFORM_TYPE_CODE PLATFORM_TYPE_NAME PRODUCT_CODE PRODUCT_NAME TARGETING_TYPE_CODE TARGETING_TYPE_NAME WEEK	AD_CLIENT_ID AD_FORMAT_CODE AD_FORMAT_NAME BID_TYPE_CODE BID_TYPE_NAME BUYER_NETWORK_ID BUYER_NETWORK_NAME DATE MONTH PLATFORM_TYPE_CODE PLATFORM_TYPE_NAME PRODUCT_CODE PRODUCT_NAME TARGETING_TYPE_CODE TARGETING_TYPE_NAME WEEK	AD_CLIENT_ID AD_FORMAT_CODE AD_FORMAT_NAME AD_UNIT_CODE AD_UNIT_ID AD_UNIT_NAME AD_UNIT_SIZE_CODE AD_UNIT_SIZE_NAME BID_TYPE_CODE BID_TYPE_NAME COUNTRY_CODE COUNTRY_NAME DATE MONTH PLATFORM_TYPE_CODE PLATFORM_TYPE_NAME PRODUCT_CODE PRODUCT_NAME TARGETING_TYPE_CODE TARGETING_TYPE_NAME WEEK	AD_CLIENT_ID AD_FORMAT_CODE AD_FORMAT_NAME BID_TYPE_CODE BID_TYPE_NAME COUNTRY_CODE COUNTRY_NAME CUSTOM_CHANNEL_CODE CUSTOM_CHANNEL_ID CUSTOM_CHANNEL_NAME DATE MONTH PLATFORM_TYPE_CODE PLATFORM_TYPE_NAME PRODUCT_CODE PRODUCT_NAME TARGETING_TYPE_CODE TARGETING_TYPE_NAME WEEK

From the previous table, note that:

DATE, MONTH and WEEK are compatible with every group.
DOMAIN_NAME (Group #1) is not compatible with CUSTOM_CHANNEL_* (Group #4).
If you want to report on ad units (Group #3) you won’t be able to use custom channels since a custom channel can be applied to one or more ad units.
Country names (Group #3) can be used in combination with ad units (Group #3) or custom channels (Group #4) but ad units cannot be combined with custom channels.

Remember to visit the AdSense API forums or our Google+ page if you need any help generating reports!

- Jose Alcérreca, AdSense API Team

AdSense Management API v1.3 Released

2013-06-18T05:51:00.000-07:00

Version 1.3 of the AdSense Management API is now available and comes with new features to help you retrieve more publisher and reporting information.

Metadata for reporting dimensions and metrics
This is a highly requested feature that provides information on the list of available dimensions and metrics for the publishers, as well as their compatibility. This is useful to help developers avoid generating reports with invalid dimensions and metrics.

Alerts
You can now list the publisher’s current alerts, in their default language or in the one you specify.

Ad code
You can now programmatically fetch the code of an ad unit using getAdCode.

Remember to visit the AdSense API forums or our Google+ page if you need any help implementing these new features!

- Jose Alcérreca, AdSense API Team

New Hangouts Coming Your Way

2013-02-19T16:00:00.000-08:00

You spoke and we listened; we like to do that in Developer Relations! We've heard your comments regarding Google Developer Live (GDL) events and we understand that they are often key to solving complex questions you have. In order to keep up with your demand we've scheduled another round of Hangouts for all of our products over the next few months.

In the upcoming Hangouts you'll notice that we are experimenting with some new formats. On some products you'll see engineer interviews, third party product discussions, or the typical Office Hours. You can view the newly scheduled hangouts on the Google Developers events page. Please RSVP by clicking the “I’ll be there” button if you plan on attending.

In case you haven’t joined us before, you'll need four things to join the hangout:

A Google+ account (sign up here)
The Google voice and video plugin installed on your computer
A quiet place to hangout so we can hear you.
A microphone is required and a video camera is preferred.

These hangouts are informal and conversational, which make them a great place to ask questions or give us feedback. If you have questions about our GDLs, reach out to us on the forums.

- Paul Rashidi, DFP API Team

Using advanced date ranges in AdSense APIs

2012-12-21T03:32:00.000-08:00

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.

- Jose Alcérreca, AdSense API Team

Migrating from AdSense Management API v1.0/1.1 to v1.2

2012-12-11T08:26:00.000-08:00

We’ll soon be sunsetting v1.0 and v1.1 of the AdSense Management API so we encourage you to migrate to v1.2 as soon as possible. To get you started, follow this simple guide.

If you don't use the client libraries you need to replace the version on the base URL that you are using:

https://www.googleapis.com/adsense/v1.1/

with

https://www.googleapis.com/adsense/v1.2/

That will allow you to continue using the API as you were and should require no further modifications to your code.

If you use the client libraries, what you need to do depends on the language you use:

Java
Download the latest client libraries and replace your project dependencies.
PHP
Make sure you get the latest files from the trunk of the repository. You may only need to replace trunk/src/contrib/Google_AdSenseService.php but you should update all the files you use.
Python
Good news for you! No need to download any libraries, the discovery service knows what to do. Create the service as follows:
http = httplib2.Http() service = build("adsense", "v1.2", http=http)
C#
Download the latest client libraries and replace your project dependencies.

To make sure you’re using the latest version, list your saved ad styles. It’s a new feature only available to v1.2, so if you don’t get an error, you’re on the right track.

To learn about the AdSense Management API read the docs and post your questions on the AdSense API Forum and we’ll do our best to help you! Also, follow our Google Ads Developers G+ page to receive important announcements and tips.

- Jose Alcérreca, AdSense API Team

New version of the AdSense Management API

2012-10-17T11:42:00.000-07:00

Good news, everyone! Version 1.2 of the AdSense Management API is now available, and with it come two new features:

the ability to retrieve saved ad styles
the ability to retrieve and run saved reports

In addition, we’ll soon be deprecating versions 1.0 and 1.1. These will both be sunset six months from now, on April 17, 2013. Migration to the new version should be extremely simple, since version 1.2 is a superset of both previous versions, with no breaking changes.

If you have any questions or comments, let us know in the forum!

- Sérgio Gomes, on behalf of the AdSense API Team

Announcing v4.1 of the AdSense Host API

2012-09-13T10:00:00.000-07:00

We’re happy to announce the release of v4.1 of the AdSense Host API. Don’t let the numbering fool you, this is a major update that provides a ton of new functionality!

The new version is intended as a full replacement of AdSense Host API v3 for ContentAds hosts, with a few extra features. Changes from v4 include added support for:

Account creation and association with a new publisher signup flow
Managing URL and custom channels on the host
Retrieving publisher ad clients
Creating and managing new publisher ad units, and retrieving ad code for them
Running publisher-side reports

With this new release, we're also announcing the sunset of version 3 of the Host API, to take place on January 1, 2013. Over the next few weeks, we will be getting in touch with existing hosts and helping them get started with the migration.

If you’re not an AdSense host yet and are interested in joining the program, take a look at our introduction page to find out more about the requirements and how it works.

Let us know if you have any questions!

- Sérgio Gomes, on behalf of the AdSense API Team

Docs Grow Ears: Google Feedback now in Google Ads Developer Documentation

2012-08-23T10:51:00.001-07:00

If you've recently visited any of the Google Ads Developer documentation, you may have noticed a "Feedback on this document" link at the top right corner of a page. That's right—you can now use that link to report errors, comment on existing content, or request further clarification for any of the Google Ads Developer docs:

In addition to this new channel, you can continue to reach out to us through the developer forums or Google Developers Live events.

Quang Nguyen, Ads Developer Relations Team

OAuth in Ads APIs

2012-08-21T12:00:00.000-07:00

Authorization is an important concern when writing software that interacts with Google’s Ads APIs. We’ve recently improved our documentation and published resources documenting how to use OAuth2 with many of our Ads APIs.

OAuth2 is an authorization flow that allows you to direct a user to a specially crafted Google URL where they grant permissions to your software to make changes to their account. With an authorized access token, you can make requests to Ads APIs on the user’s behalf. Benefits include:

Users don’t need to provide a username and password - they just log into Google.
No CAPTCHA challenges.
Limited scope - the user will only be prompted to grant access to a specific part of their account. For example, they could grant access to AdWords without the application being able to see their email or calendar.

OAuth2 is supported by:

The Ads API client libraries supported by Google have built-in support for OAuth2. We’ve included examples demonstrating how to use this feature in all client libraries. See your respective product and language product sites for more information on OAuth2.

We’re also hosting a Google Developers Live event covering how to use OAuth2 on August 23rd. This will be recorded if you can’t make it. If you have any questions about OAuth2, please post on the respective product API forums.

- Kevin Winter, AdWords API Team

Introducing the new Ads Developers Google+ Page

2012-08-21T05:03:00.000-07:00

Today we are excited to introduce a new channel for communication - Ads Developers Google+ Page. It's a place to stay informed, engaged and connected on Ads products and developer tools.

Add our Google+ page to your circles for the latest product and feature announcements, best practices, case studies, as well as opportunities to interact with and learn from Google's Ads Developer Relations team and other members of the developer community.

We look forward to having one place to bring timely updates, concise announcements, and to share information in multimedia formats across all Ads products, as well as to listen and respond to your comments.

- Danial Klimkin, Ads Developer Relations Team.

Next round of Google Ads Developers Live events

2012-08-08T12:44:00.000-07:00

Interested in more Google Ads Developers Live (Office Hours) events? We know you are because attendance has been great!

We've scheduled another round of events for AdWords, AdMob, DFP and AdSense APIs. You can view the newly scheduled live events on the Google Ads Developers Live page. Please add the events you are interested in to your calendar. You can follow our schedule by subscribing to the Google Ads Developers Office Hours calendar, which is also linked on this blog’s sidebar.

Just like in previous live events, you can join these hangouts to ask us questions or provide feedback about our products. In response to your request we will be adding AdWords API sessions for the Asia Pacific region and Japan. If you are from Asia Pacific countries or Australia and couldn’t join the hangouts before due to timezone inconvenience, we hope you will find these additional sessions more convenient. The live events in Japan will be in Japanese.

Events will rotate throughout the week to accommodate more people. We are also planning to make some of these events topic-based, where we will introduce you to a new feature of our product and then answer your questions on that topic. The dates and topics for these sessions will be announced in advance in separate blog posts.

In case you haven’t joined us before, you will need 3 things to join the hangout:

A Google+ account (sign up here)
The Google voice and video plugin installed on your computer
A quiet place to hangout so we can hear you

These hangouts are informal and conversational, which make them a great place to ask questions or give us feedback. If you have questions about our office hours, reach out to us on the forums.

- Anash P. Oommen, Ads Developer Relations Team

Meet an AdSense API Developer: Gregory Block

2012-06-14T10:21:00.001-07:00

A few months ago Ben Birt and Nick Johnson gave us some useful insights about the development of the AdSense Management API. This week, Gregory Block shares his experience of development against the API. Greg started the Google Publisher Toolbar project and is now the Team Leader of the development behind it.

Hello Greg, thanks for agreeing to be interviewed! Can you briefly describe your project and why you started the development?

The project started as a thought experiment - what would AdSense look like if we didn’t have a web interface for people to log in to, and we could only give you information within the context of your own site? It was originally called “AdSense Minus AdSense”, in homage to Garfield Minus Garfield.

Now, it’s a central part of our publisher strategy moving forward. Our customers use our products in concert with one another, but we send them to each product to figure out what’s going on.

Think of it as an “in-context” review tool for everything you do with your site. Ultimately, it will incorporate all of our platforms - AdSense, the DoubleClick Ad Exchange, DoubleClick for Publishers, Analytics, Webmaster Tools... we want you to know about all the information available within the context of the page you’re looking at.

People look at the websites they build and manage hundreds or thousands (and for some, more) of times each working day; they use our frontends only sporadically. We push information down into the place they need it most, at the right moment, in the right context.

You have more than 18 thousand users and an average rating of 4 stars: are you happy with your project?

It’s been hugely successful internally at convincing people to look beyond product silos and really focus on the needs of our end users. Ultimately, I’m aiming to provide a better, more accessible, more immediate, and more integrated experience than they can get from our web products. We’re going to support the whole publisher ecosystem, and I’m excited about all of the things we can do in that space.

It’s also a great showcase for our APIs - most of what the chrome extension does is accessible by any user from our public APIs.

What about the development process? Do you have any suggestions for other developers?

The process begins and ends with the end user. Efforts like the Google Publisher Toolbar drove our API strategy because we had a clear need we were trying to meet. Know your user, and have a clear vision for the product and how it helps that user do what they need to do.

Behind every good app is a good idea; but a good idea isn’t good enough - execution matters. The other important thing, in my opinion, is the toolchain. We take a strict approach towards building verifiably correct JavaScript, enforce strong type safety, and we bake in unit testing at development time. The toolbar isn’t one binary - it’s lots of binaries, all interacting with each other through messaging and callbacks, and we wouldn’t be able to get here without the help and support of our tools infrastructure.

If you had to mention one thing about developing against the AdSense API that positively impressed you during the development, what would that be?

Speed, speed, speed. A thin skin on the API is an order of magnitude faster than anything you can get out of our frontends. I think the API is well within reach of most of our publishers, and we can learn a lot from what people build from it. Some of those ideas we’ll be able to feed back in.

First and foremost, use the client libraries. There’s a vast amount of stuff taken care of automatically, and you’ll write and maintain less code.

Second, get your OAuth2 flow in place early. You’re going to spend a lot of time using it, and so it’s best to get that done right away. You’ll be tempted to just hack in a key you generated by hand into the source, but user experience matters. (I’m speaking from my own failures here.)

Third, think about security. We take a very, very cautious approach about inserting content into the page, and deciding what information is allowed to live in the DOM. We could improve the user experience by loosening that restriction, but we’re looking to bulletproof the product against social engineering and information leakage. As new features propagate down through the chrome versions, we’ll be using more and more of those secure mechanisms to deliver content in-site - the Chrome Infobars API, for example, will allow us to replace our in-page notification bar with one that is less intrusive to the user and doesn’t interact with page content. Sandboxed iframes will allow us to further restrict the security container of the in-page content, and allow us to move content that previously lived in stand-alone windows into in-page overlays and provide a richer experience to publishers. We use chrome as our sole platform because it’s secure - and when it comes to surfacing sensitive information like publisher revenue, security matters.

Last, prototype early, prototype often. There’s a whole skunkworks Android application we launched solely to experiment with and theorize on. Moreover, and in many ways more importantly, I depend on a UX person to cycle through a lot of ideas with me before roughing them out in code; we then cycle back through and iterate once we’re looking at implementations until we’re happy. On more than one occasion, I’ve cut a corner and not fully implemented something that was different in the mocks, and I’ve regretted it every. single. time. Don’t underestimate the power of good design.

And if you had the magic powers to request one additional feature and have it released immediately, what would that feature be?

In the immortal words of River Song, “Spoilers”.

What else do you do at Google?

I’m also responsible for the DoubleClick Ad Exchange Seller frontend here in London, as well as running a team called Publisher Insights that recommends revenue-impacting changes to the sites of AdSense and Ad Exchange publishers through simulated A/B experimentation.

Let’s talk hobbies and personal interests. What interests do you have outside work?

I play an awful lot of video games. I play through most games exactly once, to keep the size of the Pile of Shame (the games I bought but haven’t played yet) low. I’m currently on Act 3 of Diablo 3, and having mixed emotions about the experience.

I also have a Basset Hound named Daisy, who takes up an inordinate but pleasurable amount of my time.

Soooo.....what about Mass Effect3?

Utterly devastated. Taking reasonably ‘hard sci-fi’ and giving it a magical ending is a cardinal sin; I literally wish I could un-play all three. No amount of tender, love and care is going to help me forget.

There. I’ve said it. I feel better already.

Thanks Greg! Keep up the good work!

- Silvano Luciani, AdSense API Team
- Gregory Block, Ad Exchange Team

Hanging out for the Summer

2012-06-13T09:04:00.000-07:00

Interested in more Google+ Office Hour Hangouts? We know you are because attendance has been great! We've scheduled another round for all of our products this summer. You can view the newly scheduled hangouts on the Google Developers events page. Please RSVP by clicking the “I’ll be there” button if you plan on attending. You can also continue to follow our schedule by subscribing to the Google Ads Developer Office Hours calendar which is also linked on the sidebar to the right of this blog entry.

New for this round, in response to requests, we will be posting the link to the hangout in each of our respective forums. Apparently you guys are extremely interested in coming but sometimes forgetful and wanted an extra email reminder from the forums.

In case you haven’t joined us before, you will need 3 things to join the hangout:

A Google+ account (sign up here)
The Google voice and video plugin installed on your computer
A quiet place to hangout so we can hear you

These hangouts are informal and conversational, which make them a great place to ask questions or give us feedback. If you have questions about our office hours program, reach out to us on the forums.

- Paul Rashidi, DFP API Team

The Docs are Dead. Long Live the Docs!

2012-04-19T04:36:00.003-07:00

Recent visitors to any of the Ads API documentation pages will have noticed their shiny new appearance and a message to let you know the docs have moved to a new platform:

This move is much more than a skin-deep makeover. As we’ve blogged before, the new Google Developers platform is so named to reflect our focus on you, and not just on the tools we provide.

Follow the links below to take a look at the full range of Ads API docs on Google Developers:

We’ll continue to try to improve the Ads API docs on Google Developers while, over time, Google Code returns to its original purpose as an open source project hosting service. Visits to the old Google Code docs will be redirected to the corresponding Google Developers docs throughout 2012, so be sure to update your bookmarks soon.

If you have any questions about these changes please reach out to us through any of the Ads API forums or office hours.

Lesley Burr, Ads Developer Relations Team

AdSense Management API: Working with limits

2012-03-29T08:05:00.000-07:00

If you are an advanced AdSense Management API user, your application may have run into one of the several different limits we have in place. We’ve created a new documentation page to keep track of system limits, but here’s a small description of what they are and what you can do to avoid them.

API Courtesy Limit

This limit refers to the number of requests your project can make via the API in a single day, across all of your users or AdSense accounts. This is set to 10,000 queries per day for all new projects.

If you’re running into the limit, feel free to request more from the “Quotas” page for your project, in the APIs Console. We’ll look at your request and project usage history, then decide an appropriate limit to set in place.

Page size for “list” calls

The various “list” methods in the AdSense Management API are paginated, with a default size of 10,000 entries per page. You can configure this limit yourself in your request with the maxResults parameter, but you can’t set it to any value greater than 10,000.

Reports

For regular, unpaginated reports, the maximum number of rows that the API will return is 50,000. If your report is larger than that, it will be truncated at 50,000 rows.

Pagination in reports should only be used when strictly necessary, as it’s generally only useful to applications running in devices with severe storage constraints. Because of this, paginated reports are limited to 5,000 rows and any attempt to obtain data beyond the 5000th row will return an error.

Let us know in our forum if you have any questions!

- Sérgio Gomes, AdSense API Team

Spring 2012 Office Hours

2012-03-13T09:00:00.000-07:00

Google+ Office Hour Hangouts continue to be a hit across all of the Ads products so we're announcing that we've scheduled new events for the spring season. You can view the newly scheduled hangouts on the Google Developers events page. Please RSVP by clicking the “I’ll be there” button if you plan on attending. You can also continue to follow our schedule by subscribing to the Google Ads Developer Office Hours calendar which is also linked on the sidebar to the right of this blog entry.

In case you haven’t joined us before, you will need 3 things to join the hangout:

A Google+ account (sign up here)
The Google voice and video plugin installed on your computer
A quiet place to hangout so we can hear you

Frequently Asked Questions for the AdSense Management API

2012-03-06T05:35:00.000-08:00

Since launching the AdSense Management API in October last year, we’ve received a number of questions and feedback from you while coding your applications. Today, we’ll address the most frequently asked questions and share some best practices.

How do I authenticate? Do I need to use OAuth?

Right now, the only authentication method we support is OAuth, but don’t let that intimidate you; OAuth 2.0 supports several authentication methods, for web server, client-side and installed applications and devices, which together cover all use cases.

You can find more information on how to authenticate in your favourite client library language in our client library guide or the more generic OAuth 2.0 documentation.

How do I stop my users from having to authorize my application every time they use it?

If you don’t take steps to store your users’ authentication data or set the appropriate flags on your request, the authentication process will run them through a permission-granting dialog similar to the one below every time:

In order to avoid this and improve the experience for users of your web or installed application, you should store their authentication data.

There are two types of token that we need to know about here: access tokens and refresh tokens. Access tokens give you immediate access to a user’s data, and are short-lived, whereas refresh tokens are long-lived, allowing you to generate new access tokens when you need them, even if the user isn’t present.

For installed or web applications we recommend storing both, and using the refresh token to generate a new access token whenever the one you stored expires.

For client-side applications, things should be a little easier, as all it should take is a redirect. The OAuth 2.0 documentation for client-side applications has all the information you need.

For more information on request tokens, you can check the relevant section in the OAuth 2.0 documentation, or the “Persisting authentication data” section in our client library guide if you’re using one of the client libraries.

How often can I run my report queries?

Every application has different needs, so the answer to this question will no doubt depend on what you’re doing. There are, however, a few guidelines we can give you.

First of all, try to collect data on the same frequency that you analyze it. That is, if you’re interested in daily performance, there’s no need for you to collect data more often than once a day, as our reporting can compile that data for you.

On the other hand, if you’re trying to get data as frequently as possible, bear in mind that we cache our report data for 60 seconds. There’s thus no point in running the same report more often than once a minute; the data you get won’t be any fresher, and you’ll just be wasting your request quota.

How do I get my performance data per country / domain?

Most reports are based on a time dimension such as DATE, WEEK or MONTH, which is to say that they’re grouped by that particular dimension.

Not all reports need to be based on a time dimension, however. In fact, a very useful report for those of you with many international visitors is to get a breakdown of visitors per country. In order to get that, just set your start and end dates and choose COUNTRY_CODE or COUNTRY_NAME as the dimension.

You can combine both approaches as well, to get a breakdown per country for every month, for example.

To get some more background on reports and the concepts behind them, check out our Diving into Reports blog post.

What should I do if my question isn’t answered here?

We’ve got a whole bunch of resources for you, from the reference documentation to our client library guide and code examples for several programming languages.

If that doesn’t help, take a look in our forum, and you might find a similar question or get a chance to post your own. You can also join us in a Hangout during our regular office hours. We’ll be around to give you a hand in either case!

- Sérgio Gomes, AdSense API Team

AdSense Management API and Chart Tools week: Thursday

2012-01-12T03:26:00.000-08:00

Thanks for joining us for Chart Tools week on the blog, where we're sharing ways to use Google Chart Tools. In the fourth and last part of this series, we’ll examine how to organize and manage multiple charts that share the same underlying data using dashboards and controls.

Interaction with data

The last request of the CEO is to be able to interact with the data: he wants to filter the line chart and the column chart by expressing a range of page views.

What we need to do now is compose the 2 charts into a Dashboard object, following these steps:

combine the data retrieved from the AdSense Management API into one single table
create the charts
add 1 control, a Number Range Filter for ad requests
create a view on top of the data table
create a Dashboard object and feed it with the view

Create the DataTable

To create a Dashboard, we need the charts to share the same underlying data. For this reason, we will combine the requests for the line and the column chart into a single request:

start date:	2011-01-01
end date:	2011-12-31
dimensions:	MONTH
metrics:	PAGE_VIEWS, AD_REQUESTS, MATCHED_AD_REQUESTS, INDIVIDUAL_AD_IMPRESSIONS
filters:	(none)

The result will be similar to:


result = {
  "kind": "adsense#report",
  "totalMatchedRows": "9",
  "headers": [ {...} ],
  "rows": [
    ["2011-01", "28", "46", "41", "165"],
    ...
    ["2011-11", "2", "3", "3", "3"]
  ],
  "totals": ["", "241", "278", "264", "825"],
  "averages": ["", "26", "30", "29", "91"]
}

Now we can create our DataTable, adding columns for all the metrics:


var data = new google.visualization.arrayToDataTable(
    [['Month', 'PAGE_VIEWS', 'AD_REQUESTS', 'MATCHED_AD_REQUESTS',
        'INDIVIDUAL_AD_IMPRESSIONS']].concat(resp.rows));

Create the charts

The next step is to create the wrappers:


var lineChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'LineChart',
  options: {'title': 'Ad requests trend - Year 2011'},
  containerId: 'line_chart_div',
  view: {'columns': [0, 2]}
});

var columnChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'ColumnChart',
  options: {'title': 'Performances per month - Year 2011'},
  containerId: 'column_chart_div',
  view: {'columns': [0, 1, 3, 4]}
});

There are two important differences between creating wrappers for a dashboard and wrappers for standalone charts:

For each chart in a dashboard, we use the view option to select which columns are relevant for the chart (remember, all the data for the two charts is in the same table now)
We don’t draw the charts now, we’ll draw the entire dashboard later

Time to create the control!

Create the control

Let’s create the control wrapper for our number range filter for the ad requests:


var adRequestsSlider = new google.visualization.ControlWrapper({
  'controlType': 'NumberRangeFilter',
  'containerId': 'ad_requests_filter_div',
  'options': {
    'filterColumnLabel': 'Ad requests',
  }
});

The option container_id specifies the element of the page where the filter will be drawn into, while filterColumnLabel tells the filter which column to target.

Create the DataView

Remember that we need a DataView to convert our string field to numeric fields:


var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Page views'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 2))}, type:'number', label:'Ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 3))}, type:'number', label:'Matched ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 4))}, type:'number', label:'Individual ad impressions'},
]);

Create the dashboard

Creating the Dashboard, binding the control to the charts and drawing the dashboard is as easy as the following:


var dashboard = new google.visualization.Dashboard(
    document.getElementById('dashboard_div'))
    .bind(adRequestsSlider, [lineChartWrapper, columnChartWrapper])
    .draw(view);

dashboard_div is the element of the page that acts as container for the Dashboard:


<div id="dashboard_div">
  <!--Divs that will hold each control-->
  <div id="ad_requests_filter_div"></div>
  <!--Divs that will hold each chart-->
  <div id="line_chart_div"></div>
  <div id="column_chart_div"></div>
</div>

And it’s done! Our Dashboard is ready. Check the live example and the source code for today!

Mission Accomplished!

Well done -- our dashboard is ready and the CEO is happy with his new tool! Now you can relax and play foosball!

If you want to know more about our APIs, check the documentation pages:

And if you have any additional questions, don’t hesitate to engage with us in our forums:

You can also join us in one of our AdSense API Office Hours on Google+ Hangouts. Check the schedule for the upcoming Office Hours in our Google Ads Developer Blog.

Lastly, a public service announcement: thanks Riccardo for your help!

- Silvano Luciani, AdSense API Team

AdSense Management API and Chart Tools week: Wednesday

2012-01-11T03:24:00.000-08:00

Welcome back to Chart Tools week here on the blog, where we're continuing our overview of generating charts for your AdSense reporting with Google Chart Tools. Today we’ll examine how to generate two other types of charts: a table chart and a geo chart.

Table chart

The third chart requested by our CEO is a table chart. The table chart will contain the number of ad requests, the number of matched ad requests, and the number of individual ad impressions broken down by ad client ID.

Our request will have these parameters:

start date:	2011-01-01
end date:	2011-12-31
dimensions:	AD_CLIENT_ID
metrics:	AD_REQUESTS, MATCHED_AD_REQUESTS, INDIVIDUAL_AD_IMPRESSIONS
filters:	(none)

And the result will be similar to:


result = {
  "kind": "adsense#report",
  "totalMatchedRows": "4",
  "headers": [ {...} ],
  "rows": [
    ["ca-afdo-pub-1234567890123456", "59", "55", "232"],
    ...
    ["partner-mb-pub-1234567890123456", "1", "0", "0"]
  ],
  "totals": ["", "278", "264", "825"],
  "averages": ["", "69", "66", "206"]
}

As usual, let’s create a DataTable and a DataView to perform transformations on columns:


var data = new google.visualization.arrayToDataTable([['Ad client id',
    'AD_REQUESTS', 'MATCHED_AD_REQUESTS', 'INDIVIDUAL_AD_IMPRESSIONS']]
    .concat(resp.rows));
var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 2))}, type:'number', label:'Matched ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 3))}, type:'number', label:'Individual ad impressions'}
]);

Finally, let’s draw the table chart. Note that there is no title for a table chart: if you need one, you’ll have to add it in a different element.


var tableWrapper = new google.visualization.ChartWrapper({
  chartType: 'Table',
  dataTable: view,
  containerId: 'vis_div'
});
tableWrapper.draw();

The table chart for our CEO is ready, and it can be sorted and paged.

Check the live example and the source code for today!

Geo chart

Finally, the last chart requested from our CEO: a geo chart. The geo chart will show the number of page views for the year broken down by country name.

Our request will have these parameters:

start date:	2011-01-01
end date:	2011-12-31
dimensions:	COUNTRY_NAME
metrics:	PAGE_VIEWS
filters:	(none)

And the result will be similar to:


result = {
  "kind": "adsense#report",
  "totalMatchedRows": "9",
  "headers": [ {...} ],
  "rows": [
    ["Canada", "1"],
    ...
    ["United States", "52"]
  ],
  "totals": ["", "241"],
  "averages": ["", "26"],
}

DataTable and DataView creation step:


var data = new google.visualization.arrayToDataTable(
          [['Country', 'Page Views']].concat(resp.rows));

var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Page views'}
]);

Now we can draw the geo chart. For the geo chart there is no title:


var geoChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'GeoChart',
  dataTable: view,
  containerId: 'vis_div'
});
geoChartWrapper.draw();

Et voilà! We have a map of the world with colors and values assigned to specific countries representing the page views from the countries for the current year.

Check the live example and the source code for today.

Time to play!

Eager to try to see what you can do combining these two powerful Google APIs?

You can start immediately using our Google API Explorer and our Google Visualization PlayGround. You can use the Explorer to query our AdSense Management API, and then use the results inside the code on the Visualization PlayGround to generate a chart.

In the next and final part of this series, we will see how to assemble multiple charts into dashboards and enrich them with interactive controls to manipulate the data they display.

Meanwhile, feel free to post any questions related to Google Chart Tools in Google Visualization API forum, or visit our AdSense Management API forum to ask general questions.

- Silvano Luciani, AdSense API Team

AdSense Management API and Chart Tools week: Tuesday

2012-01-10T03:31:00.000-08:00

It's Chart Tools week here on the blog, and so we'll be showing you in a 4-part series how to easily generate charts for your AdSense reporting using Google Chart Tools. In today’s second post we’ll examine how to generate another type of chart: a column chart.

Column chart

The second item required by our CEO is a column chart. The column chart will show the number of page views, ad requests, matched ad requests and individual ad impressions for each month of the current year.

Our request becomes:

start date:	2011-01-01
end date:	2011-12-31
dimensions:	MONTH
metrics:	PAGE_VIEWS, AD_REQUESTS, MATCHED_AD_REQUESTS, INDIVIDUAL_AD_IMPRESSIONS
filters:	(none)

Now the result will be similar to:


result = {
 "kind": "adsense#report",
 "totalMatchedRows": "9",
 "headers": [ {...{ ],
 "rows": [
   ["2011-01", "28", "46", "41", "165"],
   ...
   ["2011-11", "2", "3", "3", "3"]
 ],
 "totals": ["", "241", "278", "264", "825"],
 "averages": ["", "26", "30", "29", "91"]
}

We create the DataTable object, adding the columns for our dimensions:


// Create the data table.
var data = new google.visualization.arrayToDataTable(
    [['Month', 'PAGE_VIEWS', 'AD_REQUESTS', 'MATCHED_AD_REQUESTS',
    'INDIVIDUAL_AD_IMPRESSIONS']].concat(result.rows));

Once again we use a DataView to convert the string values to numbers:


var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Page views'},
  ...
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 4))}, type:'number', label:'Individual ad impressions'}
]);

And finally, let’s create a wrapper for the column chart and draw it:


var columnChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'ColumnChart',
  dataTable: view,
  options: {'title': 'Performances - Year 2011'},
  containerId: 'vis_div'
});
columnChartWrapper.draw();

Another piece is done: a column chart of our performances that is also displaying tips when hovering over bars. Check the live example and the source code for today!

Time to play!

Eager to try to see what you can do combining these two powerful Google APIs?

You can start immediately by using our Google API Explorer and our Google Visualization PlayGround. You can use the Explorer to query our Management API, and then use the results inside the code on the Visualization PlayGround to generate a chart.

Stay tuned for our next post this week, where we’ll show you how to generate other two charts, a table chart and a geo chart.

If you have any questions related to the AdSense Management API, come to our forum; alternatively, visit the Google Visualization API forum if you're looking for support on Chart Tools.

- Silvano Luciani, AdSense API Team

AdSense Management API and Chart Tools week: Monday

2012-01-09T02:51:00.000-08:00

It’s Monday morning, and you’re sitting in front of your computer, ready for a relaxed start of the week. But wait!

You’ve received an email from your CEO. He wants you to add AdSense reporting to his dashboard, and he wants to see the following:

a line chart showing the number of ad requests for the current year, broken down by month
a column chart showing the number of page views, ad requests, matched ad requests and individual ad impressions for the current year, broken down by month
a table showing the number of ad requests, matched ad requests and individual ad impressions for the current year, broken down by ad client id
a geo chart showing the number of page views for the current year broken down by country

He also requires the ability to interact with data: he wants to refine the visualization of the line and column charts filtering by lowest and highest number of ad requests shown in the charts.

It might look like a week of hard work is coming, but don’t worry! It’s Chart Tools week here on the AdSense Management API blog, and we’re going to show you how to easily and rapidly create the dashboard using the Google AdSense Management API and the Google Chart Tools. In the first part of this series, we’ll examine how to generate a line chart.

Background

You can access the AdSense Management API from different programming languages using the appropriate Google APIs Client. Check our documentation for AdSense Management API specific information.

The Google Chart Tools API are accessible using Javascript, check this ‘Hello Charts’ example for a quick start lesson on the API.

Line chart

The CEO wants a line chart showing the number of ad requests for the current year, broken down by month.

We will send a request to the AdSense Management API with the following parameters:

start date:	2011-01-01
end date:	2011-12-31
dimensions:	MONTH
metrics:	AD_REQUESTS

And the result will be a json array similar to the following:

result = {
  "kind": "adsense#report",
  "totalMatchedRows": "9",
  "headers": [ {...} ],
  "rows": [
    ["2011-01", "46"],
    ...
    ["2011-11", "3"]
  ],
  "totals": ["", "278"],
  "averages": ["", "30"]
}

To use the Chart API we first need to create a DataTable object representing the result of our request:

// Create the data table.
var data = new google.visualization.arrayToDataTable(
    [['Month', 'AD_REQUESTS']].concat(result.rows));

The AdSense Management API is returning the value for AD_REQUESTS as a string, but we need a numeric value for our charts. To achieve this, we are going to build a Data View on top of our Data Table and convert the string column to a number column:

var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Ad requests'}
]);

Our DataView will use the first column of the DataTable as it is, but will generate on the fly a second column composed of numeric values by calling a function of our choice that implements the conversion.

Finally we can draw the chart using a chart wrapper and passing our DataView to the wrapper. Make sure to define an element with id equal to the containerId parameter, as this is where the chart will be drawn.

var lineChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'LineChart',
  dataTable: view,
  options: {'title': 'Ad requests trend - Year 2011'},
  containerId: 'vis_div'
});
lineChartWrapper.draw();

The line chart for the CEO is ready, and it’s also displaying tips when hovering over points. Check the live example and the source code for today!

Time to play!

Eager to try to see what you can do combining these two powerful Google APIs?

You can start immediately by using our Google API Explorer and our Google Visualization PlayGround. You can use the Explorer to query our Management API, and then use the results inside the code on the Visualization PlayGround to generate a chart.

In the next post of this series, we’ll look at how to generate a column chart.

Have questions in the meantime?

If they’re related to the AdSense Management API, come to our forum and ask!
If they’re related to the Google Chart Tools, visit the Google Visualization API forum and ask!

- Silvano Luciani, AdSense API Team