Reporting API

Owned by
Itay Nave
Last updated: May 29, 2024 by
Lior Weissbrod
9 min read

 

The Aniview Reporting API allows access to Aniview’s Ad Platform’s management functionality.

 

Login API

In order to use the API, it is required first to login into the publisher account with the account’s
credentials.

Request URL:
https://manage.aniview.com/api/token?format=json


Request Method:
POST

 

Headers:

Content-Type: application/json


Request payload (aka Body - Raw):

{ "id": "<your@email.com>", "password": "<your_password>", "accountId": "<account_id>" }

If your user is associated with multiple accounts, networks or publishers, specify the exact Id you would like to login to

Response Status Code:
401 Unauthorized - if you can’t log in
200 - success!!!


Response Body:
The Response will include a JSON object of data containing the returned token and the
accountId you are connected to.
Example:

{ "data": { "token": "adadSodsaoSTdzQZUYi5IMdvadsRNCqs4tdaAvDSWTfNrxAsfeg5wzikAbE6NktCiYntw1KmhQ2A2v dvaNasdkg-JCmdPauDaddsGddadaaasd4Mi6EUUKbb2SWYIa3BGXTjeQrQIn53k9e94EuMjqRQ68PLEv8VZY3ie aRds_az2y3adCSq7mUCHg== ", "accountId": "5678fa70181f46dc32812345" } }


Once you get a valid token, there are 2 alternative ways of using it:
Each API call should be sent with the token GET / POST / PUT / DELETE.

  1. Set the header:
    X-Bamboo-Token: <token>

  2. Set-Cookie:
    token=<token>

Logout API

The Logout API is called to clean your session cookie and logout from the session

Request URL:
https://manage.aniview.com/api/token/0?format=json


Request Method:
DELETE

Request payload (aka Body - Raw):

{ “id”: 0 }

Status Code:
200 OK

Reporting API

Request URL:
https://manage.aniview.com/api/adserver/stats/report?startDate=1487548800&endDate=1487635199&dimensions=daily%2Chourly%2Ccou&metrics=inventory%2Cimpression%2Ccomplete&format=csv&query={}

https://manage.aniview.com/api/adserver/stats/report?format=csv&startDate=1582050453&endDate=1582136853&dimensions=daily%2Chourly%2Cncid&metrics=inventory%2CinventoryRequest%2Crequest%2Cbid%2Cimpression&query={"ncid":{"%24in":["56df1aba181f46c46f8b45af"]}}

