English | Site Directory

Documentation for the requested version is not available.Documentation for the requested diff is not available.

Introduction

Link to this version

Contents

The AdSense API enables developers to programmatically generate ad code snippets for insertion into a publisher's web pages. The API can also filter out unwanted ads and generate detailed reports about clickthrough performance.

This document assumes that you are familiar with AdSense and the functionality available on the AdSense website. (The API provides a subset of that functionality.) This document also assumes familiarity with web services in general, and with the programming language you will be using.

To access AdSense accounts programmatically, you build web service clients that connect to one or more of the AdSense API web services. The services are listed below. If you are not already familiar with these services, you can learn about them by creating and using an AdSense account at Google AdSense. This website has user controls for interactively setting the various fields, properties and operations, with immediate visual previews of the ads and search boxes you are producing.

Overview of AdSense API Web Services

The core messaging technology for the AdSense API is Simple Object Access Protocol (SOAP), which is an XML- and HTTP-based protocol with wide support in the industry. The AdSense API uses document/literal style SOAP 1.1.

To access AdSense accounts programmatically, you build web service clients that use the AdSense API. Typically, your web service client application would use a toolkit that knows how to connect to and interact with web services. (See the section About SOAP for more discussion of toolkits.)

The services currently offered are:

  • AccountService
    The Account Service lets you create and modify AdSense accounts, including:
    • Create a new AdSense account
    • Associate with an existing AdSense account
    • Get and modify various publisher account settings
  • AdSenseForContentService
    The AdSense For Content (AFC) Service lets you generate ad code snippets to insert into your web pages. You can control the dimensions, color, and whether the ad contains only text, images or both. When someone clicks on an ad, Google credits you a payment. This service lets you:
    • Generate ad code snippet based on ad style, layout, and unit type
    • Get and modify ad styles (color)
    • Get ad layouts (size)
    • Get ad unit type (text, image or both)
    • Get channels (get all, get active, get inactive)
  • AdSenseForSearchService
    The AdSense For Search (AFS) Service lets you add Google search to a publisher's website. When an end user performs a search, ads are displayed — when a user clicks through, Google credits a payment. It lets you:
    • Generate a code snippet for a Google search box
    • Specify full web search or restrict it to one of several domains
    • Specify several properties, including locale, SafeSearch, search box style and channel
  • SiteFilterService
    The Site Filter Service lets you add, remove and view filters that will screen out ads from specific URLs, such as competitors. You can create and manage a list of filters for restricting websites.
  • ChannelService
    The Channel Service lets you create, list and modify channels for detailed reports for viewing on the AdSense website. By assigning a channel to any combination of pages, publishers can track a variety of performance metrics across their sites. The Report Service can be used to view these metrics.
  • ReportService
    The Report Service lets you generate reports on AdSense accounts. It can generate reports for AdSense for Content, AdSense for Search, and Referral services. The reports can:
    • Filter data to a specific date range
    • Specify any channel, unit (such as Page, Ad, or TargetingType) or referral product (AdSense or Firefox)
    • Group the data, such as by date, channel or referral product

AdSenseForContentService, SiteFilterService and ChannelService work together to provide the AdSense For Content Service.

In some services, where a single operation is provided, a matching batch operation is also provided. For example, AdSenseForContentService provides the saveAdStyle operation for saving a single ad style and saveAdStyles for saving a batch of ad styles. Calling a batch operation is more efficient than multiple calls to a single operation; therefore, you are encouraged to use the batch operations wherever possible.

Each publisher is identified by a unique identification (ID) string. When you create an account for a publisher, this publisher ID is returned as the value of the id field of SyndicationService_Data. This ID is also known as the client ID or synServiceId. You must pass in this ID as the synServiceId parameter when performing certain operations, such as generating ad code snippets, adding or deleting ad styles, and adding or removing site filters.

Back to Top

Terminology

