Chartboost API — Analytics Methods

Last Update:

 

The campaign analytics endpoint provides detailed reports that can be grouped by either app or creative. Be advised that when specifying a groupBy field, a job ID will be returned by the Queued Analytics system, as detailed in the "Before you begin" section.


HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/campaign
Example Request https://analytics.chartboost.com/v3/metrics/campaign?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer's user ID}}&userSignature={{CB customer's user signature}}

Parameters
Parameter Request Type Required? Description Default
aggregate String Optional Aggregate the results over time (daily, weekly, monthly) Daily
campaignId String Optional Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role) N/A
campaignType String Optional network, cross_promo, direct_deal network, direct_deal
dateMin String Required The minimum date (YYYY-MM-DD) N/A
dateMax String Required The maximum date (YYYY-MM-DD) N/A
groupBy String Optional One of the following: 'country' 'app' 'app,creative' 'target_creative' 'date' 'campaign' 'campaign_target' 'campaign_type' None
platform String Optional Filter by specific platforms (iOS, Google Play, Amazon) All
role String Optional advertiser or publisher Both

Response Fields
Parameter Description Returned for...
adTypeId 1 = interstitial
2 = more_apps
3 = in_play
4 = rewarded_video
5 = video_interstitial
Everyone
app App name Everyone
campaign Campaign name Everyone
campaignId Campaign ID (can be either To Campaign ID or From Campaign ID based on groupBy and role) Everyone
campaignTarget Campaign target name (only returned when grouping by campaign_target) Advertisers
campaignSubType user_acquisition or retargeting Everyone
clicksDelivered Clicks delivered Publishers
clicksReceived Clicks received Advertisers
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
creative Advertised creative name (only returned when grouping by creative) Advertisers
ctrDelivered Clickthrough rate for delivered impressions Publishers
ctrReceived Clickthrough rate for received impressions Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1,000 impressions Publishers
ecpmSpent Cost per 1,000 impressions Advertisers
impressionsDelivered Impressions delivered by the publisher Publishers
impressionsReceived Impressions received by the advertiser Advertisers
installDelivered Installs delivered Publishers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
videoCompletedDelivered Completed video views delivered Publishers
videoCompletedReceived Completed video views received Advertisers

▲ Back to top

 

The app analytics endpoint provides detailed reports that can be grouped by app, ad type, or ad location.


HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/app
Example Request https://analytics.chartboost.com/v3/metrics/app?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer's user ID}}&userSignature={{CB customer's user signature}}

Parameters
Parameter Request type Required? Description Default
aggregate String Optional Aggregate the results over time (daily, weekly, monthly) Daily
appId String Optional One or more (comma-separated) app IDs All
dateMax String Required The maximum date (YYYY-MM-DD) N/A
dateMin String Required The minimum date (YYYY-MM-DD) N/A
groupBy String Optional One of the following: app, ad_type,app, date, ad_location (Publishers only), platform, campaign_type None
platform String Optional Any of the following: iOS, Google Play, Amazon All
role String Optional advertiser or publisher Both

Response Fields
Parameter Description Returned for...
ad_type Creative ad type
Learn more about ad types ▶
Everyone, only when groupBy=ad_type,app
allInstalls Number of total installs accrued regardless of source (Chartboost or otherwise) Everyone
app App name Everyone
appBundleId No longer sent; user will see Deprecated in reports Everyone
appId Chartboost app ID Everyone
bootups Number of times a user launches your app on a device Everyone
campaignType network, cross_promo, direct_deal Everyone, only when groupBy=campaignType
clicksDelivered Clicks delivered Publishers
clicksReceived Clicks received Advertisers
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
ctrDelivered Clickthrough rate for delivered impressions Publishers
ctrReceived Clickthrough rate for received impressions Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1,000 impressions Publishers
ecpmSpent Cost per 1,000 impressions Advertisers
eventLocation The Chartboost named location of the ad being published in the app. Advertisers will see default in the response field. Everyone
impressionsDelivered Impressions delivered by the publisher Publishers
impressionsReceived Impressions received by the advertiser Advertisers
installDelivered Installs delivered Publishers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
platform iOS, Google Play, or Amazon Everyone
uniques Number of unique devices that booted up the app Everyone
videoCompletedDelivered Completed video views delivered Publishers
videoCompletedReceived Completed video views received Advertisers

▲ Back to top

 

The export installs endpoint provides a full list of all installs received and/or provided. Please note that this endpoint will always return a Job ID from the Queued Analytics system, as detailed in the "Before you begin" section.


HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/install
Example Request https://analytics.chartboost.com/v3/metrics/install?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer's user ID}}&userSignature={{CB customer's user signature}}

Parameters
Parameter Request type Required? Description Default
campaignIds String Optional One or more (comma-separated) campaign IDs All campaigns
campaignType String Optional networkcross_promo or direct_deal All
dateMax String Required The maximum date (YYYY-MM-DD) N/A
dateMin String Required The minimum date (YYYY-MM-DD) N/A
platform String Optional Any of the following: iOS, Google Play, Amazon All
role String Optional advertiser or publisher Both