Link parameters:

  1. Base URL: https://manage.aniview.com/api/adserver/stats/report

  2. startDate, endDate: Required parameters - Linux date of the start and end time of the report
    The following link can be used for the date conversion - https://www.epochconverter.com/
    E.g. startDate Sun, 21 Aug 2022 00:00:00 and endDate Mon, 22 Aug 23:59:59 would look as follows:

  3. tzo: -2 : Time zone offset in hours (optional)

  4. type: X (optional) - by default it’s Ad Server report (1), otherwise use:

    1. 6 for Content

    2. 2 for CDN

    3. 10 for SSAI

    4. 8 for Ads.txt

  5. dimensions: list of dimensions separated with an encoded comma (“,”) - you can use an encoder like https://meyerweb.com/eric/tools/dencoder/

  6. metrics: list of metrics separated with an encoded comma (“,”) - you can use an encoder like https://meyerweb.com/eric/tools/dencoder/

  7. format: csv or json

  8. query: HTML encoded query filter - you can use an encoder like
    Sample query (before encoding): &query={"ncid":{"$in":[Vb9fea5181f46d4388b5555"]}}
    In this sample, it filters the report to include data only from the specified network channel

Request Method:
GET

Status Code:
Should download the report in CSV format. The JSON format is also supported.

Notes:

  1. By using startDate and endDate parameters, It is possible to retrieve hourly data
    between specific hours.

  2. If any dimension or metric does not exist – the value in the report will be “-“

Dimensions

Dimension

Description

Available for account

Dimension

Description

Available for account

daily

Row per Day (date - linux format)

all

monthly

Row per month

all

weekday

The day of the week

all

weekly

Row per days of the week, Monday to Sunday (configurable)

all

hourly

Row per hour

all

nasid

Ad Source ID

network

nasidName

Ad Source Name

network

nasidEnv

Ad Source Environment

network

nasidDesc

Ad Source Description

network

nasidCreatedAt

Ad Source Creation Time

all

nasidStatus

Ad Source Status

all

nasidProvider

Ad Source Provider

network

nasidType

Ad Source Type

network

nasidOwnerType

Ad Source Demand Owner

network

ncid

Channel ID

all

ncidName

Channel Name

all

ncidPublisher

Channel Publisher *(for publisher represents App/Site ID)

network

ncidPublisherName

Channel Publisher Name *(for publisher represents App/Site)

network

ncidCreatedAt

Channel Created At

all

ncidStatus

Channel Status

all

ncidEnv

Channel Environment

all

coasid

Partner Connection ID

network

coasidName

Partner Connection Name

network

pcid

Publisher Channel ID

network

pcidName

Publisher Channel Name

network

pasid

Publisher Connection ID

network

pasidName

Publisher Connection Name

network

nid/iid

Network/Publisher ID

network

nName/iname

Network/Publisher Name

network

cou

Country

all

coun

Country Name

all

cos

OS

 

osv

Operation system version

all

r

Domain/Bundle ID

all

grR

Grouped Domain/Bundle ID

all

sn

Sub Id

all

brn

Browser Name

all

adType

Ad Type

all

proto

Protocol (http/https)

all

mc

Media Creative

all

tgt

Tag Type

all

viewability

Viewability

all

he

App Name

all

wi

Player Dimensions

all

viewabilityQuarters

Viewability Quarters

all

piv

Player in View

all

sellerID

The ID of the Network/Publisher/App/site/etc. - needed for ads.txt/supply chain

network

sellerType

Intermediary, Publisher or Both - needed for ads.txt/supply chain

network

stk

Sticky

all

fv

Player Position

all

AV_D1

Creative Type

all

AV_D6

City

all

AV_D7

Region

all

aid

Advertiser

network

aidid

Advertiser ID

network

cd1

Custom1

all

cd2

Custom2

all

cd3

Custom3

all

cd4

Custom4

all

cd5

Custom5

all

cd6

Custom6

all

cd7

Custom7

all

cd8

Custom8

all

cd9

Custom9

all

cd10

Custom10

all

impressionCapLimit

 

network

impressionCapFrequency

 

network

impressionCapMode

 

network

requestCapLimit

 

network

requestCapMode

 

network

AV_D35

 

 

AV_D17

 

 

AV_D18

 

 

sTagName

 

 

sTagType

 

 

sTplName

 

 

sTplType

 

 

Studio player tag ID

AV_D17

all

Device Type

AV_D32

all

AV_D51-64

Reserved for SSAI

network

Metrics

Event

Metric

Description

Available for account

 

Event

Metric

Description

Available for account

 

playerLoaded

PlayerLoaded

Pixel should be implemented in player tag in order to support the metric: fired every time the player is loaded

all

 

playerStarted

PlayerStarted

Pixel fired once aniview.js is loaded

all

 

inventory

Inventory

Once there is the first serving request

all

 

inventoryRequest

InventoryRequest

The first serving call (when the waterfall is called)

all

 

request

Request

Every request to a Third-Party Ad Source

all

 

bid

Bid

When the Ad Source returns a valid response

all

 

bidRate

Bid Rate

= Bids/Requests*100

all

 

initAd

initAd ()

initAd

all

 

AdLoaded

AdLoaded

AdLoaded

all

 

startAd

startAd ()

startAd

all

 

impression

Impression

Impression (fired on AdImpression)

all

 

start

Start

Start event (fired on AdVideoStart)

all

 

adViImpression

Viewable Impression

When the player is viewable for at least 2 consecutive seconds

 

 

firstQuartile

First Quartile (25%)

First Quartile (25%)

all

 

midpoint

Mid Point (50%)

Midpoint (50%)

all

 

thirdQuartile

Third Quartile (75%)

Third Quartile (75%)

all

 

complete

Complete (100%)

Complete (100%)

all

 

completionRate

Completion Rate

=Complete/Impressions*100

all

 

fillRate

Fill Rate

= Impression/Inventory

 or

= impression/request (if Ad Source is a dimension)

all

 

opportunity

Opportunity

Fired once a Partner Connection is checked to see if any Ad Source within it can pass Optimization

network

 

tAvailable

Tags Available

Fired once one or more of the Ad Sources within a Partner Connection succeeded to be in the Waterfall

network

 

AdError

AdError

There was a VPAID Error

all

 

mediaPlayError

Media Play Error

There was an error while trying to play the media file

all

 

mediaTimeout

Media Timeout

While trying to play the media file there was a time error

all

 

AV_M1

Empty Waterfall

 

all

 

vpaidGeneralError

Vpaid General Error

General error of the player

all

 

vpaidLoadError

Vpaid Load Error

There was an error while trying to load the VPAID

all

 

vpaidLoadTimeout

Vpaid Load Timeout

There was a Timeout error while trying to load the VPAID JS.

all

 

vpaidInitAdError

Vpaid initAd Error

We called initAd () and the VPAID returned an AdError event

all

 

vpaidInitAdTimeout

Vpaid initAd Timeout

In the case that the VPAID does not respond with AdLoaded in the specified time, we will be an initAdTimeout error

all

 

vpaidStartAdError

Vpaid startAd Error

We called start ad startAd() there was and the VPAID returned AdError event

all

 

vpaidStartAdTimeout

Vpaid startAd Timeout

In the case that the VPAID does not respond with Ad Impression in the specified time, we will return a StartAdTimeout error

all

 

vpaidPlayError

Vpaid Play Error

There was an error while playing the ad

all

 

sec3

3 Sec

Pixel fired after the ad has played for 3 seconds

 

 

sec10

10 Sec

Pixel fired after the ad has played for 10 seconds

 

 

avr

AdsViewedRate

Ads Viewed Rate

all

 

aavt

AVGAdsViewedTime

AVG Ads Viewed Rate

all

 

dtavt

TotalAdsViewedTime

Total Ads Viewed Time

all

 

dtadt

TotalAdsDurationTime

Total Ads Duration Time

all

 

mute

Mute

Mute event

all

 

unmute

Unmute

Unmute

all

 

pause

Pause

Pause

all

 

resume

Resume

Resume

all

 

fullscreen

Full Screen

Full screen

all

 

rewind

Rewind

Rewind

all

 

click

Click

Click

all

 

ctr

CTR (Click-through-rate)

Click Through Rate

all

 

revenue

Revenue

Revenue

all

 

rwf

Revenue Without Fees

=Revenue - Accounting Fees

network

 

fee

Accounting Fees

Calculation of Fees based on Rules (See Acounting Fees Feature)

network

 

ncpm

Gross CPM ($)

Revenue CPM (Gross CPM)

all

 

rpm

RPM

Revenue by Inventory

all

 

rf

Request Fees

Request Fees

network

 

iccpm

Inventory Cost CPM

Inventory Cost (requires AV_IC to be passed in ref1)

network

 

ic

Inventory Cost

Inventory Cost CPM

network

 

chcost

Channel Cost

Channel Cost

network

 

chCpm

Channel Cost CPM

Channel Cost CPM

network

 

cost

Publisher/Partner Cost

Publisher/Partner Cost

network

 

costCpm

Publisher/Partner Cost CPM

Publisher/Partner Cost CPM

network

 

totalCost

Total Cost

=Publisher/Partner Cost + Channel Cost

network

 

totalCostCpm

Total Cost CPM

=Publisher/Partner Cost + Channel Cost

  CPM

network

 

profit

Profit

=Revenue - Total Cost

network

 

netCpm

Net CPM

= Revenue - Total Cost CPM

 

network

 

AV_M11 - AV_M20

Custom Events

Sum of Custom Event

network

 

avgViewability

Average viewability

Average viewability

all

 

viewabilityErr

Viewability Error

Sum of impression generated by undetected viewability (-1)

all

 

requestFillRate

Request FIll Rate

Impression/Request

all

 

AV_M41-43

in development

Reserved for SSAI

network

 

AV_M49

VIewavle Inventory

When the player is viewable for at least 2 consecutive seconds

 

 

Filters

Filter Name

Description

Possible Values

Filter Name

Description

Possible Values

cd1-cd10

Custom Dimensions

Any Value

sn

Sub ID

any Value

PHP Code Snippet:

 

Related articles