Publisher (or User)
An individual or business that owns and manages content on the web and would like to earn revenue using AdSense.
Developer
An individual or business that provides a client application that lets publishers create and manage AdSense accounts.
Client Application
An application that publishers can use to create and manage AdSense accounts through the AdSense API.

In the API reference, brackets [] appended to a type (such as AdLayout[]) indicate an unbounded list.

Back to Top

About AdSense

For more information about Google AdSense, here are some helpful links:

Back to Top

Signing Up

Before using the AdSense API, you need to sign up using the AdSense API information form. This process will give you a test developer acccount on the sandbox.

To use AdSense API, your site needs at least one hundred thousand (100,000) page views per day. See Eligibililty for more information. If you do not qualify, you can still use Google AdSense to monetize your site.

Back to Top

Getting Started

To use the AdSense API, write a client program in the programming language or your choice. We have tested Java, Perl, PHP, Python and C#, and have sample code for those languages. Write your client program to send a request to one of the AdSense web services, such as the AccountService or AdSenseForContentService. The relevant service will process the request and send back a response, which your client program needs to parse.

Tip: Use the AdSense API sandbox to test and debug your AdSense API client application. This feature replicates the live website and lets you simulate creating AdSense accounts for new or existing publishers, associate those accounts with their own developer account, and then test operations on that account.

Since the AdSense API runs as a web service, you don't need to install the AdSense API. The only software you need to install to use the AdSense API is the software for the programming language and toolkit that you will be using to write your client programs. For example, if you intend to write your client programs in Java, you will need to install the Java Development Kit and also a SOAP toolkit such as Axis. See the section Soap Toolkits for a list of possible toolkits for various languages.

The operations provided by a web service are defined in a WSDL (Web Services Definition Language) file which is posted on the web service's website. To connect to a web service, you need to know the URL for the WSDL. For all the AdSense API services, the URL for the WSDL has the following form:

https://www.google.com/api/adsense/vN/SERVICE_NAME?wsdl

For example:

https://www.google.com/api/adsense/v2/AccountService?wsdl

Links to WSDLs are listed in the API Reference at the end of the description for each service.

The exact details of how the client program connects to the WSDL depends on the language and the toolkit being used. Typically, the toolkit has a function for connecting to a service. You simply call the relevant operation and pass in the URL for the WSDL. For example, in Perl you would do the following to connect to AccountService:

# Specify the WSDL
$url = "http://www.google.com/api/adsense/v2/AccountService?WSDL";

# Set up the connection to the service.
my $service = SOAP::Lite->service($url);

See the code samples in the Sample Code section for examples of how to connect to the AdSense API Web Services in the selected programming languages.

After establishing a connection to the WSDL, the client program can send requests to the web service to perform any of the operations supported by the web service. For example, after connecting to the AccountService, a client program could send an createAccount request to create a new account.

See the Reference section for detailed API information about each service.

Back to t op

Setting Up Publisher Accounts

Setting Up A Publisher's Account

Before performing operations on behalf of a publisher, you must associate yourself with that publisher. How you do this depends on whether the publisher already has an AdSense account.

New AdSense Publisher

  1. Have publisher accept terms and conditions - Before creating an account for them, it is necessary for you to first show them the AdSense terms and conditions and get their acceptance before creating the account. You can find these documents at https://www.google.com/adsense/api-terms?hl=lang, where lang is the "User's Preferred Locale" locale code. For example: AdSense Online Standard Terms and Conditions (English).
  2. Create a new account - You then create a new AdSense account for them (which includes creating an association with them). You are returned a client ID unique to the publisher, which should be used for all further operations on the publisher's account. An email is automatically sent to the publisher, which includes a link for them to verify their email address, provide their contact information (address and telephone number) and set their password. Once we receive this information, the publisher's new account is processed for approval.
  3. Generate and insert ad code - Without waiting for the publisher to reply to the email, and before the new account receives approval, you can call generateAdCode to get HTML code snippets to insert into the publisher's web pages. These snippets are rendered as ads in the style you have chosen or or as public service announcements. Public service announcements are served immediately, until the publisher's account is approved, then real ads are served.

