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 programatic app token. The programatic token should be included in the header as:

Authorization: Bearer

Flurry Monetization API Query Builder

We’ve created an api console which you can use to build test queries and experiment with our API.

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 - 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.