Response Fields
Parameter Description Returned for...
Ad Type Creative ad type
Learn more about ad types ▶
Everyone
Click Timestamp Date & time (DD-MM-YYYY HH:MM:SS) Everyone
Cost Type Advertising bid type
Learn more about bid types ▶
Everyone
Cost Value Advertising bid amount Everyone
Country Two-letter country code of device Everyone
Date Date & time (DD-MM-YYYY HH:MM:SS) Everyone
From App Bundle Publishing app bundle ID Everyone
From App ID Publishing app ID Everyone
From App Name Publishing app name Everyone
From Campaign ID Publishing campaign ID Publishers
From Campaign Name Publishing campaign name Publishers
From Campaign Type networkcross_promodirect_deal Publishers
GAID Google Advertising ID Everyone (Publisher only if Behavioral Targeting is disabled)
IFA iOS Identifier for Advertisers (if iOS 10 Limit Ad Tracking is disabled) Everyone (Publisher only if Behavioral Targeting is disabled)
MAC MAC address (Deprecated) N/A
Model Device model Everyone
OS Device operating system Everyone
To App Bundle Advertising app bundle ID Everyone
To App ID Advertising app ID Everyone
To App Name Advertising app name Everyone
To Campaign ID Advertising campaign ID Advertisers
To Campaign Name Advertising campaign name Advertisers
To Campaign Target Advertising campaign target ID Everyone
To Campaign Type networkcross_promodirect_deal Advertisers
UUID Device Universal Unique Identifier (if available) Everyone (Publisher only if Behavioral Targeting is disabled)

▲ Back to top

 

In addition to the endpoints you'll find on the dashboard's API Explorer page, we've built one specially designed to return clean analytics data at the app, date, and country level. This endpoint can also be used on behalf of Chartboost customers by third-party attribution and mediation services that require country-level data.

Note for mediation networks: We strongly recommend that you omit the campaignType field, as the API will automatically return results for network,direct_deal.
Please note that there might be a discrepancy between app and campaign endpoints and your dashboard analytics. Use the campaign endpoint and group by country to retrieve app, country, and ad_type data.

HTTP method GET
Endpoint https://analytics.chartboost.com/v3/metrics/appcountry
Example Request https://analytics.chartboost.com/v3/metrics/appcountry?dateMin={{Minimum date}}&dateMax={{Maximum date}}&userId={{Chartboost customer's user ID}}&userSignature={{CB customer's user signature}}

Parameters
Parameter Request Type Required? Description Default
appIds String Optional One or more (comma-separated) app IDs All apps
dateMin String Required The minimum date (YYYY-MM-DD) N/A
dateMax String Required The maximum date (YYYY-MM-DD) N/A
campaignType String Optional network, cross_promo or direct_deal network,direct_deal
adTypeIds String Optional One or more (comma-separated) ad type IDs: 1 = interstitial, 3 = in_play, 4 = rewarded_video, 5 = video_interstitial 1,4,5
role String Optional advertiser or publisher publisher
adLocation String Optional One or more (comma-separated) adLocations
  • Case #1: (adLocation=<value which is not 'all'>) shows results aggregated by each adLocation presented for ONLY for the specified adLocation(s). Information for any adLocation(s) is only available if the adLocation(s) is one of the Top 3 adLocations used by the Publisher App. No data is returned for the remaining adLocation(s).
  • Case #2: (adLocation='all') shows result broken down by up to top 3 adLocation(s) for a Publisher App with the remaining data being aggregated under adLocation = 'other'
  • Case #3: (adLocation= empty or not-passed)aggregates all data under adLocation = 'overall'. No breakdown by adLocation is provided.
see case #3

Response Fields
Parameter Description Returned for...
adLocation The Chartboost named location of the ad being published in the app. Advertisers will see default in the response field. Everyone
adType interstitial, rewarded_video, video_interstitial Everyone
app App name Everyone
campaignType network, cross_promo, direct_deal Everyone
clicksDelivered Clicks Publishers
clicksReceived Clicks Advertisers
countryCode Two-letter country code, or "unknown" Everyone
cpcvEarned Ratio of money earned from completed video views to completed video views Publishers
cpcvSpent Ratio of money spent on completed video views to number of completed video views Advertisers
ctrDelivered Click-through rate Publishers
ctrReceived Click-through rate Advertisers
dt Date (YYYY-MM-DD) Everyone
ecpmEarned Earnings per 1000 impressions Publishers
ecpmSpent Cost per 1000 impressions Advertisers
impressionsDelivered Impressions Publishers
impressionsReceived Impressions Advertisers
installRateDelivered Install rate Publishers
installRateReceived Install rate Advertisers
installsDelivered Installs Publishers
installsReceived Installs Advertisers
moneyEarned Money earned Publishers
moneySpent Money spent Advertisers
platform iOS, Google Play, or Amazon Everyone
videoCompletedDelivered Completed video views Publishers
videoCompletedReceived Completed video views Advertisers

▲ Back to top

 


You might also like...