Existing AdSense Publisher

  1. Associate existing account - Create an association with the publisher's existing account. When the association is created, you are returned a client ID unique to the publisher, which should be used for all further operations on the publisher's account. An email is automatically sent to the publisher asking them to confirm they want this association. You can make only a limited set of calls on behalf of the publisher until the publisher confirms the association. After the publisher accepts the association, you can leverage all services of the API to manage the publisher's account.
  2. Generate and insert ad code - Without waiting for the publisher to accept the association, you can call generateAdCode to get HTML code snippets to insert into the publisher's web pages. These snippets are rendered as ads in the style you have chosen or as public service announcements. Public service announcements are served immediately. Real ads are served within hours if the publisher's AdSense account has been approved.

When creating an association, both the postalCode and phone hints must be present in the publisher's AdSense account for the association to succeed — if either hint is missing, you may need to ask them to log into the AdSense front end and update it before proceeding with verification. You may validate the phone and postalCode hints if you wish. The phone hint, for example, is just the last 5 digits of the phone number (excluding any punctuation).

Note: AdSense API does not support There is no support for a developer to manage their own AdSense account via the AdSense API.

Allowed Operations Prior to Active Status

A developer can perform the following operations on a publisher's account before the publisher grants access (that is, prior to or while the association status is «pendingEmailVerification»).

Service Operation
AccountService createAccount
associateAccount
getAssociationStatus
getAllSyndicationServices
getSyndicationService
getUsersPreferredLocale
getWebsiteLocale
AdSenseForContentService generateAdCode
AdSenseForSearchService generateSearchBoxCode

If an operation attempted by the developer is not permitted by the status of the developer-publisher association, error code 113 (not associated) error is returned.

Back to top

Setting Request Headers

All requests sent to the AdSense API Web Services must include the following header elements:

  • developer_email — the AdSense login email of the developer.
  • developer_password — the AdSense login password of the developer.

The following header elements are optional:

  • client_id — (optional) identification of the publisher's AdSense account being accessed. This client ID is required in most cases except when creating an AdSense account for a publisher or when creating an association with an existing AdSense publisher.
  • display_locale (optional) represents the display locale in which the publisher wants the error messages or other locale-specific data to be returned as part of the SOAP response. The display locale defaults to Locale.US if the header is absent. This locale can be different from the locale in which correspondence with the publisher (that is, emails) would be written. Must be a Google supported locale.

The exact details of how the client program specifies a request header depends on the programming language and the toolkit being used, but usually the toolkit has a function for setting a header value. For examples of setting request headers in various toolkits, see the sample code.

For an example of XML code for setting a request header, see the section SOAP Request Example further down this page.

Other special debugging request header elements are available only in the sandbox.

Back to Top

XML Namespaces

All operations and complex types defined in the AdSense API web services are associated with the following XML namespace:

http://www.google.com/api/adsense/vN <!-- where N is the version number -->

Lowercase types shown throughout this guide (for fields, parameters, and return types) are XML Schema datatypes and are associated with the following namespace:

http://www.w3.org/2001/XMLSchema
Back to Top

About SOAP

The AdSense API Web Services use document-style versions of the Simple Object Access Protocol (SOAP). A client program sends a SOAP request; the web service processes the request and sends a response. Both the request and the response are packaged as XML messages that have a header and a body.

For the AdSense API, all API messages are sent via HTTPS requests. The XML for the SOAP request is sent as an HTTP POST request with a special SOAPAction header; the response is sent back as the response to the POST. All AdSense API calls are encrypted with SSL (that is, as HTTPS) to protect the privacy of your data.

The header describes meta data about the message. In the case of the AdSense API Web Services, the header must include the developer's login email and password. The body of the message specifies the requested operation (such as createAccount) along with any applicable parameters (such as the website URL for the new account).

