AdMob API Documentation

Table of Contents

Getting Started
API Requests
Parameters
Client Keys
Authentication
Rate Limiting
API Responses
Format
Pagination
Example
Errors
Error Codes
Warnings
How are warnings different from errors?
Warning Codes
Auth Login v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Auth Logout v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Site Search v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Site Stats v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Ad Search v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Ad Stats v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Ad Group Search v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Ad Group Stats v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Campaign Search v2
Endpoint
HTTP Method
Parameters
Returns
Errors
Campaign Stats v2
Endpoint
HTTP Method
Parameters
Returns
Errors


API
The AdMob API allows you to access the campaign, sites and applications data in your
AdMob account with a secure programmatic interface. You can build custom applications
using the AdMob API to help better manage your mobile business.
Getting Started
If you want to use the AdMob API you need 4 things:

1.
An API client key (e.g. kd4a316bf82c1eb30b2403000a556ef1). You can create an API
client key at http://www.admob.com/api.
2.
AdMob login credentials (email and password) for your account.
3.
Any site ids or ad ids (e.g. a22222222222222) that you want to get stats for. If you don't
know the ids of your sites or ads, use the corresponding search endpoint.
4.
An API client. A sample PHP client is provided, or you can write your own using the
documentation.
API Requests
Parameters
Each AdMob API endpoint requires either a GET or POST request. Endpoints that do not
modify state require a GET request.

GET /v2/site/stats?site_id=a22222222222222&start_date=2010-01-01&end_date=2010-02-01
HTTP/1.1
Host: api.admob.com

Endpoints that modify state require a POST request.

POST /v2/site/stats HTTP/1.1
Host: api.admob.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 65

site_id=a22222222222222&start_date=2010-01-01&end_date=2010-02-01

Some parameters accept arrays of values. For example, the following notation can be used
to pass multiple site ids to the site stats endpoint.

site_id[]=a11111111111111&site_id[]=a22222222222222&site_id[]=a33333333333333

Some parameters accept associative arrays of values. For example, the following notation
can be used to order stats by impressions descending.

order_by[impressions]=desc
Client Keys
All AdMob API endpoints require the client_key parameter which identifies the API client
making the request. Client keys can be created at http://www.admob.com/api/. If you are
the author of multiple clients, you should create a different client key for each of your
clients.
Authentication
If an endpoint requires authentication it means that the API client must first obtain a token.
A token grants an API client permission to access data on behalf of an AdMob user for a
limited amount of time.
1.
API client prompts the AdMob user for their AdMob login credentials (email and
password).
2.
API client exchanges these credentials for a token using the HTTPS login endpoint. Any
previous tokens issued to this API client for this user will be invalidated.
3.
API client uses the token to make requests on behalf of the user.

If the AdMob API returns a token_invalid error, it means the API client needs to obtain a
new token to continue making requests on behalf of the AdMob user. A token may
become invalid for a few reasons.

Tokens automatically expire after a certain amount of time.

A token will expire if the user or API client uses the AdMob API logout endpoint.

A token will expire if a new token is requested for the same user by the same API client
using the AdMob API login endpoint.

Recommendations

API clients should not store AdMob login credentials for a user unless the user
specifically requests the API client to do so.

The API client should provide a way for the user to log out using the AdMob API logout
endpoint.

When possible, the API client should call the AdMob API logout endpoint when the user
exits the client.
Rate Limiting
The number of requests that a client can make is subject to a rate limit. This rate limit may
change over time as we learn more about how the API is used. If a single client or user
exceeds a rate limit then subsequent requests will return with an error for a short period of
time. API clients should wait at least 1 second before retrying a request that was rate
limited.

