AdColony BidSheet Reporting API v1.0

 

Revision Date Description
May 6, 2021 Added BidSheet reporting API

 

  1. API Access URL
  2. BidSheet Summary Report
    1. Request parameters
    2. Response variables
    3. Well-formatted responses
      1. JSON
      2. XML
    4. Errors
      1. JSON
      2. XML
  3. Support

The use of the reporting API is intended for Advertisers running BidSheet ad groups on AdColony Video Ad Network to retrieve ad performance reporting data via an API. The API uses HTTP GET to make reporting requests and retrieve results from the server.

1. API Access URL

https://clients-api.adcolony.com/api/v2/bidsheet_summary?user_credentials=<api_key>&ad_group_id=<ad_group_id>&date=<mmddyyyy>

Note: Please refer to the Read-Only API Key in your account settings in the AdColony Portal to access your API_KEY

 

2. BidSheet Summary Report

The BidSheet summary reporting API provides performance data about a BidSheet ad group that belongs to an advertiser’s account. The reporting API allows for variable date range or specific date reports. Reports can only be generated for a specific ad group. Performance data can be grouped by different date intervals. For more information on all of these options, consult the request parameters below.

 

Note: A day is defined by the GMT time zone

2.1. Request Parameters

Parameter Data Element Description
user_credentials String

Required

Please use the API Key found in your account settings in the AdColony Portal to access the reporting API
ad_group_id String

Required

The Ad Group ID associated with the Ad Group
format String

Optional

Response format

If not specified, then defaults to JSON, but other response formats such as CSV and XML are supported

Supported values: json, xml, csv

date String

Required unless ‘interval’ parameter is specified, in which case ‘date’ parameter will be overridden

Start date in mmddyyyy format

Note: GMT time zone is assumed

end_date String

Optional

End date in mmddyyyy

Note: GMT time zone is assumed; should limit to 3 months in date range for daily report

interval String

Optional

A string specifying the date interval to retrieve data for

Supported values: today, yesterday, last24, this_week, last_week, this_month, last_month, last_30_days, this_year, all_time

date_group String

Optional

If not specified, defaults to ‘aggregate’

If ‘day’ is specified, report will break down by daily

Supported values: hour, day, aggregate

 

2.2. Response Variables

 

CSV JSON XML Description
Campaign ID campaign_id CampaignID AdColony Campaign ID
Campaign Name campaign_name CampaignName Name of Campaign in AdColony Portal
Ad Group ID ad_group_id AdGroupID AdColony Ad Group ID
Ad Group Name ad_group_name AdGroupName Name of Ad Group in AdColony Portal
Creative ID creative_id CreativeID AdColony Creative ID
Creative Name creative_name CreativeName Name of Creative in AdColony Portal
Advertiser Store ID advertiser_store_id AdvertiserStoreID iTunes ID (iOS) / Bundle ID (Android)
Start Date start_date StartDate Start date of report (if specified in the YYYY-MM-DD format)
End Date end_date EndDate End date of report (if specified in the YYYY-MM-DD format)
Date date Date When the date group is by day, in YYYY-MM-DD format. When date group is by hour, in YYYY-MM-DD HH format
Impressions impressions Impressions Number of Ad Starts
CVVs cvvs CVVs Number of Video Completes
Total Clicks total_clicks TotalClicks Number of Clicks
CTR ctr CTR Click Through Rate (Clicks / Impressions)
Spend ($) spend Spend Total number amount spent
Total Campaign Spend Limit total_campaign_spend_limit TotalCampaignSpendLimit Campaign Spend Limit (if set)
Total Group Spend Limit total_group_spend_limit TotalGroupSpendLimit Ad Group Spend Limit (if set)
eCPI ($) ecpi eCPI Effective Cost per Install (Spend / Install)
Installs installs Installs Total Number of Installs
Country country Country 2-Letter Country Abbreviation (ISO Alpha 2)
Platform platform Platform iOS, Android
Pricing pricing Pricing Pricing model
Bid bid Bid Bid amount
BidSheet Row Hash bidsheet_row_hash BidSheetRowHash Hash of targeting row from BidSheet
Publisher Store ID publisher_store_id PublisherStoreID If iOS, the store ID. If Android, the app package name
App Name app_name AppName Name of the application as it appears in the app store / google play, but if no name, portal name
App ID app_id AppID UUID of the app as from the AdColony portal
Zone ID zone_id ZoneID UUID of the zone from AdColony portal
Zone Name zone_name ZoneName Name of the zone as shown in the AdColony UI
Device Language device_language DeviceLanguage Language as defined in device settings
Zone Type zone_type ZoneType Full Screen / Banner
Zone Skip zone_skip ZoneSkip Skip / Non-skip zones
Session View Position session_view_position SessionViewPosition The order in which the ad was shown on the inventory. For example, session view position of 3 means the ad was shown 3rd and two other adcolony ads were shown before yours. Considers only the order of ads trafficked via the AdColony SDK
Device Type device_type DeviceType Phone, Tablet
Device Model device_model DeviceModel The model of the device
OS Version os_version OSVersion The version of the device operating system 
Segment ID segment_id SegmentID Segment ID
Segment Name segment_name SegmentName The name of the segment
First Quartile Video Complete first_quartiles FirstQuartileVideoComplete Impressions where 25% of video playback is complete (video only)
Midpoint Video Complete midpoints MidpointVideoComplete Impressions where 50% of video playback is complete (video only)
Third Quartile Video Complete third_quartiles ThirdQuartileVideoComplete Impressions where 75% of video playback is complete (video only)
SKAN Campaign ID skan_campaign_id SKANCampaignID SKAN campaign ID

 

