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 v 2 Endpoint HTTP Method Parameters Returns Errors Auth Logout v 2 Endpoint HTTP Method Parameters Returns Errors Site Search v 2 Endpoint HTTP Method Parameters Returns Errors Site Stats v 2 Endpoint HTTP Method
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
AdMob API DocumentationTable of Contents Getting StartedAPI Requests
ParametersClient KeysAuthenticationRate Limiting
API ResponsesFormatPagination
ExampleErrors
Error CodesWarnings
How are warnings different from errors?Warning Codes
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
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.
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
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.
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.
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.{
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.
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.
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
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.
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. {
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.