Publisher API
Contents |
Overview
Use this API to:
- programmatically create publications via an API
- report on those publications
Data model
Adfonic has a three-tiered data model for managing publisher data that is useful to understand for the purposes of this API.
- Account -- this is the Adfonic account which collects revenue, receives payments, and so on.
- Publication -- these are the individual mobile sites or apps.
- Ad slot -- each publication can contain one or more ad slots, e.g. to represent different pages within a site, or different ad formats that will display in various areas.
Access to the APIs
The services use the HTTP REST model. Parameters can be encoded as a query string or post data. Parameters must be properly URL-encoded in all cases.
In general, the APIs are accessed via URLs that fit the following pattern:
https://api.adfonic.net/type/service.format
For operations on an existing object (publication or ad slot) the ID is part of the URL.
https://api.adfonic.net/type/id.format
The format suffix can be either .xml or .json and dictates the response format. The examples below use XML for readability, but the JSON mappings are straightforward.
Authentication to the APIs is via a per-account developer key. To acquire a developer key, please fill out the [Technical Support] form. Your developer key will be issued by Adfonic and should be kept secret. For ease of integration, the developer key can be sent in the clear. Note that if someone acquires your developer key, they can access any of the methods in this API, but they cannot log in to your account, change payment options, etc. If you need a new developer key, Adfonic can regenerate one for you.
The developer key is used as the password in standard HTTP Basic Authentication (the "Authorization" HTTP header). The corresponding username is your Adfonic account (i.e., your email address). You should be aware that Basic Authentication is not an encrypted protocol; in order to secure the connection, you should ensure that you are using HTTPS for the connection itself.
If the request is successful, you will get a 200 HTTP response. Additional information is formatted as XML in the response as shown for each method below. All XML responses are wrapped in the following (MASG is the Mobile Ad Serving Group).
<masg-response> ... body of response ... </masg-response>
If you get a HTTP 4xx error returned, the body of the response will contain details about the error condition in the following format for XML:
<masg-error> <code>INTEGER</code> <description> ...human readable description... </description> </masg-error>
Publication management functions
Create new publication
POST /publication/create.{format}
This service takes the following parameters
| name | Name of the publication. Maximum length is 255 characters. |
| type | Publication type. Valid values are: MOBILE_SITE, IPHONE_APP, IPHONE_SITE, ANDROID_APP, JAVA_APP, OTHER_APP |
| description | A human readable description. Maximum length is 4096 characters. |
| reference | An optional reference, e.g. an ID on your side that you want to associate with the publication |
| url | A URL associated with the publication. This is optional for applications. |
| transparent | true or false. If true, Adfonic may share the name and description of the publication with advertisers. Where possible you should allow each publisher to opt-in to transparency. |
| languages | Optional ISO two-letter language code for the publication, e.g. "es" for Spanish, "en" for English. If no language is given, English is assumed. If multiple languages are supported, they should be comma-separated. |
| requests | Optional. Estimated ad requests per month. Please submit integers with no formatting or punctuation. |
| uniques | Optional. Estimated unique users per month. Please submit integers with no formatting or punctuation. |
| autoapprove | Optional. true or false, defaults to true. If false, ads for the publication must be manually reviewed and approved using the Adfonic.com site. |
A successful response will give you the newly created Publication ID and echo back the current state of the publication.
<masg-response>
<publication>
<id> ... </id>
<name> ... </name>
<description> ... </description>
<type> ... </type>
<reference> ... </reference>
<url> ... </url>
<transparent> true|false </transparent>
<requests> ... </requests>
<uniques> ... </uniques>
<languages> ... </languages>
<autoapprove> true|false </autoapprove>
<status> ... </status>
</publication>
</masg-response>
Create new ad slot
POST /adslot/create.{format}
| publication | The publication ID. |
| name | A name for the ad slot. Limited to 255 characters. |
| formats | Ad format(s) for the ad slot. The following formats are supported: banner, text, iab300x250. Note that banner is a dynamically sized format depending on the device type. For iPhone requests it is 300x50. If you can support the display of both banner and text ads in the ad slot, please specify both ("banner,text"). |
| tags | Optional set of comma-separated tags for the ad slot. Tags are used to help target (but not exclude) campaigns. Each tag must be 255 characters or less. There is no limit to the number of tags per slot. |
The response will give you an Ad Slot ID that may be used in ad requests.
<masg-response>
<adslot>
<id> ... </id>
<publication> ... </publication>
<name> ... </name>
<formats> ... </formats>
<tags> ... </tags>
</adslot>
</masg-response>
Update publication
POST /publication/{id}.{format}
| name | Optional. Name of the publication. Maximum length is 255 characters. |
| description | Optional. A human readable description. Maximum length is 4096 characters. |
| reference | Optional. An optional reference, e.g. an ID on your side that you want to associate with the publication |
| url | Optional. A URL associated with the publication. This is optional for applications. |
| transparent | Optional. true or false. If true, Adfonic may share the name and description of the publication with advertisers. Where possible you should allow each publisher to opt-in to transparency. |
| languages | Optional ISO two-letter language code for the publication, e.g. "es" for Spanish, "en" for English. If no language is given, English is assumed. |
| requests | Optional. Estimated ad requests per month. Please submit integers with no formatting or punctuation. |
| uniques | Optional. Estimated unique users per month. Please submit integers with no formatting or punctuation. |
| autoapprove | Optional. true or false, defaults to true. If false, ads for the publication must be manually reviewed and approved using the Adfonic.com site. |
| status | Optional. Can be PAUSED, ACTIVE or STOPPED. Note that once stopped, publications cannot be reactivated (this is a permanent action). Pausing a publication will cause all ad requests to be treated as test requests and not recorded for purposes of statistics or earnings. |
If successful, the response will confirm the publication status.
<masg-response>
<publication>
<id> ... </id>
<name> ... </name>
<description> ... </description>
<type> ... </type>
<reference> ... </reference>
<url> ... </url>
<transparent> true|false </transparent>
<requests> ... </requests>
<uniques> ... </uniques>
<languages> ... </languages>
<autoapprove> true|false </autoapprove>
<status> ACTIVE </status>
</publication>
</masg-response>
Update ad slot
POST /adslot/{id}.{format}
| name | Optional. New name for the ad slot. Limited to 255 characters. |
| formats | Optional. Ad formats for the ad slot, comma separated. The following formats are supported: banner, text, iab300x250. Note that banner is a dynamically sized format depending on the device type. For iPhone requests it is 300x50. |
| tags | Optional set of comma-separated tags for the ad slot. Tags are used to help target (but not exclude) campaigns. Each tag must be 255 characters or less. There is no limit to the number of tags per slot. |
The response will show the updated ad slot.
<masg-response>
<adslot>
<id> ... </id>
<publication> ... </publication>
<name> ... </name>
<formats> ... </formats>
<tags> ... </tags>
</adslot>
</masg-response>
List publications
GET /publication/list.{format}
| status | Optional status filter. Valid values are ACTIVE, PAUSED, STOPPED. |
<masg-response>
<publication>
<id> ... </id>
<name> ... </name>
<description> ... </description>
<type> ... </type>
<reference> ... </reference>
<url> ... </url>
<transparent> true|false </transparent>
<requests> ... </requests>
<uniques> ... </uniques>
<languages> ... </languages>
<autoapprove> true|false </autoapprove>
<status> ... </status>
</publication>
<publication ... > <!-- for each publication --> </publication>
</masg-response>
List ad slots
GET /adslot/list.{format}
| publication | Optional Publication ID. If omitted, all ad slots for the account will be listed. |
<masg-response>
<adslot>
<id> ... </id>
<publication> ... </publication>
<name> ... </name>
<formats> ... </formats>
<tags> ... </tags>
</adslot>
<adslot ... > <!-- for each ad slot -->
</masg-response>
Reporting functions
The reporting functions allow you to access realtime reporting information from Adfonic's servers. Reporting is currently granular to the latest hour. The start and end times are inclusive. That means that to get a full day's statistics, you would specify for example 2010031100 as the starting hour, and 2010031123 as the ending hour. Note that the times are relative to the time zone you have configured for your Adfonic account.
The response gives the following metrics: requests, impressions, clicks, and earnings. Earnings is the net payment due to the publisher for the activity period.
You can get a breakdown by country by specifying bycountry=true to each of these methods.
Note that Adfonic uses USD as the single currency for all accounts.
Get all reporting statistics
GET /publication/statistics.{format}
Get reporting statistics for all publications.
| level | The level at which to provide data. Valid values are "publication" or "adslot". The default is publication. |
| start | The start date and hour in YYYYMMDDHH form. This is assumed to be in the time zone you have configured for your account. |
| end | The end date and hour (inclusive) in YYMMDDHH form. This is assumed to be in the time zone you have configured for your account. |
| bycountry | Optional, defaults to false. true means show breakdown for all countries with data |
Response (level=publication, bycountry=false)
<masg-response>
<publication>
<id> ... </id>
<statistics> <!-- Global -->
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>
<currency>USD</currency>
<amount>DECIMAL</amount>
</earnings>
</statistics>
</publication>
<publication ...> <!-- repeat for each publication... --> </publication>
</masg-response>
Response (level=publication, bycountry=true)
<masg-response>
<publication>
<id> ... </id>
<statistics>
<country>US</country><!-- Two letter ISO country code -->
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>
<currency>USD</currency>
<amount>DECIMAL</amount>
</earnings>
</statistics>
<statistics>
<country>GB</country>
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>
<currency>USD</currency>
<amount>DECIMAL</amount>
</earnings>
</statistics>
<!-- repeat for each country -->
</publication>
<publication ...> <!-- repeat for each publication... --> </publication>
</masg-response>
Response (level=adslot, bycountry=false)
<masg-response>
<publication>
<id> ... </id>
<adslot>
<id> ... </id>
<statistics>
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>
<currency>USD</currency>
<amount>DECIMAL</amount>
</earnings>
</statistics>
</adslot>
<adslot ...> <!-- if multiple ad slots --> </adslot>
</publication>
<publication ...> <!-- repeat for each publication... --> </publication>
</masg-response>
With level=adslot and bycountry=true, same as above but statistics for each country for each adslot.
Get reporting statistics for publication
GET /publication/{id}/statistics.{format}
This method provides a rollup for all ad slots for all publications (first form) or a given publication (second form).
| level | The level at which to provide data. Valid values are "publication" or "adslot". The default is publication. |
| start | The start date and hour in YYYYMMDDHH form. This is assumed to be in the time zone you have configured for your account. |
| end | The end date and hour (inclusive) in YYMMDDHH form. This is assumed to be in the time zone you have configured for your account. |
| bycountry | Optional, defaults to false. true means show breakdown for all countries with data |
Response (level=publication)
<masg-response>
<publication>
<id> ... </id>
<statistics> <!-- Optionally per country as above -->
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>
<currency>USD</currency>
<amount>DECIMAL</amount>
</earnings>
</statistics>
</publication>
<publication ...> <!-- if multiple publications --> </publication>
</masg-response>
Response (level=adslot)
<masg-response>
<publication>
<id> ... </id>
<adslot>
<id> ... </id>
<statistics> <!-- Optionally per country as above -->
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>
<currency>USD</currency>
<amount>DECIMAL</amount>
</earnings>
</statistics>
</adslot>
<adslot ...> <!-- if multiple ad slots --> </adslot>
</publication>
</masg-response>
Get reporting statistics for ad slot
GET /adslot/{id}/statistics.{format}
This method provides the ad slot level detail for a given ad slot.
| start | The start date and hour in YYYYMMDDHH form. This is assumed to be in the time zone you have configured for your account. |
| end | The end date and hour (inclusive) in YYMMDDHH form. This is assumed to be in the time zone you have configured for your account. |
| bycountry | Optional, defaults to false. true means show breakdown for all countries with data |
Response
<masg-response>
<adslot>
<id> ... </id>
<statistics> <!-- one per country if global=false... -->
<requests>INTEGER</requests>
<impressions>INTEGER</impressions>
<clicks>INTEGER</clicks>
<earnings>DECIMAL</earnings>
</statistics>
</adslot>
<adslot ...> <!-- if multiple adslots... --> </adslot>
</masg-response>