The requests that a web service can process are defined in a Web Services Definition Language (WSDL) file in XML. The WSDL file describes the operations that the web service can perform, the required parameters for each operation, and the response for each operation. It also includes definitions of the SOAP header elements and the faults thrown in the case of an error.

SOAP Toolkits

Typically, to use the AdSense API Web Services, you would download a toolkit that knows how to interpret WSDL files and how to encode and decode XML request and response messages. When an AdSense API web service receives a request, it sends back the response as an XML message. The web service toolkits know how to parse the response and return a data structure or object back to the caller, as appropriate for the language.

The toolkits help generate stubs that know how to locate the AdSense API service. You would typically generate stubs for each service using the toolkit and then write your client application against the stubs.

The exact toolkit you would use depends on the language you are using. Some toolkits do more for you or work better than others. Some take care of all the XML for you; others require you to write some XML yourself. The commonly used toolkits include the following — for specific information about which version to use, where to download, how to install and use, see the Sample Code.

  • Java: Apache Axis
  • Perl: SOAP::Lite
  • PHP: NuSOAP Toolkit
  • Python: fpconst
  • C#: Visual Studio

Note: The AdSense API uses document/literal style SOAP, not rpc/encoded style. Some toolkits work differently for document-style web services than for rpc-style.

If you use a SOAP toolkit, you should rarely have to write XML code to use the AdSense API Web Services, since the toolkits handle the XML generation. Some toolkits, however, may require you to hand-code some of the XML yourself. For example, nusoap.php, requires you to write the XML code for input parameters.

It can sometimes be helpful to capture the XML request and response messages for debugging purposes. See How do I view the XML code generated by the request and response?.

To learn more about SOAP, see the SOAP Tutorial at W3Schools.

Back to Top

Examples

SOAP Request Example

The following code is a SOAP request to createAdSenseAccount in AccountService. The header sets the developer_email, developer_password and display_locale. The body of the message is a request to create an AdSense account, supply the necessary parameters.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Header>
     <ns1:developer_email
                  soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
                  soapenv:mustUnderstand="0"
                  xmlns:ns1="http://www.google.com/api/adsense/v2">
           testuser1+api@google.com
     </ns1:developer_email>
     <ns2:developer_password
                  soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
                  soapenv:mustUnderstand="0"
                  xmlns:ns2="http://www.google.com/api/adsense/v2">
           TEST123
     </ns2:developer_password>
     <ns3:display_locale
                  soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next"
                  soapenv:mustUnderstand="0"
                  xmlns:ns3="http://www.google.com/api/adsense/v2">
           en_US
     </ns3:display_locale>
  </soapenv:Header>

  <soapenv:Body>
     <createAdSenseAccount xmlns="http://www.google.com/api/adsense/v2">
        <loginEmail>johndoe1@example.com</loginEmail>
        <entityType>Business</entityType>
        <websiteUrl>www.example.com</websiteUrl>
        <websiteLocale>en</websiteLocale>
        <usersPreferredLocale>en_US</usersPreferredLocale>
        <emailPromotionPreferences>true</emailPromotionPreferences>
        <synServiceTypes>ContentAds</synServiceTypes>
      <hasAcceptedTCs>true</hasAcceptedTCs>
    </createAdSenseAccount>
  </soapenv:Body>
</soapenv:Envelope>

SOAP Response Example

The following code is a SOAP response to the previous createAdSenseAccount request. The body includes the client ID "ca-pub-9644922955003912" and syndication service type "ContentAds".

<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <createAdSenseAccountResponse xmlns="http://www.google.com/api/adsense/v2">
      <createAdSenseAccountReturn>
        <id>ca-pub-9644922955003912</id>
        <type>ContentAds</type>
      </createAdSenseAccountReturn>
    </createAdSenseAccountResponse>
  </soapenv:Body>
</soapenv:Envelope>