{
"errors": [
{
"code": "rate_limit_exceeded",
"msg": "You have made too many requests in a short period of
time."
}
],
"warnings": [
],
"data": null,
"page": {
"current": 1,
"total": 1
}
}
API Responses
Format
The AdMob API always returns a HTTP 200 with a JSON (http://json.org) encoded body.
For example:
{
"errors": [
],
"warnings": [
],
"data": null,
"page": {
"current": 1,
"total": 1
}
}

Each response contains the following elements:
errors
Array of errors that occurred. If the error array is empty then the request was successful.
If the error array is not empty it means that the API was unable to return the requested
data.
warnings
Array of warnings that occurred. If a warning occurs it means the API was able to
complete the request successfully but there is some condition or information that might
need to be handled by the developer of the API client.
data
The data returned by the API endpoint. The type of the data depends on the endpoint
(flat array, associative array, null, etc.). If an error occurs, the data value should be
ignored.
page.current
The current page of data returned by the API.
page.total
The total number of data pages available. If this number is greater than 1, additional
requests are necessary to get all of the data that matched the query.
Pagination
There is a limit to the amount of data that will be returned in one API call. Currently this
limit is 100 items but it could change in the future. If you request more than this limit, the
data will be split into multiple pages and the first page will be returned by default. You can
retrieve the remaining pages of data by repeating the request with the page parameter.
Example
Consider a fictional endpoint that has a page limit of 5 items and you request 8 items. On
the first request the response might look like this:
{
"errors": [
],
"warnings": [
],
"data": [
{
"name": "row1"
},
{
"name": "row2"
},
{
"name": "row3"
},
{
"name": "row4"
},
{
"name": "row5"
}
],
"page": {
"current": 1,
"total": 2
}
}

The total number of pages is 2, so a second request is necessary to get the remaining 3
items. To request the second page, the first request is repeated with the additional parameter
page=2. The second response might look like this:
{
"errors": [
],
"warnings": [
],
"data": [
{
"name": "row6"
},
{
"name": "row7"
},
{
"name": "row8"
}
],
"page": {
"current": 2,
"total": 2
}
}
Errors
If an error occurs, it means that the API was unable to return the data that you requested
and the response will contain a non-empty errors array. For example:
{
"errors": [
{
"code": "required_parameter_missing",
"msg": "site_id is required"
},
{
"code": "required_parameter_missing",
"msg": "start_date is required"
}
],
"warnings": [
],
"data": null,
"page": {
"current": 1,
"total": 1
}
}

An error object contains two parts:
code
A constant error string that represents the error. The API client should use this field
to determine how to handle the error.
msg
A human readable message that may provide additional information to the end user
or developer about the error that occurred. The API client should not rely on the
contents of the error message because error messages can be added or changed
without notice.

If the error array is empty then the request was successful:
{
"errors": [
],
"warnings": [
],
"data": null,
"page": {
"current": 1,
"total": 1
}
}
Error Codes
There are a standard set of error codes that AdMob API endpoints can return:
Error Code Meaning Recommendation
api_downtime
The API is temporarily
disabled for maintenance.
Notify user to try again later. When
possible, the error message will
contain information on when AdMob
expects the maintenance to be
completed.
endpoint_deprecated
The endpoint was removed
from the API due to some
severe performance or
security concern. AdMob's
goal is to never deprecate
an endpoint unless absolutely
necessary.
The API client should notify the
user that the feature is no longer
available and optionally prompt the
user to check to see if there is a
new version of the API client. The
API client developer should provide
an update to their client that does
not use the deprecated endpoint.
endpoint_invalid
Endpoint does not exist (and
never did exist).
Check for typos in your API client.
internal_server_erro
r
Something bad happened that
we need to fix.
Developers who encounter this
error may submit a bug report to
api@admob.com to aid us in fixing
the problem.
rate_limit_exceeded
The request was blocked
because the API client or user
made too many requests in a
short period of time.
The API client should wait at least 1
second before retrying the request
on behalf of the user.
request_invalid
The request is malformed in
some way. Examples include
using HTTP when HTTPS is
required, or errors that affect
multiple parameters such as
passing a start date that is
after the end date.
Display message to the user.
*_required
A required parameter was Prompt the user to input
missing from the request. The
asterisk (*) will be the name
of the missing parameter (e.g.
site_id_required).
a value for the parameter
unless it is a authentication
parameter that is managed by
the client (client_key_required,
token_required, etc.)
*_invalid
This error happens when
the value for a parameter
is improperly formatted
or not valid. The asterisk
(*) will be the name of the
invalid parameter (e.g.
site_id_invalid).
Prompt the user to fix the value
for the parameter unless it is
a authentication parameter
that is managed by the client
(client_key_invalid, token_invalid,
etc.)
Warnings
If a warning occurs, it means that the API was able to complete the request as expected but
there is some condition or information that might need to be handled by the developer of
the API client. If a warning occurs then the response will contain a non-empty array of
warning objects.

{
"errors": [
],
"warnings": [
{
"code": "endpoint_deprecated",
"msg": "This endpoint was deprecated on 2010-01-01. Please use
the XXX endpoint instead
}
],
"data": null,
"page": {
"current": 1,
"total": 1
}
How are warnings different from errors?

An error should be handled synchronously by the API client.

Warnings should be logged in a location that can be reviewed asynchronously by the

API client developer.
Warning Codes
Warning Code Meaning
api_downtime
The API has downtime scheduled for some
point in the future.
client_update_available
The API client you are using is out of date.
This warning will only happen if you are using
the user-agent of the sample API client code
provided by AdMob.
endpoint_deprecated
The endpoint will be removed at some point
in the future. API clients should stop using
this endpoint as soon as possible.

Auth Login v2
Endpoint
https://api.admob.com/v2/auth/login
HTTP Method
POST
Parameters
Name Type Example Note
client_key
Required client_key=k4004829c5899ba9
d231df3604b8ba45
Click here to learn more about
client keys
email
Required email=example@admob.com AdMob login email
password
Required password=averybadpassword For AdMob accounts that are
linked to a Google Account,
this is the API password that
you can find on the Account
Information
(http://www.admob.com/
my_account/account_info)
page. For unlinked AdMob
accounts, this is the
password you use to login to
www.admob.com.
Returns
Returns a token on success.

{
"errors": [
],
"warnings": [
],
"data": {
"token": "ta98585435afabcf26319e2038a09f40"
},
"page": {
"current": 1,
"total": 1
}
}
Errors
This endpoint may return any standard error code documented here.
Auth Logout v2
Endpoint
https://api.admob.com/v2/auth/logout
HTTP Method
POST
Parameters
Name Type Example Note
client_key
Required client_key=k4004829
c5899ba9d231df3604
b8ba45
Click here to learn
more about client
keys
token
Required token=ta98585435afa
bcf26319e2038a09f4
Token to destroy
Returns
Returns nothing on success.
{
"errors": [
],
"warnings": [
],
"data": null,
"page": {
"current": 1,
"total": 1
}
}
Errors
This endpoint may return any standard error code documented here.
Site Search v2
Endpoint
http://api.admob.com/v2/site/search
HTTP Method
GET
Parameters
Name Type Example Note
client_key
Required client_key=k4004829c58
99ba9d231df3604b8ba45
Click here to learn more about
client keys
token
Required token=ta98585435afabcf
26319e2038a09f40
Click here to learn more about
authentication
site_id
Optional site_id=a1111111111111
1
site_id[]
=a22222222222222&site
_id[]=a33333333333333
Search for sites with these ids

include_deleted
Optional include_deleted=1 If this parameter is specified then
deleted sites will be included in
the results. This is useful if you
want to get stats for sites that
have been deleted.


Returns
Returns an array of sites that match all search parameters and are owned by the authenticated
user. If no search parameters are passed then all of the authenticated user's sites will be
returned.
{
"errors": [
],
"warnings": [
],
"data":[
{
"id": "a11111111111111",
"name": "AdMob WWW",
"url": "http://www.admob.com",
"description": "test AdMob site"
},
{
"id": "a22222222222222",
"name": "AdMob Analytics",
"url": "http://analytics.admob.com",
"description": "test AdMob Analytics"
}
],
"page": {
"current": 1,
"total": 1
}
}
Errors
This endpoint may return any standard error code documented here.

Site Stats v2
Endpoint
http://api.admob.com/v2/site/stats
HTTP Method
GET
Parameters
Name Type Example Note
client_key
Required client_key=k4004829c5899ba9
d231df3604b8ba45
Click here to learn more
about client keys
token
Required token=ta98585435afabcf26319
e2038a09f40
Click here to learn more
about authentication
site_id
Required site_id=a11111111111111
site_id[]
=a22222222222222&site_id[]
=a33333333333333
One or more site ids for
retrieving stats.
start_date
Required start_date=2010-01-01
end_date
Required end_date=2010-01-01
object_dimensio
n
Optional object_dimension=site Pass this parameter to
group stats by site. If this
parameter is not passed,
stats will be totaled
across all sites.
time_dimension
Optional time_dimension=day
time_dimension=week
time_dimension=month

Pass this parameter
to group stats by day,
week, or month. If this
parameter is not passed,
stats will be totaled
across the entire date
range.
order_by
Optional order_by[impressions]=desc
order_by[impressions]=asc
You can order by most
stat names returned by
this endpoint

Returns
Returns an array of site stats.
{
"errors": [
],
"warnings": [
],
"data": [
{
"site_id": "a22222222222222",
"requests": 3975183,
"overall_requests": 3975183,
"housead_requests": 0,
"interstitial_requests": 0,
"impressions": 3160241,
"cpc_impressions": 3096739,
"cpm_impressions": 63502,
"exchange_impressions": 0,
"housead_impressions": 0,
"interstitial_impressions": 0,
"fill_rate": 0.795,
"housead_fill_rate": 0,
"overall_fill_rate": 0.795,
"clicks": 14357,
"housead_clicks": 0,
"ctr": 0.0045,
"housead_ctr": 0,
"ecpm": 0.2654,
"revenue": 838.6146,
"cpc_revenue": 578.2176,
"cpm_revenue": 260.397,
"exchange_downloads": 0,
"date": "2010-01-09"
},
{
"site_id": "a22222222222222",
"requests": 3333404,
"overall_requests": 3333404,
"housead_requests": 0,
"interstitial_requests": 0,
"impressions": 2506779,
"cpc_impressions": 2467302,
"cpm_impressions": 39477,
"exchange_impressions": 0,
"housead_impressions": 0,
"interstitial_impressions": 0,
"fill_rate": 0.752,
"housead_fill_rate": 0,
"overall_fill_rate": 0.752,
"clicks": 12139,
"housead_clicks": 0,
"ctr": 0.0048,
"housead_ctr": 0,
"ecpm": 0.2492,
"revenue": 624.5699,
"cpc_revenue": 420.58,
"cpm_revenue": 203.9899,
"exchange_downloads": 0,
"date": "2010-01-10"
}
],
"page": {
"current": 1,
"total": 1
}
}

Errors
This endpoint may return any standard error code documented here.

Ad Search v2
Endpoint
http://api.admob.com/v2/ad/search
HTTP Method
GET
Parameters

Name Type Example Note
client_key
Required client_key=k4004829c589
9ba9d231df3604b8ba45
Click here to learn
more about client
keys

token
Required token=ta98585435afabcf2
6319e2038a09f40

Click here to
learn more about
authentication

ad_id
Optional ad_id=a11111111111111
ad_id[]
=a22222222222222&ad_i
d[]=a33333333333333
Search for ads with
these ids.
ad_group_id
Optional ad_group_id=a111111111
11111
Search for ads in this
ad group.
include_deleted
Optional include_deleted=1 If this parameter
is specified then
deleted ads will
be included in the
results. This is useful
if you want to get
stats for ads that
have been deleted.


Returns
Returns an array of ads that match all search parameters and are owned by the authenticated
user. If no search parameters are passed then all of the authenticated user's ads will be
returned.

{
"errors": [
],
"warnings": [
],
"data": [
{
"id": "a11111111111111",
"ad_group_id": "a33333333333333",
"name": "AdMob WWW",
"text": "Click me!",
"url": "http://www.admob.com"
},
{
"id": "a22222222222222",
"ad_group_id": "a44444444444444",
"name": "AdMob Analytics",
"text": "Click me!",
"url": "http://analytics.admob.com"
}
],
"page": {
"current": 1,
"total": 1
}
}

Errors
This endpoint may return any standard error code documented here.



Ad Stats v2
Endpoint
http://api.admob.com/v2/ad/stats
HTTP Method
GET
Parameters

Name Type Example Note
client_key
Required client_key=k4004829c5899b
a9d231df3604b8ba45
Click here to learn
more about client
keys
token
Required token=ta98585435afabcf263
19e2038a09f40
Click here to
learn more about
authentication
ad_id
Required ad_id=a11111111111111
ad_id[]
=a22222222222222&ad_id[]
=a33333333333333
One or more ad ids
for retrieving stats.
start_date
Required start_date=2010-01-01
end_date
Required end_date=2010-01-01
object_dimension
Optional object_dimension=ad Pass this parameter
to group stats by ad.
If this parameter is
not passed, stats will
be totaled across all
ads.

time_dimension
Optional time_dimension=day
time_dimension=week
time_dimension=month

Pass this parameter
to group stats by
day, week, or month.
If this parameter is
not passed, stats will
be totaled across the
entire date range.

order_by
Optional order_by[impressions]=desc
order_by[impressions]=asc
You can order by
most stat name
returned by this
endpoint

Returns
Returns an array of ad stats.

{
"errors": [
],
"warnings": [
],
"data": [
{
"impressions": 0,
"clicks": 0,
"ctr": 0,
"cost": 0,
"cpc": 0,
"ecpm": 0,
"date": "2009-12-10",
"ad_id": "a11111111111111"
},
{
"impressions": 168742,
"clicks": 2259,
"ctr": 0.0134,
"cost": 158.13,
"cpc": 0.07,
"ecpm": 0.9371,
"date": "2009-12-11",
"ad_id": "a22222222222222"
}
],
"page": {
"current": "1",
"total": 1
}
}
Errors
This endpoint may return any standard error code documented here.

Ad Group Search v2
Endpoint
http://api.admob.com/v2/ad_group/search
HTTP Method
GET
Parameters

Name Type Example Note
client_key
Required client_key=k4004829
c5899ba9d231df3604
b8ba45
Click here to learn
more about client
keys
token
Required token=ta98585435afa
bcf26319e2038a09f4
0
Click here to
learn more about
authentication
ad_group_id
Optional ad_group_id=a11111
111111111
ad_group_id[]
=a222222222222
22&ad_group_id[]
=a33333333333333
Search for ad groups
with these ids.
campaign_id
Optional campaign_id=a11111
111111111
Search for ad groups
in this campaign.
include_deleted
Optional include_deleted=1 If this parameter
is specified then
deleted ad groups
will be included in
the results. This is
useful if you want
to get stats for ad
groups that have
been deleted.




Returns
Returns an array of ad groups that match all search parameters and are owned by the
authenticated user. If no search parameters are passed then all of the authenticated user's ad
groups will be returned.

{
"errors": [
],
"warnings": [
],
"data": [
{
"id": "a11111111111111",
"campaign_id": "a33333333333333",
"name": "AdMob WWW"
},
{
"id": "a22222222222222",
"campaign_id": "a44444444444444",
"name": "AdMob Analytics"
}
],
"page": {
"current": 1,
"total": 1
}
}

Errors
This endpoint may return any standard error code documented here.

Ad Group Stats v2

Endpoint
http://api.admob.com/v2/ad_group/stats
HTTP Method
GET
Parameters

Name Type Example Note
client_key
Required client_key=k4004829c5899ba
9d231df3604b8ba45
Click here to learn
more about client
keys
token
Required token=ta98585435afabcf2631
9e2038a09f40
Click here to
learn more about
authentication
ad_group_id
Required ad_group_id=a111111111111
11
ad_group_id[]
=a22222222222222&ad_grou
p_id[]=a33333333333333
One or more
ad group ids for
retrieving stats.

start_date
Required start_date=2010-01-01
end_date
Required end_date=2010-01-01
object_dimension
Optional object_dimension=ad_group Pass this parameter
to group stats by
ad group. If this
parameter is not
passed, stats will be
totaled across all ad
groups.
time_dimension
Optional time_dimension=day
time_dimension=week
time_dimension=month
Pass this parameter
to group stats by day,
week, or month. If
this parameter is not
passed, stats will be
totaled across the
entire date range.

order_by
Optional order_by[impressions]=desc
order_by[impressions]=asc
You can order by
most stat names
returned by this
endpoint

Returns
Returns an array of ad group stats.

{
"errors": [
],
"warnings": [
],
"data": [
{
"impressions": 0,
"clicks": 0,
"ctr": 0,
"cost": 0,
"cpc": 0,
"ecpm": 0,
"date": "2009-12-10",
"ad_id": "a11111111111111"
},
{
"impressions": 168742,
"clicks": 2259,
"ctr": 0.0134,
"cost": 158.13,
"cpc": 0.07,
"ecpm": 0.9371,
"date": "2009-12-11",
"ad_id": "a22222222222222"
}
],
"page": {
"current": 1,
"total": 1
}
}

Errors
This endpoint may return any standard error code documented here.This endpoint may return
any standard error code documented here.
Campaign Search v2
Endpoint
http://api.admob.com/v2/campaign/search
HTTP Method
GET
Parameters

Name Type Example Note
client_key
Required client_key=k4004829c5899ba
9d231df3604b8ba45
Click here to learn
more about client
keys
token
Required token=ta98585435afabcf2631
9e2038a09f40
Click here to
learn more about
authentication
campaign_id
Optional campaign_id=a11111111111
111
campaign_id[]
=a22222222222222&campai
gn_id[]=a33333333333333
Search for campaigns
with these ids.
include_deleted
Optional include_deleted=1 If this parameter
is specified then
deleted campaigns
will be included in
the results. This is
useful if you want
to get stats for
campaigns that have
been deleted.

Returns
Returns an array of campaigns that match all search parameters and are owned by the
authenticated user. If no search parameters are passed then all of the authenticated user's
campaigns will be returned.

{
"errors": [
],
"warnings": [
],
"data": [
{
"id": "a11111111111111",
"name": "AdMob WWW",
"notes": "hello world",
},
{
"id": "a22222222222222",
"name": "AdMob Analytics",
"notes": "hello world",
}
],
"page": {
"current": 1,
"total": 1
}
}

Errors
This endpoint may return any standard error code documented here.

Campaign Stats v2
Endpoint
http://api.admob.com/v2/campaign/stats
HTTP Method
GET
Parameters

Name Type Example Note
client_key
Required client_key=k4004829c5899ba
9d231df3604b8ba45
Click here to learn
more about client
keys
token
Required token=ta98585435afabcf2631
9e2038a09f40
Click here to
learn more about
authentication
campaign_id
Required campaign_id=a11111111111
111
campaign_id[]
=a22222222222222&campaig
n_id[]=a33333333333333
One or more
campaign ids for
retrieving stats.
start_date
Required start_date=2010-01-01
end_date
Required end_date=2010-01-01
object_dimension
Optional object_dimension=campaign Pass this parameter
to group stats by
campaign. If this
parameter is not
passed, stats will be
totaled across all
campaigns.
time_dimension
Optional time_dimension=day
time_dimension=week
time_dimension=month
Pass this parameter
to group stats by day,
week, or month. If
this parameter is not
passed, stats will be
totaled across the
entire date range.
order_by
Optional order_by[impressions]=desc
order_by[impressions]=asc

You can order by
most stat names
returned by this
endpoint

Returns
Returns an array of campaign stats.

{
"errors": [
],
"warnings": [
],
"data": [
{
"impressions": 0,
"clicks": 0,
"ctr": 0,
"cost": 0,
"cpc": 0,
"ecpm": 0,
"date": "2009-12-10",
"campaign_id": "a11111111111111"
},
{
"impressions": 168742,
"clicks": 2259,
"ctr": 0.0134,
"cost": 158.13,
"cpc": 0.07,
"ecpm": 0.9371,
"date": "2009-12-11",
"campaign_id": "a22222222222222"
}
],
"page": {
"current": 1,
"total": 1
}
}
Errors
This endpoint may return any standard error code documented here.This endpoint may return
any standard error code documented here.