Bidease reporting API documentation

Overview

This document describes the steps to retrieve data in CSV format containing performance and spending information. All requests use a GET method with query strings.

To exclude the header, add &noheader=true to the request.

Request URL Example

https://ui-api.bidease.com/api/reporting/v1/stats?api-token={API_TOKEN}&fromdate={FROM_DATE}&todate={TO_DATE}&rekls={REKL}&products={PRODUCT}&campaigns={CAMPAIGN}&group={GROUP1}&group={GROUP2}

• API_TOKEN: mandatory value which should be provided in each request. Provided by Bidease tech support ([email protected]) or by Bidease CSM.
• FROM_DATE: Start date (inclusive), formatted as YYYY-MM-DD.
• TO_DATE: End date (exclusive), also in YYYY-MM-DD format.

TO_DATE  should be greater than FROM_DATE!

TO_DATE & FROM_DATE should be in the range (today() - 2 years; today), but the whole data retrieval amount could vary and influence on the date from.

In addition, FROM_DATE and TO_DATE supports relative dates that could be described with the following notation with regular expressions:

^(today()(-\d+d)?$

This means that the API call uses the date in the API_TOKEN's timezone, and 'today' refers to the start of the day when the API call is made:

• 'today': YYYY-MM-DDl
• 'today-20d' is today minus 20 days

As a result, it is possible to specify relative dates. Here is an example of getting data from yesterday:

&fromdate=today-1d&todate=today

All dates and times are in token timezone (UTC+0 by default)!

Grouping (verticals)

You can group data using up to 7 values, such as:

• Application – bundle of the application where impression was served
• Carrier – carrier of connection
• City – city
• Country – country (ISO-3)
• Day – day of event
• Exchange – exchange name
• Hour – hour of event (in API_TOKEN timezone)
• Model – mobile phone model
• Region – region or subarea
• Make – mobile phone make
• CreativeHash – unique value of creative resources
• DeviceType – type of device (Mobile, Tablet)
• OperationSystem – operation system
• CampaignID – ID of campaign
• CampaignName – name of campaign
• CreativeID – ID of creative
• OperationSystemVersion – operation system version
• PlacementID – in application placement ID (eg. there could be different ad placement in one bundle (320x50 in the bottom and interstitial)
• HasIFA – has the device advertisement identifier been passed or not
• AdvertiserID - ID of advertiser on ui.bidease.com
• ProductID – ID of product on ui.bidease.com
• Currency – currency of the payment during payment event
• ConvHour – hour of conversion (install)
• ImpressionHour – hour impression
• ConvDay – day of conversion (install)
• ImpressionDay – day of impression

Grouping examples:

https://ui-api.bidease.com/api/reporting/v1/stats?api-token={API_TOKEN}&fromdate={FROM_DATE}&todate={TO_DATE}&group=Day&group=CampaignID&group=CampaignName

https://ui-api.bidease.com/api/reporting/v1/stats?api-token={API_TOKEN}&fromdate={FROM_DATE}&todate={TO_DATE}&group=CreativeID&group=HasIFA&group=PlacementID

Additionally, if the Bidease AdOps team is using custom bindings on campaigns, you can retrieve them in a separate grouping by using the group-by-param parameter with the appropriate value. For example:
&group-by-param=CustomCampaign

Filters

You can filter data using these parameters (zero or more values can be passed):

• rekls –  advertiser IDs from Bidease UI
• products – product IDs from Bidease UI
• campaigns – campaign IDs from Bidease UI
• bundles – app bundles from Google Play and Apple Store

Examples:

&campaigns=10&campaigns=11&bundles=com.bidease&bundles=1133415133&rekls=304&rekls=404

If no filters are provided, all available data is analyzed!

Time Attribution in Grouping

There are three types of time attribution:

• Event – the timestamp when an action (impression, click, conversion, purchase) was recorded.
• Impression – the timestamp when the impression occurred.
• Conversion – the timestamp when the conversion occurred.

Therefore it's possible to choose three types of grouping:

• Day – day of event (YYYY-MM-DD)
• ImpressionDay – day of impression (YYYY-MM-DD)
• ConvDay – the day of conversion and any related events, as well as the timestamp of events prior to the conversion (e.g., impression/click) (YYYY-MM-DD)

In the query string, use attr-type to select the attribution:

• ByEvent (default) – group by event timestamp
• ByImpression – group by impression timestamp
• ByConv – group by conversion timestamp

Example:

&group=ImpressionDay&attr-type=ByImpression

Extra Columns

You can add additional columns to the CSV by passing them as extra-column parameters. Values for extra-column parameter could be taken from Bidease UI. Example:

&extra-column=UniqClicks&extra-column=Ecpa4&extra-column=UniqImpressions

Sample Request

Here is an example request for getting data for advertisers 300 and 310 grouped by application, country, cretiveid, campaignid for the December 2019:

https://ui-api.bidease.com/api/reporting/v1/stats?&api_token=XXX-XXX-XXXX-XXX-XXXX&fromdate=2019-12-01&todate=2020-01-01&rekls=300&rekls=310&group=Application&group=Country&group=CreativeID&group=CampaignID

Response Format

The resulting CSV will include columns such as:

• spend –media cost in dollars
• impressions – number of impressions
• clicks – number of clicks
• conversions – number of installs
• revenue – value passed from MMP's. Required for agencies to calculate their revenue
• iap_sum – sum of in-app purchases
• iap – amount of in-app purchases
• goal1/2/3/4/5/6 – amount of in-app events from Bidease UI
• ctr – click-through rate
• ecpm – effective cost per thousand impressions
• ecpc – effective cost per click
• i2c – impressions to conversions ratio
• cpi – cost per install

After those columns, you will find the grouping columns in the same order as they appeared in your request.