Monetization Reporting API¶
The Yahoo Monetization Reporting API provides programmatic access to YAP’s monetization data.
All interaction with the API is via HTTPS GET requests, the entire query is just a URL, making it easy to save and share queries.
To get the access to your comany data you need to acquire the programmatic app token. The programmatic token should be included in the header as:
Authorization: Bearer programmatic_token_here
Construct the API request¶
The API request comprises of elements that can be combined to query your monetization data. Everything in the API is case-sensitive.
endPoint/view/timeGrain/dimension?metrics=[comma-separated-metrics]&dateTime=[…]&filters=[…]sort=[…]&format=[..]&timeZone=[]
The endpoint is https://api-metrics.flurry.com/public/v1/data/
Request¶
Name |
Required |
Value |
Description |
---|---|---|---|
view |
required |
publisherRecent, publisherHistory |
Publisher Recent - up to 15 days of most recent hourly and daily data; Publisher History - up to 400 days of daily, weekly, monthly data |
timeGrain |
required |
hour, day, week, month, quarter,year |
Time grain is the period over which metrics are aggregated. For example, If hour is specified the metrics is aggregated in hour increments |
dimension |
required |
company, app, country, platform, adNetwork, adUnit, placement, assetType |
Dimension groups the metrics. Multiple dimensions can be requested. If multiple dimensions are requested the format is dimension1/dimension2/dimension3/… |
metrics |
required |
impressions, clicks, revenueInUSD, adsRequested, adsReceived, videoViews,videoStarts, video25PViews, video50PViews, video75PViews, videoCompletions, videoViewRate, videoStartRate, video25PRate, video50PRate, video75PRate, videoCompletionRate, fillRate, eCPM, ctr, impressionFillRate |
Comma-separated list of metrics to be provided in the response. The metrics are of three different types: Delivery, Video, Clicks, see deatils below for each. |
dateTime |
required |
fromDate/toDate |
dateTime=fromDate/toDate Date format YYYY-MM-DD if grain=Month, use Format YYYY-MM |
filters |
optional |
filters=dimensionName|dimensionField-filterOperation[some,list,of,url,encoded,filter,strings]. For example: filters=company|id-in[48256],adUnit|id-in[47891] |
Filters allow you to constrain the data processed by the system. Depending on what resource is being requested, filters may constrain the rows in the response, or may constrain the data that the system is processing. The general format of a single filter is: dimensionName|dimensionField-filterOperation[some,list,of,url,encoded,filter,strings] |
sort |
optional |
sort=impressions|desc sort=impressions|desc&topN=4 |
Comma-separated sort list. The metric sorted by needs to be in the list of requested metrics |
format |
optional |
csv, json |
Format of the output, The default response format is JSON |
timeZone |
optional |
timeZone=-08:00 |
This param is relevant for publisherRecent view only, publisherHistrory view reports all data in PDT. Time zone Ids available at: http://joda-time.sourceforge.net/timezones.html |
token |
required |
The token provides the authorization to access the company’s date. |
The programatic token should be included in the header as mentioned above. See instructions documented here how to acquire the token. |
Publisher Revenue = Post TAC Publisher Revenue (Rev Share on Gross Revenue. Other deductions applied where applicable)
eCPM = (Publisher Revenue/Impressions) * 1000
CTR = (Clicks/Impressions) * 100
Fill Rate = (Ads Returned/Ads Requested) * 100
Impression Fill Rate = (impressions/demandSourceAdsRequested) * 100
View¶
The Yahoo App Publishing supports two views into the publisher’s performance:
Publisher Recent - up to 15 days of most recent hourly or daily data
Publisher History - retains up to 400 days worth of monetization daily, weekly, monthly, quarterly or yearly data
Time Grain¶
Time grain is the granularity or “bucket size” of each response row, time grain is the period over which metrics are aggregated. Available time grains for publisherRecent view:
hour
day
week
Available time grains for publisherHistory view:
day
week
month
quarter
year
Dimension¶
Dimension groups the metrics data. At least one dimension needs to be provided in the request. The enabled dimensions are:
Name |
Description |
Value |
---|---|---|
company |
provides the company wide view of the metrics |
id, name (default) |
app |
breaks down the metrics by the app |
id, name (default), company|id, apiKey, platform|id, platform|name |
country |
breaks down the metrics by the country |
id, name (default), iso |
platform |
provides breakdown by the platform where the ads are served. Valid values are iOS, Android, Web |
id, name (default) |
adNetwork |
provides breakdown by the network where the ads are sourced from. Currently valid values are: Gemini, RTB, Direct |
id, name (default) |
adUnit |
provides breakdown by the ad unit |
id, name (default), app|id, company|id, status|id, status|name |
placement |
provides breakdown by the placement type (i.e ‘Banner Top’, ‘Banner Bottom’, ‘Full Screen’, ‘Stream’) |
id, name (default), code |
assetType |
provides a description of the asset criteria (i.e ‘Card’, ‘Basic’, ‘Detailed Card’) |
id, name (default), code |
For example to view hourly performance by the platform:
https://api-metrics.flurry.com/public/v1/data/publisherRecent/hour/platform?metrics=impressions,revenueInUSD,adsRequested,adsReceived,...
Or by app:
https://api-metrics.flurry.com/public/v1/data/publisherRecent/hour/app?metrics=impressions,revenueInUSD,adsRequested ,...
Multiple dimensions can be requested. If multiple dimensions are requested the format is dimension1/dimension2/dimension3/… For example: To view daily breakdown by the company, app, platform, adUnit:
https://api-metrics.flurry.com/public/v1/data/publisherRecent/day/company/app/platform/adUnit?metrics=impressions,revenueInUSD,adsRequested,adsReceived,
There are instances when you want to know the possible values for dimensions before running metric queries. For example: list names and api keys for all apps on your company account
https://api-metrics.flurry.com/public/v1/data/publisherRecent/day/platform/assetType/app;show=name,apiKey?metrics=impressions,fillRate,clicks,revenueInUSD....
In general, to see a value other than defalut name returend for the given dimension, add
;show=all
or
;show=id (any other value listed in the value column above for the given dimension
after the dimension name
https://api-metrics.flurry.com/public/v1/data/publisherHistory/day/app/country;show=all?metrics=impressions,fillRate,clicks,revenueInUSD&dateTime=2017-05-01/2017-05-02
https://api-metrics.flurry.com/public/v1/data/publisherHistory/day/app/country;show=iso?metrics=impressions,fillRate,clicks,revenueInUSD&dateTime=2017-05-01/2017-05-02
Metrics¶
Metrics are the data points, and include things like impressions, revenue, ctr,.., etc.
Comma-separated list of metrics is provided in the response. The metrics are of three different types: Delivery, Video, Clicks.
Delivery metrics: Impressions, Publisher Revenue USD, Ads Requested, Ads Returned, eCPM, Fill Rate, Clicks, CTR, Video Starts, Video Start Rate, Video Completed Views, Video Completion Rate
Video metrics: Impressions, eCPM, Clicks, CTR, Video Starts, Video Start Rate, Video Views, Video View Rate, 25P Views, 25P Rate, 50P Views, 50P Rate, 75P Views, 75P Rate, Video Completed Views, Video Completion Rate
Click metrics: Clicks, CTR.
dateTime (The Interval)¶
dateTime of a data query is the date/time range for data to include in the query. The interval is expressed as a pair of fromDate and toDate instants in time, using the ISO 8601 format, where the fromDate instant is inclusive and the toDate is exclusive.
One important thing to note about intervals is that they must align to the time grain specified in the query. If you ask for monthly time grain, the interval must start and stop on month boundaries, and if you ask for weekly time grain, the interval must start and stop on a Monday, which is when our week starts and stops.
Filters¶
Filters allow you to filter by dimension values. All dimensions (company, app, country, platform, adNetwork, adUnit) minimally have an ‘id’ property (a key which uniquely identifies a dimension value) and a ‘name’ property (a human-readable description (not necessarily unique)). Other dimension fields may exist as well. All of these fields can be used to filter rows reported on, and all of these fields are included in the data query result set for each dimension.
Id is the numeric value for each element as used in Flurry to uniquely capture the dimension
The general format of a single filter is: dimensionName|dimensionField-filterOperation[some,list,of,url,encoded,filter,strings]
For example: &filters=company|id-in[109318] &filters=app|name-notin[SamplesApp]
These filters can be combined by comma-separating each individual filter, and the filter strings are URL-encoded, comma-separated values: dimension1|id-contains[foo,bar],dimension2|id-notin[baz],dimension3|desc-startsWith[Once%20upon%20a%20time,in%20a%20galaxy]
For example: &filters=company|id-in[109318],app|id-notin[371877,454588]
These are the available filter operations: in: In filters are an exact match on a filter string, where only matching rows are included notin: Not In filters are an exact match on a filter string, where all rows except matching rows are included
Sorting¶
You can sort by the columns that are required in the metrics.
Example:
https://api-metrics.flurry.com/public/v1/data/publisherHistory/day/company/app/country/platform/adNetwork/adUnit?metrics=impressions,revenueInUSD,adsRequested,adsReceived&dateTime=2016-08-16/2016-08-26&filters=company|id-in[109318]&sort=impressions|desc&topN=4
Parse API Response¶
For the request of the following format :
endPoint/view/timeGrain/dimension_1/dimension_2/dimension_3/?metrics=metric_1,metric_2,metric_3,metric_4&dateTime=[…]&filters=[…]sort=[…]&format=[..]
The response format is
{
"rows":
[
{
"dateTime": "2016-05-12 09:00:00.000-07:00",
"dimension_1|name": “DIMENSION_1_NAME",
"dimension_2|name": "DIMENSION_2_NAME",
"dimension_3|name": "DIMENSION_3_NAME",
"metric_1": metric_1_value,
"metric_2": metric_2_value,
"metric_3": metric_3_value,
"metric_4": metric_4_value
},
{ ….. }
]
}
Name |
Description |
---|---|
dateTime |
Format YYYY-MM-DDThh:mm:ss.sTZD. If week is the selected grain: Week rollup of dates. Aggregate in blocks of Start Date (inclusive) + 6 days. Format <YYYYMMDD> - <YYYYMMDD> If month is the selected grain: Group by calendar month. Current month=MTD. Format YYYY-MON |
company|name |
Publisher Name |
app|name |
The application name |
country|name |
Country the data is reported for |
platform|name |
iOS | Android |
adNetwork|name |
Example values Gemini, Flurry Marketplace, Direct |
adUnit|name |
Ad Unit Name |
placement|name |
Placement Name |
assetType|name |
Asset criteria name for an Ad Unit |
Impressions |
Number of impressions. |
Clicks |
Number of clicks. |
Publisher Revenue USD |
Revenue USD for the publisher post TAC adjusted for Rev Share, ODA, and Contra deductions. |
Ads Requested |
Total number of ads requested. |
Ads Returned |
Total number of ads returned. |
Publisher eCPM |
(Publisher Revenue/Impressions) * 1000 |
CTR |
(Clicks/Impressions) * 100 |
Fill Rate |
(Ads Returned/Ads Requested) * 100 |
Video |
Video Starts, Video Start Rate, Video Views, Video View Rate, 25P Views25P Rate, 50P Views, 50P Rate, 75P Views, 75P Rate, Video Completed Views, Video Completion Rate |
Error Code |
Error codes are listed at the end of this document |
Note
The API returns the row if there is at least one non-zero metric value for the requested columns. In other words if all the metrics for the given row are 0 the row is not present in the response.
Examples¶
Example 1 Multiple dimensions request:
https://api-metrics.flurry.com/public/v1/data/publisherHistory/day/company/app/country/platform/adUnit?metrics=impressions,revenueInUSD,adsRequested,adsReceived,fillRate,clicks,ctr&dateTime=2016-09-01/2016-09-02&filters=company|id-in[109318]&sort=impressions|desc&topN=4
Corresponding response:
{
"rows": [{
"dateTime": "2016-09-01 00:00:00.000-07:00",
"company|name": "FlurrySamples",
"app|name": "iOSFlurrySamplesApp",
"country|name": "India",
"platform|name": "iPhone",
"adUnit|name": "InStream",
"impressions": 50,
"revenueInUSD": 0.00456,
"adsRequested": 1160,
"adsReceived": 236,
"fillRate": 20.344827586206897,
"clicks": 1,
"ctr": 2.0
},
{
"dateTime": "2016-09-01 00:00:00.000-07:00",
"company|name": "FlurrySamples",
"app|name": "SandeepTestApp",
"country|name": "United States",
"platform|name": "Android",
"adUnit|name": "Clips_15nonSkip_30nonSkip",
"impressions": 1,
"revenueInUSD": 0.0,
"adsRequested": 2,
"adsReceived": 2,
"fillRate": 100.0,
"clicks": 0,
"ctr": 0.0
}, {
"dateTime": "2016-09-01 00:00:00.000-07:00",
"company|name": "FlurrySamples",
"app|name": "iOSFlurrySamplesApp",
"country|name": "Unknown",
"platform|name": "iPhone",
"adUnit|name": "InStream",
"impressions": 0,
"revenueInUSD": 0.0,
"adsRequested": 11,
"adsReceived": 0,
"fillRate": 0.0,
"clicks": 0,
"ctr": 0.0
}, {
"dateTime": "2016-09-01 00:00:00.000-07:00",
"company|name": "FlurrySamples",
"app|name": "iOSFlurrySamplesApp",
"country|name": "United States",
"platform|name": "iPhone",
"adUnit|name": "InStream",
"impressions": 0,
"revenueInUSD": 0.0,
"adsRequested": 2,
"adsReceived": 0,
"fillRate": 0.0,
"clicks": 0,
"ctr": 0.0 }]}
Example 2
Publisher Recent view with the time zone (this query returns valid data only when the date / time selected is in the last 15 days frame:
https://api-metrics.flurry.com/public/v1/data/publisherRecent/hour/company/app/platform/adUnit?metrics=impressions,revenueInUSD,adsRequested,adsReceived,fillRate,clicks,ctr&dateTime=2016-09-09/2016-09-10&filters=company|id-in[109318]&sort=impressions|desc&topN=1&timeZone=-12:00
Corresponding Response:
{
"rows": [{
"dateTime": "2016-09-09 00:00:00.000-12:00",
"company|name": "FlurrySamples",
"app|name": "iOSFlurrySamplesApp",
"platform|name": "iPhone",
"adUnit|name": "InStream",
"impressions": 0,
"revenueInUSD": 0.0,
"adsRequested": 6,
"adsReceived": 0,
"fillRate": 0.0,
"clicks": 0,
"ctr": 0.0
}, {
"dateTime": "2016-09-09 01:00:00.000-12:00",
"company|name": "FlurrySamples",
"app|name": "iOSFlurrySamplesApp",
"platform|name": "iPhone",
"adUnit|name": "InStream",
"impressions": 0,
"revenueInUSD": 0.0,
"adsRequested": 1,
"adsReceived": 0,
"fillRate": 0.0,
"clicks": 0,
"ctr": 0.0
}, {
"dateTime": "2016-09-09 22:00:00.000-12:00",
"company|name": "FlurrySamples",
"app|name": "AndroidFlurrySamplesApp",
"platform|name": "Android",
"adUnit|name": "Stream",
"impressions": 0,
"revenueInUSD": 0.0,
"adsRequested": 8,
"adsReceived": 0,
"fillRate": 0.0,
"clicks": 0,
"ctr": 0.0
}]
}
Errors¶
Code |
Name |
What to do |
---|---|---|
400 |
BAD REQUEST |
You have some sort of syntax error in your request. We couldn’t figure out what you were trying to ask. Check your request format. |
401 |
UNAUTHORIZED |
We don’t know who you are, so send your request again, but tell us who you are. Usually this means you didn’t include proper token authentication information in your request |
403 |
FORBIDDEN |
We know who you are, but you can’t come in. This is usually because you’re making a request to access data from a company or app to which you do not have access. |
404 |
NOT FOUND |
We don’t know which resource you are requesting. You probably have a typo in your URL path. |
416 |
REQUESTED RANGE NOT SATISFIABLE |
We can’t get that data for you. Time range is too large or not available for reporting. |
422 |
UNPROCESSABLE ENTITY |
We understood the request (ie. syntax is correct) but something else about the query is wrong. Likely something like a dimension mis-match or a metric / dimension not being available in the requested table. |
429 |
TOO MANY REQUESTS |
You’ve hit the rate limit. Wait a little while for any requests you may have sent to finish and try your request again. |
5xx |
INTERNAL SERVER ERROR |
Some other error on our end. We try to catch and investigate all of these, but we might miss them, so please let us know if you get 5XX errors. |
500 |
MAXIMUM NUMBER OF ROWS REACHED |
Our API retruns max 50,000 rows in the response. Modify your query to request a smaller scope |
507 |
INSUFFICIENT STORAGE |
The query was deemed too costly to run and rejected. |
Additional Clarification/ Tips¶
Case sensitive API is case sensitive. This means that metric, dimension and API request parameter names must be spelled as specified in the document. sessions is not the same as Sessions is not the same as SeSsIoNs.
Specifying time intervals: dateTime follows ISO 8601 for start and end period. Start date time period is included but end date time interval is excluded from query interval
Week/ Month time grains require specifying the exact start and end boundary dates for query to be well formed. Month queries must specify first of the month for both start and end period. Week queries must specify dates for Monday of the week for corresponding start and end periods.
Max interval supported at this time is 90 days in one single request. Since the API request is a synchronous call to server, limiting this period allows for faster response to queries. For gathering data for longer periods, please split query for multiple time periods.
Missing timestamps For scenarios where there are no results for a combination of timestamp, dimensions and any filter criteria, timestamps are omitted completely. This is done to reduce size of results and for faster response to queries.
Filter can only be applied on dimensions that are included in the results requested.
Sorting applies for results within a specific timestamp. This means that results are always ordered first by timestamp and then by any sort criteria that you added to the API request.
To sort on a metric, requires the metric to be part of API data request.
Additional dimension attributes can be requested by adding show clause next to dimension breakdown on the API request. Without show clause, only dimension name attribute will be included on the result. Show clause must include comma separated dimension attributes or all.
Rate limits To prevent abuse of the system, the API only allows each user to have a certain number of data requests being processed at any one time. If you try to make another request that would put you above the allowed limit, you will be given an error response with an HTTP response status code of 429.
- The following headers will be returned with a 429 response:
X-RateLimit-Limit The maximum number of credits that the consumer is permitted to charge. All requests consume at least 1 credit but can cost more depending on the resources consumed.
X-RateLimit-Remaining The number of credits remaining. This number can go negative.
X-RateLimit-RefillPerMinute The rate (credits/minute) at which credits are refilled.
Programmatic accounts are specific to one company only. Even though you may have access to multiple companies, a programmatic account grants API authorization to one company only. You can have multiple accounts that have access to different set of apps in case your company/ app team organization requires such a configuration.
Forgot/ lost/ compromised programmatic token requires that you delete the programmatic account that you/ company admin created create a new programmatic account and replace old token with token from this newly created programmatic account.