Advertiser API
Contents |
Overview
Use this API to:
- programmatically view Campaigns and Creatives via an API
- report on those Campaigns and Creatives
Data model
Adfonic has a three-tiered data model for managing advertiser data that is useful to understand for the purposes of this API.
- Account -- this is the Adfonic account which manages the budgets and payments, and so on.
- Campaign
- Creative
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>
View advertisers
GET /advertisers/list.{format}
A successful response will return an array of Advertiser objects.
<masg-response> <advertiser> <id>62519873-6975-4cee-a708-793b53b74e29</id> <name>Somo</name> <status>ACTIVE</status> <dailyBudget></dailyBudget> <balance>1787.48</balance> <notifyLimit>100.00</notifyLimit> </advertiser> </masg-response>
View campaigns
GET /advertiser/{AdvertiserID}/campaigns/list.{format}
A successful response will return an array of Campaign objects.
<masg-response> <campaign> <id>111111-c52c-41ed-1111-1200e1f6d8b3</id> <name>Demonstration Campaign</name> <status>ACTIVE</status> <description>Demonstration Campaign</description> <advertiser>111111-6975-4cee-1111-793b53b74e29</advertiser> <startDate></startDate> <endDate>11-30-2011 23:59</endDate> <activationDate>11-22-2011 17:01</activationDate> <deactivationDate></deactivationDate> <dailyBudget>83.33</dailyBudget> <overallBudget>750.00</overallBudget> <dailyBudgetWeekday></dailyBudgetWeekday> <dailyBudgetWeekend></dailyBudgetWeekend> </campaign> </masg-response>
View campaign
GET /campaign/{CampaignID}.{format}
This service takes the following parameters
| CampaignID | ID of the Campaign. |
A successful response will return the Campaign object.
<masg-response> <campaign> <id>111111-c52c-41ed-1111-1200e1f6d8b3</id> <name>Demonstration Campaign</name> <status>ACTIVE</status> <description>Demonstration Campaign</description> <advertiser>111111-6975-4cee-1111-793b53b74e29</advertiser> <startDate></startDate> <endDate>11-30-2011 23:59</endDate> <activationDate>11-22-2011 17:01</activationDate> <deactivationDate></deactivationDate> <dailyBudget>83.33</dailyBudget> <overallBudget>750.00</overallBudget> <dailyBudgetWeekday></dailyBudgetWeekday> <dailyBudgetWeekend></dailyBudgetWeekend> </campaign> </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 reporting statistics for a specific campaign
GET /campaign/{CampaignID}/statistics.{format}
Get reporting statistics for all publications.
| 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. |
<masg-response>
<campaign>
<id>1111111-c52c-41ed-1111-1200e1f6d8b3</id>
<statistics>
<impressions>4859</impressions>
<clicks>17</clicks>
<conversions>1</conversions>
<conversionsPercent>5.88</conversionsPercent>
<CTR>
<currency>USD</currency>
<amount>0.00</amount>
</CTR>
<ECPM>
<currency>USD</currency>
<amount>0.21</amount>
</ECPM>
<costPerConversion>
<currency>USD</currency>
<amount>1.04</amount>
</costPerConversion>
<spend>
<currency>USD</currency>
<amount>1.04</amount>
</spend>
</statistics>
</campaign>
</masg-response>