2.3. Well-formatted Responses

Sample JSON and XML responses are shown below.

2.3.1. JSON

https://clients-api.adcolony.com/api/v2/bidsheet_summary?user_credentials=abcdefghijklmnopqrst&ad_group_id=1234&date=05062021&format=json

{  "status": "success",  "results": [    {      "campaign_id": 1234,      "campaign_name": "Campaign",      "ad_group_id": 1234,      "ad_group_name": "Group",      "creative_id": "",      "creative_name": "",      "advertiser_store_id": "123456789",      "start_date": "2021-05-06",      "end_date": "2021-05-06",      "impressions": 0,      "cvvs": 0,      "total_clicks": 0,      "ctr": 0.00,      "spend": 0.0000000,      "total_campaign_spend_limit": 500,      "total_group_spend_limit": 500,      "ecpi": 0,      "installs": 0,      "country": "US",      "platform": "ios",      "pricing": "cpi",      "bid": 1,      "bidsheet_row_hash": "48e1599cdb87c4d6c9f1292f7e54f58cabc3f8e725638a969b3ddfb6a3f92546",      "publisher_store_id": "",      "app_name": "",      "app_id": "",      "zone_id": "",      "zone_name": "",      "device_language": "",      "zone_type": "",      "zone_skip": "",      "session_view_position": "",      "device_type": "",      "device_model": "",      "os_version": "",      "segment_id": "",      "segment_name": "",      "first_quartiles": 0,      "midpoints": 0,      "third_quartiles": 0,      "skan_campaign_id": 1    }  ]}

2.3.2. XML

https://clients-api.adcolony.com/api/v2/bidsheet_summary?user_credentials=abcdefghijklmnopqrst&ad_group_id=1234&date=05062021&format=xml

<Response xmlns="http://www.adcolony.com">  <Status>success</Status>  <Reports>    <Report>      <CampaignID>1234</CampaignID>      <CampaignName>Campaign</CampaignName>      <AdGroupID>1234</AdGroupID>      <AdGroupName>Group</AdGroupName>      <CreativeID/>      <CreativeName/>      <AdvertiserStoreID>123456789</AdvertiserStoreID>      <StartDate>2021-05-06</StartDate>      <EndDate>2021-05-06</EndDate>      <Impressions>0</Impressions>      <CVVs>0</CVVs>      <TotalClicks>0</TotalClicks>      <CTR>0.00</CTR>      <Spend>0.0000000</Spend>      <TotalCampaignSpendLimit>500</TotalCampaignSpendLimit>      <TotalGroupSpendLimit>500</TotalGroupSpendLimit>      <eCPI>0</eCPI>      <Installs>0</Installs>      <Country>US</Country>      <Platform>ios</Platform>      <Pricing>cpi</Pricing>      <Bid>1</Bid>      <BidSheetRowHash>48e1599cdb87c4d6c9f1292f7e54f58cabc3f8e725638a969b3ddfb6a3f92546</BidSheetRowHash>      <PublisherStoreID/>      <AppName/>      <AppID/>      <ZoneID/>      <ZoneName/>      <DeviceLanguage/>      <ZoneType/>      <ZoneSkip/>      <SessionViewPosition/>      <DeviceType/>      <DeviceModel/>      <OSVersion/>      <SegmentID/>      <SegmentName/>      <FirstQuartileVideoComplete>0</FirstQuartileVideoComplete>      <MidpointVideoComplete>0</MidpointVideoComplete>      <ThirdQuartileVideoComplete>0</ThirdQuartileVideoComplete>      <SKANCampaignID>1</SKANCampaignID>    </Report>  </Reports></Response>

 

2.4. Errors

The Reporting API will return an error in the following situations:

 

Status Code Message
401 user_credentials is incorrect
400 Invalid id(s): ad_group_id
400 No Bidsheet group was found for specified ad_group_id
400 No Bidsheet was found for specified Bidsheet group
400 Invalid date format. The correct format is mmddyyyy
400 date is greater than end_date
400 The report requested exceeds the allowed capacity limit. Please try to reduce the report size by decreasing the date range
429* Your organization’s API queue has filled up — please wait a while, or contact [email protected]

 

* API Queue Limit

To best support incoming requests for all users, a queue was implemented per API Key. As designed, up to five reports can be actively processed at the same time. Additional reporting requests made while five reports are actively running are added to a queue to become active once an existing report completes. The supported queue length is 25 reports. When five reports are actively running, and the queue count has hit 25 reports, any additional request will return a 429 error.

The recommended method of pulling concurrent reports is to run in batches between 15-20 reports up front, and then make additional requests as reports from the initial batch complete.

 

2.4.1. Sample JSON Error

{  "status": "error",  "status_code": 401,  "result": "user_credentials is incorrect"}

 

2.4.2. Sample XML Error

<Response xmlns="http://www.adcolony.com"><Status>error</Status><StatusCode>401</StatusCode><Result>user_credentials is incorrect</Result></Response>

 

3. Support Inquiries

If you need support with your API integration please contact [email protected].