AdMob API Documentation

AdMob API DocumentationTable of Contents Getting StartedAPI Requests

ParametersClient KeysAuthenticationRate Limiting

API ResponsesFormatPagination

ExampleErrors

Error CodesWarnings

How are warnings different from errors?Warning Codes

Auth Login v2EndpointHTTP MethodParametersReturnsErrors

Auth Logout v2EndpointHTTP MethodParametersReturnsErrors

Site Search v2EndpointHTTP MethodParametersReturnsErrors

Site Stats v2EndpointHTTP Method

ParametersReturnsErrors

Ad Search v2EndpointHTTP MethodParametersReturnsErrors

Ad Stats v2EndpointHTTP MethodParametersReturnsErrors

Ad Group Search v2EndpointHTTP MethodParametersReturnsErrors

Ad Group Stats v2EndpointHTTP MethodParametersReturnsErrors

Campaign Search v2EndpointHTTP MethodParametersReturnsErrors

Campaign Stats v2EndpointHTTP MethodParametersReturnsErrors

API

The AdMob API allows you to access the campaign, sites and applications data in yourAdMob account with a secure programmatic interface. You can build custom applicationsusing the AdMob API to help better manage your mobile business.

Getting StartedIf 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

ParametersEach AdMob API endpoint requires either a GET or POST request. Endpoints that do notmodify 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 usedto 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 notationcan be used to order stats by impressions descending.

order_by[impressions]=desc

Client Keys

http://www.admob.com/api









All AdMob API endpoints require the client_key parameter which identifies the API clientmaking the request. Client keys can be created at http://www.admob.com/api/. If you arethe author of multiple clients, you should create a different client key for each of yourclients.

AuthenticationIf 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 alimited 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 anew token to continue making requests on behalf of the AdMob user. A token maybecome 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 LimitingThe number of requests that a client can make is subject to a rate limit. This rate limit maychange over time as we learn more about how the API is used. If a single client or userexceeds a rate limit then subsequent requests will return with an error for a short period oftime. API clients should wait at least 1 second before retrying a request that was ratelimited. {

"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

FormatThe 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.

PaginationThere is a limit to the amount of data that will be returned in one API call. Currently thislimit 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 canretrieve the remaining pages of data by repeating the request with the page parameter.

ExampleConsider a fictional endpoint that has a page limit of 5 items and you request 8 items. Onthe 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 3items. To request the second page, the first request is repeated with the additional parameterpage=2. The second response might look like this:{

"errors": [

],

"warnings": [

],

"data": [

{

"name": "row6"

},

{

"name": "row7"

},

{

"name": "row8"

}

],

"page": {

"current": 2,

"total": 2

}

}

ErrorsIf an error occurs, it means that the API was unable to return the data that you requestedand 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 fieldto determine how to handle the error.

msg

A human readable message that may provide additional information to the end useror developer about the error that occurred. The API client should not rely on thecontents of the error message because error messages can be added or changedwithout notice.

If the error array is empty then the request was successful:{

"errors": [

],

"warnings": [

],

"data": null,

"page": {

"current": 1,

"total": 1

}

}

Error CodesThere 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 deprecatean 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 [email protected] 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

mailto:[email protected]






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.)

WarningsIf a warning occurs, it means that the API was able to complete the request as expected butthere is some condition or information that might need to be handled by the developer ofthe API client. If a warning occurs then the response will contain a non-empty array ofwarning 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

Endpointhttps://api.admob.com/v2/auth/login

HTTP MethodPOST

Parameters

Name Type Example Note

client_key Required client_key=k4004829c5899ba9d231df3604b8ba45

Click here to learn more about client keys

email Required [email protected] 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.

ReturnsReturns a token on success. {

"errors": [

],

"warnings": [

],

"data": {

"token": "ta98585435afabcf26319e2038a09f40"

},

"page": {

"current": 1,

"total": 1

}

}

https://api.admob.com/v2/auth/login


















http://www.admob.com/my_account/account_info
















http://www.admob.com






ErrorsThis endpoint may return any standard error code documented here.

Auth Logout v2

Endpointhttps://api.admob.com/v2/auth/logout

HTTP MethodPOST

ParametersName Type Example Note



token Required token=ta98585435afabcf26319e2038a09f4

