Download - AdColony Publisher Reporting API v2...As of v2.3, data for this API is updated continuously, and has about a 15 min delay to real time reporting. The publisher summary reporting API

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

Download - AdColony Publisher Reporting API v2...As of v2.3, data for this API is updated continuously, and has about a 15 min delay to real time reporting. The publisher summary reporting API

Top Related