GetCampaigns

From MdotM API
Jump to: navigation, search
  • The advertiser can call the MdotM API periodically to retrieve campaign data.
  • Using this information, the advertiser can measure of a variety of performance metrics, including:
    • Campaign Pacing
    • Performance of Creatives
    • Geographic Performance
    • Performance by Device

Request

Method: GET
Rate Limit: Every 60 seconds.
URL: http://ads.mdotm.com/api/1.0/getCampaigns

with required parameters (email, secretkey):

Name Description Type Compulsion Example
email
Your email address
String
Required
email=api@mdotm.com
secretKey
Alphanumeric authentication code
String
Required
secretKey=4431141f1f341afaacd

and additional parameters:

Name Description Type Compulsion Example
appID Limit results to one or more App IDs.

For iOS apps, use your 9-digit ID iTunes ID: https://www.codeproof.com/blog/how-to-find-aitunes-store-id-or-appid/ .

For Android apps, use the value you set for the "package" variable as described here: http://developer.android.com/guide/topics/manifest/manifest-element.html .
String
Optional
appID=123456789
or
appID=com.app.developer
startDT
Specify start date for performance history, YYYY-mm-dd
String
Optional
startDT=2012-01-01
endDT
Specify end date for performance history, YYYY-mm-dd
String
Optional
endDT=2012-03-31

Response

Returns: JSON Array of campaigns which is an array of objects with the following attributes:

NOTE: Fields with no data do not show up at all.

Name Description Type Example
campaignID
Campaign ID
String
"123456"
campaignName
Campaign Name
String
"Example"
startDT
StartDate, YYYY-mm-dd
Start Date/Time
"2011-12-01"
endDT
EndDate, YYYY-mm-dd
End Date/Time
"2011-12-31"
iphoneAppID
iOS - iTunes App ID
String
"123456789"
ipadAppID
iOS - iTunes App ID
String
"123456789"
androidAppID
Android - Package Name
String
"com.example.appname"
desktopUrl
Desktop URL
String
"http://example.com"
mobileUrl
Mobile URL
String
"m.example.com"
totalSpendMax
Total Spend Cap, in USD
Float
"250000"
monthSpendMax
Monthly Spend Cap, in USD
Float
"0"
daySpendMax
Day Spend Cap, in USD
Float
"0"
status
Campaign Status
String
"Active"
adGroups
Ad Group data
Array
[ ... ]
external_campaignID
Client's Campaign ID
String
"123"

and an adGroups attribute which is an array of objects with the following attributes:

Name Description Type Example
adgroupID
Ad Group ID
String
"123456"
adGroupName
Ad Group Name
String
"Example_iPhone_US-GB"
appID
App ID
String
"123456789"
countryTargeting
Countries Targeted
Array
["US","GB"]
excludeCountries
Countries Excluded
Array
["CA","AU"]
osTargeting
OS Versions Targeted
Array
["3.0","3.1","3.2","4.0","4.1","4.2","4.3","5.0"]
deviceTargeting
Devices Targeted
Array
["iPhone","iPod"]
includeDevices
Devices Included
Array
["Dell Streak","Motorola Razr"]
excludeDevices
Devices Excluded
Array
["Samsung Galaxy","Droid X"]
cpc
Cost-per-Click, in USD
Float
"0"
cpa
Cost-per-Action, in USD
Float
"1.50"
cpm
Cost Per Thousand Impressions, in USD
Float
"0"
status
Ad Group Status
String
"Active"
performance
Performance data
Array
[ ... ]
external_adgroupID
Client's Adgroup ID
String
"123"

and a performance attribute which is an array of objects with the following attributes:

Name Description Type Example
logDate
Campaign info by Date, YYYY-mm-dd
Date
"2012-01-01"
impressions
Impressions
Integer
"100000"
clicks
Clicks
Integer
"2000"
conversions
Conversions
Integer
"80"
purchases
Purchases (or other secondary event)
Integer
"35"
price
Spend, in USD
Float
"120.00"
status
Ad Status
String
"Active"
external_adID
Client's Ad ID
String
"123"

Example

Request:

http://ads.mdotm.com/api/1.0/getCampaigns?email=your@email.com&secretKey=yoursecretkey&appID=com.example.appname&startDT=2012-01-01&endDT=2012-03-31
http://ads.mdotm.com/api/1.0/getCampaigns?email=your@email.com&secretKey=yoursecretkey&appID=123456789&startDT=2012-01-01&endDT=2012-03-31

Response:

{
"error":0,
"description":"success",
"response":{
            "campaigns":[
                         {
                          "campaignID":"123456",
                          "campaignName":"Example",
                          "startDT":"2012-01-01",
                          "endDT":"2012-03-31",
                          "iPhoneAppID":"123456789",
                          "iPadAppID":"123456789",
                          "androidAppID":"com.example.appname",
                          "desktopURL":"http://example.com",
                          "mobileURL":"m.example.com",
                          "totalSpendMax":"250000",
                          "monthSpendMax":"0",
                          "daySpendMax":"0",
                          "status":"Active",
                          "external_campaignID":"123",
                          "adGroup":[
                                      {
                                       "adGroupID":"123456",
                                       "adGroupName":"Example_iPhone_US-GB",
                                       "appID":"123456789",
                                       "Countries":["US","GB"],
                                       "excludeCountries":["CA","AU"],
                                       "Devices":["iPhone","iPod"],
                                       "includeDevices":["Dell Streak","Motorola Razr"],
                                       "excludeDevices":["Samsung Galaxy 2","Droid X"],
                                       "OS":["3.0","3.1","3.2","4.0","4.1","4.2","4.3","5.0"],
                                       "totalSpendMax":"250000",
                                       "monthSpendMax":"0",
                                       "daySpendMax":"0",
                                       "cpc":"0",
                                       "cpa":"1.50",
                                       "cpm":"0",
                                       "status":"Active",
                                       "external_adgroupID":"123",
                                       "performance":[
                                                      {
                                                       "logDate": "2015-06-01",
                                                       "impressions":"100000",
                                                       "clicks":"2000",
                                                       "conversions":"80",
                                                       "purchases":"35",
                                                       "price":"120.00",
                                                       "status":"Active",
                                                       "external_adID":"123"
                                                      }
                                                     ]
                                      }
                                     ]
                         }
                        ]
            }
}