adcolony publisher reporting api v2...as of v2.3, data for this api is updated continuously, and has...
TRANSCRIPT
AdColonyPublisherReportingAPIv2.3
RevisionDate DescriptionJan15,2014 InitialreleaseMay28,2014 ReplacedtyposappIDwithapp_idinrequestURLsJan26,2015 Added‘country’forgroup_byparameterJun25,2015 Enabledgroupbyzonebycountry
AddedplatformcolumnAddedInternalAppIDcolumnRowswithnodataisexcludedAddeddefaultrequestlimit(10perminute;100perhour)
Apr12,2016 AddedStoreIDcolumnPerformanceUpdates
- Continuousdataupdates- Nearreal-time(only5-15mindelay)
Nov22,2016 APIdocumentationupdatedtoincludedetailsonAPIQueueLimit(SeeErrorssection)
TheuseofthereportingAPIisintendedforpublishersrunningonAdColonyVideoAdNetworktoretrieveadperformancereportingdataviaanAPI.TheAPIusesHTTPGETtomakereportingrequeststotheserverandretrieveresults.
1.APIAccess
URL:http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=mmddyyyy
Note:PleaserefertotheAPIKeyinPublisherPortaltoaccesstheReportingAPI
2.PublisherSummaryReports
Asofv2.3,dataforthisAPIisupdatedcontinuously,andhasabouta15mindelaytorealtimereporting.
ThepublishersummaryreportingAPIprovidesperformancedataaboutappsunderapublisher’saccount.ThereportingAPIallowsforvariabledaterangeorspecificdatereports.Reportscanbegeneratedforallappsorforspecificapp.Performancedatacanbegroupedbydifferentdateintervalsandbrokenoutbyappandzone.Formoreinformationonalltheseoptionsconsulttherequestparametersandsamplerequestsbelow.Note:AdayisdefinedbytheGMTtimezone
2.1RequestParameters
Parameter DataElement Description
user_credentialsString.
Required.
PleaseusetheAPIKeyfoundinyourAccountsettinginAdColonyDashboardPortaltoaccesstheReportingAPI.
app_idString.
Optional.
TheAppIDassociatedwithyoursiteorapp.Ifnotspecified,thentheperformancedatawillbereportedacrossallappsassociatedwiththepublisher’saccount.
Cansupportmultipleapp_ids,commaseparated:
eg.“app_id=appxxxxa,appxxxxc”
formatString.
Optional.
Responseformat.Ifnotspecified,thendefaultstoJSON.OtherresponseformatssuchasCSVandXMLaresupported.
Supportedvalues:json,xml,csv
date
String.
Requiredunlessintervalparameterisspecifiedinwhichcase‘date’parameterwillbeoverridden.
StartDateinmmddyyyyformat.
Note:GMTtimezoneisassumed.
2.2Responsevariables
CSV JSON XML DescriptionInternalAppID internal_app_id InternalAppID AdColonyDBIDofAppAppName app_name AppName AppNameinputtedbyPublisherAppID app_id AppID ExternalAppID–SameIDthatis
calledbytheSDKStoreID store_id StoreID iTunesstoreIDforiOS
end_dateString.
Optional.
EndDateinmmddyyyyformat.Ifnotspecified,thenasingledayofdataisreported.
Note:GMTtimezoneisassumed;shouldlimitto3monthsinDaterangefordailyreports
intervalString.
Optional.
Astringspecifyingthedateintervaltoretrievedatafor.
Supportedvalues:today,yesterday,last24,this_week,last_week,this_month,last_month,last_30_days,this_year,last_year,all_time
date_groupString.
Optional.
Ifnotspecified,defaultsto“aggregate”.If“day”isspecified,reportwillbreakdownbydaily.
Supportedvalues:day,aggregate
group_by
String.
Optional.
Ifnotspecified,defaultsto“app”.Passin“zone”togetareportbreakdownbyzoneID.
Supportedvalues:app,zone,country
Note:cansupportmultiplegroup_byorcommaseparatedvalues
Eg:“group_by=app&group_by=country”Eg:“group_by=app,country”
*Dataforgroup_by=zone,countryisonlyavailablebeginningMay2015.
BundleIDforAndroid*ThisIDisonlyavailableiftheapphasbeensyncedwiththestoreusingtheappsyncoptionintheAdColonyportal.
Platform platform Platform iOSvAndroidvAmazonInternalZoneID internal_zone_id InternalZoneID AdColonyDatabaseIDforZoneZoneID zone_id ZoneID ExternalZone–ThisisthezoneID
usedbytheSDKZoneName zone_name ZoneName ZoneNameinputtedbypublisherStartDate start_date StartDate StartDateofthereportdate
range(intheYYYY-MM-DDformat)
EndDate end_date EndDate EndDateofthereportdaterange(intheYYYY-MM-DDformat)
Earnings($) earnings Earnings TotalEarningseCPM($) ecpm eCPM Effectivecostperthousand
impression(doesnotincludehouseimpressions)
Calculation:[Earnings/(Impressions-HouseImpressions)/1000)]
FillRate(%) fill_rate FillRate CalculatedbyImpressions/Requests
Requests requests Requests Numberofadrequestmadeagainsttheadcache
Impressions impressions Impressions Totalnumberofimpressions(includinghouse)
HouseImpressions house_impressions HouseImpressions Totalnumberofhouseimpressions
CVVs cvvs CVVs Totalnumberofcompletedvideoviews(includinghouse)
HouseCVVs house_cvvs HouseCVVs Totalnumberofhousecompletedvideoviews
CompletionRate completion_rate CompletionRate CalculatedbyImpressions/CVVsClicks clicks Clicks TotalNumberofclicksCTR ctr CTR CalculatedbyClicks/ImpressionsCountry country Country CountryCode
2.2.1SampleRequestandResponseformatinCSV
Example1:retrievedailyperformancereportonallappson7/1/2013
http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&format=csv&date_group=day
Example2:retrievedailyperformancereportonallappsforaselecteddaterangefrom7/1/2013to7/2/2013http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=csv&date_group=day
Example3:retrieveaggregateperformancereportonallappsforaselecteddaterangefrom7/1/2013to7/2/2013http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=csv&date_group=aggregate
Note:DatefieldsinAggregatereportspecify“StartDate”and“EndDate”ineachresponserecordwhereDailyreportonlyhas“Date”field.
Example4:retrievedailyperformancereportonaspecifiedappon7/1/2013withzonebreakdownhttp://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&format=csv&group_by=zone&date_group=day&app_id=appxxxa
Note:YoumustusetheAppIDtospecificitytheapp_idparameter,nottheInternalAppID
Example5:retrievedailyperformancereportonaspecifiedappforaselecteddaterangefrom7/1/2013to7/2/2013http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=csv&date_group=day&app_id=appxxxa
Example6:retrieveaggregateperformancereportonaspecifiedappforaselecteddaterangefrom7/1/2013to7/2/2013http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&endDate=07022013&format=csv&date_group=aggregate&app_id=appxxxa
Example7:retrievedailyperformancereportaselecteddaterangefrom7/1/2013to7/2/2013withcountryandappbreakdownhttp://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=csv&date_group=day&group_by=country&group_by=app
Example8:retrievedailyperformancereportonaspecifiedappforaselecteddaterangefrom7/1/2013to7/2/2013withcountrybreakdownforspecifiedappidshttp://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=csv&date_group=day&group_by=country&group_by=app&app_id=appxxxa,appxxxc
Example9:retrievedailyperformancereportaselecteddaterangefrom7/1/2013to7/2/2013withcountryandzonebreakdown
http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=csv&date_group=day&group_by=country&group_by=zone
2.3Well-formattedResponses
BothsampleXMLandJSONresponsesamplesareshownbelow.
2.3.1SampleXMLResponse–Example2:retrievedailyperformancereportonallappsforaselecteddaterangefrom7/1/2013to7/2/2013http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=xml&date_group=day
Note:DatefieldsinAggregatereportspecify“StartDate”and“EndDate”ineachresponserecordwhereDailyreportonlyhas“Date”field.
<Response xmlns="http://www.adcolony.com"> <Status>success</Status> <Reports>
<Report> <InternalAppID>12345</InternalAppID> <AppName>App 1</AppName> <AppID>appxxxa</AppID> <Platform>ios</Platform> <InternalZoneID>1234</InternalZoneID> <ZoneID>vzxxxa</ZoneID> <ZoneName>Zone 1</ZoneName> <Date>2015-07-01</Date> <Earnings>0</Earnings> <eCPM>0</eCPM> <FillRate>100</FillRate> <Requests>1</Requests> <Impressions>1</Impressions> <HouseImpressions>0</HouseImpressions> <CVVs>0</CVVs> <HouseCVVs>0</HouseCVVs> <CompletionRate>0</CompletionRate> <Clicks>0</Clicks> <CTR>0</CTR> <Country>CA</Country>
</Report> <Report>
<InternalAppID>12345</InternalAppID> <AppName>App 1</AppName> <AppID>appxxxa</AppID> <Platform>ios</Platform> <InternalZoneID>1234</InternalZoneID> <ZoneID>vzxxxb</ZoneID> <ZoneName>Zone 2</ZoneName> <Date>2015-07-01</Date> <Earnings>0</Earnings> <eCPM>0</eCPM> <FillRate>100</FillRate> <Requests>1</Requests> <Impressions>1</Impressions> <HouseImpressions>0</HouseImpressions> <CVVs>0</CVVs> <HouseCVVs>0</HouseCVVs>
<CompletionRate>0</CompletionRate> <Clicks>0</Clicks> <CTR>0</CTR> <Country>CA</Country>
</Report> </Reports>
</Response>
2.3.3SampleJSONResponse–Example5:retrievedailyperformancereportonaspecifiedappforaselecteddaterangefrom7/1/2013to7/2/2013http://clients-api.adcolony.com/api/v2/publisher_summary?user_credentials=<API_KEY_HERE>&date=07012013&end_date=07022013&format=json&date_group=day&app_id=appxxxa
Note:DatefieldsinAggregatereportspecify“start_date”and“end_date”ineachresponserecordwhereDailyreportonlyhas“date”field.
status": "success",
"results": [
{ "internal_app_id": 12345, "app_name": "app name", "app_id": "appxxxa", "platform": "android", "internal_zone_id": 12345, "zone_id": "vzxxxa", "zone_name": "Zone name", "date": "2015-07-15", "earnings": 0, "ecpm": 0, "fill_rate": 100, "requests": 1, "impressions": 1, "house_impressions": 0, "cvvs": 0, "house_cvvs": 0, "completion_rate": 0, "clicks": 0, "ctr": 0, "country": "BR"
},
{ "internal_app_id": 12345, "app_name": "app name", "app_id": "appxxxa", "platform": "android", "internal_zone_id": 23456, "zone_id": "vzxxxb", "zone_name": "Zone name 2", "date": "2015-07-01", "earnings": 0, "ecpm": 0,
"fill_rate": 100, "requests": 1, "impressions": 1, "house_impressions": 0, "cvvs": 1, "house_cvvs": 0, "completion_rate": 100, "clicks": 0, "ctr": 0, "country": "BR"
},
2.4Errors
TheReportingAPIwillreturnanerrorinthefollowingsituations:
StatusCode Message401 ‘user_credentialsisincorrect.’200 ‘Noappsfoundforuser_credentials.’400 ‘Invalidapp_id.’400 ‘Invalidparameter_nameprovided.’400 ‘Invaliddateformat.Thecorrectformatismmddyyyy.’400 ‘dateisgreaterthanend_date.’400 ‘Thereportrequestedexceedstheallowedcapacitylimit.
Pleasetrytoreducethereportsizebydecreasingthedaterange,specifyingcampaignids,orreducingyourgroupings.’
429* ‘Yourorganization’sAPIqueuehasfilledup–pleasewaitawhile,[email protected]’
*APIQueueLimit
Tobestsupportincomingrequestsacrossallusers,aqueuewasimplementedperAPIKey.Asdesigned,uptofivereportscanbeactivelyprocessingatthesametime.Additionalreportingrequestmadewhilefivereportsareactivelyrunningareaddedtoaqueuetobecomeactiveonceanexistingreportcompletes.Thesupportqueuelengthis25reports.Whenfivereportsareactivelyrunning,andthequeuecounthashit25reports,anyadditionalrequestwillreturna429error.
Therecommendedmethodofpullingconcurrentreportsistoruninbatchesbetween15-20reportsupfront,andthenmakeadditionalrequestsasreportsfromtheinitialbatchcomplete.
2.4.1SampleXMLErrorresponse
<Response xmlns="http://www.adcolony.com"> <Status>error</Status> <StatusCode>401</StatusCode> <Result>user_credentials is incorrect</Result>
</Response>
2.4.2SampleJSONErrorresponse
{ status:“error”, status_code:401, result:“user_credentialsisincorrect.”}