AdColony Publisher Reporting API v2...As of v2.3, data for this API is updated continuously, and has...

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>

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.”}

AdColony Publisher Reporting API v2...As of v2.3, data for this API is updated continuously, and has...

Documents

Transcript of AdColony Publisher Reporting API v2...As of v2.3, data for this API is updated continuously, and has...