Token to destroy

ReturnsReturns nothing on success.{

"errors": [

],

"warnings": [

],

"data": null,

"page": {

"current": 1,

"total": 1

}

}


https://api.admob.com/v2/auth/logout













Site Search v2

Endpointhttp://api.admob.com/v2/site/search

HTTP MethodGET

Parameters





Click here to learn more about authentication

site_id Optional site_id=a11111111111111site_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.

ReturnsReturns 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",

http://api.admob.com/v2/site/search













"description": "test AdMob site"

},

{

"id": "a22222222222222",

"name": "AdMob Analytics",

"url": "http://analytics.admob.com",

"description": "test AdMob Analytics"

}

],

"page": {

"current": 1,

"total": 1

}

}


Site Stats v2

Endpointhttp://api.admob.com/v2/site/stats

HTTP MethodGET

Parameters






site_id Required site_id=a11111111111111site_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

nOptional 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=daytime_dimension=weektime_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]=descorder_by[impressions]=asc

You can order by most stat names returned by this endpoint

Returns

http://api.admob.com/v2/site/stats













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,


"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

}

}


Ad Search v2

Endpointhttp://api.admob.com/v2/ad/search

HTTP MethodGET

Parameters






ad_id Optional ad_id=a11111111111111ad_id[]=a22222222222222&ad_id[]=a33333333333333

Search for ads with these ids.

ad_group_id Optional ad_group_id=a11111111111111

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.

ReturnsReturns 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.

http://api.admob.com/v2/ad/search













{

"errors": [

],

"warnings": [

],

"data": [

{

"id": "a11111111111111",

"ad_group_id": "a33333333333333",


"text": "Click me!",

"url": "http://www.admob.com"

},

{

"id": "a22222222222222",

"ad_group_id": "a44444444444444",


"text": "Click me!",

"url": "http://analytics.admob.com"

}

],

"page": {

"current": 1,

"total": 1

}

}


Ad Stats v2

Endpointhttp://api.admob.com/v2/ad/stats

HTTP MethodGET

Parameters






ad_id Required ad_id=a11111111111111ad_id[]=a22222222222222&ad_id[]=a33333333333333

One or more ad ids for retrieving stats.



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.



http://api.admob.com/v2/ad/stats














You can order by most stat name returned by this endpoint

ReturnsReturns 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"

},

{


"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

}

}


Ad Group Search v2

Endpointhttp://api.admob.com/v2/ad_group/search

HTTP MethodGET

Parameters






ad_group_id Optional ad_group_id=a11111111111111ad_group_id[]=a22222222222222&ad_group_id[]=a33333333333333

Search for ad groups with these ids.

campaign_id Optional campaign_id=a11111111111111

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.

ReturnsReturns an array of ad groups that match all search parameters and are owned by the

http://api.admob.com/v2/ad_group/search















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

}

}


Ad Group Stats v2

Endpointhttp://api.admob.com/v2/ad_group/stats

HTTP MethodGET

Parameters






ad_group_id Required ad_group_id=a11111111111111ad_group_id[]=a22222222222222&ad_group_id[]=a33333333333333

One or more ad group ids for retrieving stats.



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.



http://api.admob.com/v2/ad_group/stats

















ReturnsReturns 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"

},

{


"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

}

}

ErrorsThis 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 MethodGET

Parameters






campaign_id Optional campaign_id=a11111111111111campaign_id[]=a22222222222222&campaign_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 inthe results. This is useful if you want to get stats for campaigns that have been deleted.

ReturnsReturns 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",


"notes": "hello world",

},

{

"id": "a22222222222222",


"notes": "hello world",

}

],

"page": {

"current": 1,

"total": 1

}

}


Campaign Stats v2

Endpointhttp://api.admob.com/v2/campaign/stats

HTTP MethodGET

Parameters






campaign_id Required campaign_id=a11111111111111campaign_id[]=a22222222222222&campaign_id[]=a33333333333333

One or more campaign ids for retrieving stats.



object_dimension Optional object_dimension=campaign Pass this parameter to group stats by campaign. If this parameter is not passed, stats will betotaled across all campaigns.



http://api.admob.com/v2/campaign/stats















ReturnsReturns 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"

},

{


"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

}

}

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

Documents

AdMob API Documentation