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.