Skip to main content

Ad revenue monetization network aggregate reporting API

John Smith

At a glance: Get aggregated ad revenue by ad monetization network (without the attribution media source). Use the reports to optimize monetization networks.

Ad revenue monetization network integration and reporting API

Ad revenue is often a significant source of revenue for app publishers. This API gives you insights as to how different ad monetization networks generate revenue.

To get ad revenue monetization network data:

  1. Integrate the ad network and in the Ad revenue tab, select Monetization revenue API.
    See complete partner integration instructions. 
  2. Use the API to get ad revenue monetization network aggregate reports.
  3. For campaign media sources optimization, use ad revenue campaign optimization.

BI developer considerations

  • Dates: dates or date ranges relate to the date revenue is reported by monetization partners.
  • Boolean values: true or false (case sensitive.)

The sections that follow contain the information necessary for you to prepare API requests.

Ad revenue API facts

Overview The API call consists of the path, headers, and a JSON containing the data query. Data returns by default with a CSV format (not file). 
Path

https://hq1.appsflyer.com/api/ad-revenue-agg/v1/data/app/app_id
Path parameters  (mandatory)
  • app_id: The app identifier listed in the ZendeskConnect dashboard. Insert it exactly as it displays in the dashboard.
  • Get a list of apps in your account.

Query parameters

[optional]

Results return in:

  • [Default] CSV structure having a tabular format. The first row contains the column names.
  • JSON structure
  • Example: format=json
  • https://hq1.appsflyer.com/api/ad-revenue-agg/v1/data/app/app_id?format=JSON
HTTP method POST
Headers
Request headers

Key

 Value Mandatory
Content-Type application/json Yes 
Authorization Bearer Yes 
Accept application/json Yes 
Authorization
Date limitations
  • Earliest date supported: The date you turned the feature on in ZendeskConnect
  • Maximum query range: 60 days
Rate limitation
  • API call-rate limited to 60 calls per minute and 50,000 calls per day per account 
  • Queries return up to 10,000 rows
Boolean values Always in lower case: true,  false
Data freshness
  • Intraday
  • Each time we request data from the partner, we request the current day and the previous two days. It means that data updates retroactively. Consider this in your data ingestion process. 
Ad revenue monetization API facts

Main parameters

Basic parameters

Parameter name

 Description Mandatory 

from 

Start date of the date range.

  • Format: String yyyy-mm-dd
  • Example: "from": "2020-11-02"
Yes

to

End date of the date range

  • For a single day: from and to values are identical. 
  • Format: yyyy-mm-dd
  • Example: "from": "2020-10-01", "to": 2020-10-31 is 31 days.
  • Maximum days in the range 60 days
 Yes
preferred_currency
  • Default currency: USD
  • If true, response returns in app-specific currency. Conversion to app-specific currency is performed from USD using the exchange rate at the time of the request. 
  • [Default] If false, response returns in USD.
 No
filters

Select filters from the dimensions list.

Format: Strings in a nested JSON. 

Example: "filters": { "geo": [ "za", "de" ], "ad_type": [ "banner", "video", "interstitial" ]

 No
groupings

Select one or more groupings from the dimension list.

Format: Strings in an array

Example: "groupings": [ "geo", "ad_type" ]

 Yes
metrics

Select one or more metrics from the metrics list.

Format: Strings in an array.

Example: "metrics": [ "impressions", "clicks", "ctr", "revenue" ]

 Yes
include_mediated

By default, at query time, the API filters mediated revenue data for enabled direct integrations. You can include mediated data in the report by passing the include_mediated parameter with the value true.

 No

Dimension list (filter and group)

  • Use filter parameters to get the necessary data.
  • Use groupings to include additional columns and make your reports less granular.
  • The geo and platform dimensions are always available. Other dimensions depend on the data provided by the monetization network. 
  • If no data is available for a given grouping, the response is n/a.
  • If the request doesn't include filters, the response includes the total revenue divided between the selected dimensions.
  • Monetization networks employ different data schemes. Consequently, besides for geo and platform, not all dimensions are available per monetization network.
Filtering and grouping dimensions available

Dimension

Format

Filter

Group

Description

geo

String

Yes

Yes

ISO 3166 2-letter country code. Use to filter by geo (country). Multiple values supported.

Example: "geo" : "US", "ZA"

ad_type

String

Yes

Yes

Supported values differ according to the monetization network.

Example: "ad_type" : "banner", "interstitial"

device_type

String

Yes

Yes

Values permitted: phone, tablet, other

Example: "device_type" : "tablet"

source_network

String

Yes

Yes

Monetization network. Data is collected from networks you integrate with and enable in ZendeskConnect.

The source_network name is either the name of the partner integrating with ZendeskConnect or the monetization network name reported by the integrated partner.

segment

String

Yes

Yes

Example: "segment" : "my_segment"

date

String

No

Yes

Ad revenue date

Example: To group by date, "groupings": ["date"]

placement

String

Yes

Yes

  • Example: "groupings": ["placement"]

  • If grouped by placement: the placement_id automatically returns in addition to placement. 

ad_unit

String

Yes

Yes

  • Example: "groupings": ["ad_unit"].

  • If grouped by ad_unit: the ad_unit_id automatically returns in addition to ad_unit

platform

String

Yes

Yes

The platform serving the ad

app_id

String

Yes

Yes

 

Metrics

  • Metrics available are listed in the table. 
  • Specify one or more metrics in an array.
  • Metric availability is monetization network-dependent. 

Metric

Format

Description

requests

Integer

Number of ad requests 

impressions

Integer

Number of impressions 

clicks

Integer

Number of clicks 

revenue

Decimal

Amount of revenue generated.

If preferred_currency=false: value is in USD.

If preferred_currency=true: value is in app-specific currency. Use get App list API to get the currency or check in the dashboard.

Currency conversion rates: Currency conversion, if required, is performed using the exchange rate that prevails on the ad revenue date.

ecpm

Decimal

Effective cost per thousand impressions (eCPM).

Formula: revenue / impressions * 1000

completions

Integer

Number of ad view completions as reported by the monetization partner

fill_rate

Decimal

Formula: impressions / requests

Note: Field should return n/a for monetization partners that do not return request data

ctr

Decimal

Formula: clicks / impressions

arpdau

Decimal

Formula: (average daily revenue during the date range / number of days) / (max daily unique active users during the date range / number of days)
Ad revenue metrics

Curl example request

This example contains a complete API call.


curl --location --request POST 'https://hq1.appsflyer.com/api/ad-revenue-agg/v1/data/app/{app-id}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <V2 token of more than 700 characters' \
--data-raw '{
    "from": "2020-10-01",
    "to": "2020-10-30",
    "preferred_currency": true, 
    "filters": {
        "geo": [
            "za",
            "de"
        ],
        "ad_type": [
            "banner",
            "video",
            "interstitial"
        ]
    },
    "groupings": [
        "geo",
        "ad_type"
    ],
    "metrics": [
        "impressions",
        "clicks",
        "ctr",
        "revenue"
    ]
}'

Example JSON response


       {
    "results": [
        {
            "ad_type": "banner",
            "app_id": "com.adrevenue.agg_api_1b",
            "clicks": 0,
            "ctr": 0,
            "currency": "JPY",
            "geo": "de",
            "impressions": 960,
            "platform": "android",
            "revenue": 10097232.84006
        },
        {
            "ad_type": "interstitial",
            "app_id": "com.adrevenue.agg_api_1b",
            "clicks": 0,
            "ctr": 0,
            "currency": "JPY",
            "geo": "de",
            "impressions": 800,
            "platform": "android",
            "revenue": 8414360.70005
        },
        {
            "ad_type": "banner",
            "app_id": "com.adrevenue.agg_api_1b",
            "clicks": 0,
            "ctr": 0,
            "currency": "JPY",
            "geo": "za",
            "impressions": 80,
            "platform": "android",
            "revenue": 0
        }
    ]
}

Example CSV response


geo,ad_type,app_id,platform,currency,impressions,clicks,ctr,revenue
de,banner,com.adrevenue.agg_api_1b,android,JPY,960,0,0,1.009723284006e+07
de,interstitial,com.adrevenue.agg_api_1b,android,JPY,800,0,0,8.41436070005e+06
za,banner,com.adrevenue.agg_api_1b,android,JPY,80,0,0,0

Additional information

Response codes and troubleshooting

Response codes

Response code 

Message

Remark 
200 OK

Valid data return
400 Bad request  
401 Unauthorized
  • No authorization token was found.
  • Check that you are using the correct token. It should be more than 700 characters long.
404 Not found
  • Eliminate any network, firewall, etc. related problems. 
  • The token is valid but does not match the app ID requested.
  • The app_id does not exist.
 422 Unprocessable entity
  • See the error message that returns in a JSON. For example, the request must include at least one grouping.
  • Ensure that the request is contained in a JSON and not sent as query parameters. 
  • Ensure that the JSON is formatted in accordance with this article.

Traits and limitations

Trait
Trait Remarks 
Ad network access  No
Agency access No
Agency transparency Not applicable. No agency involvement.
App-specific time zone Data is recorded using the date provided by the ad monetization partner. 
App-specific currency  Supported
Rate limitation
  • API call-rate limited to 60 calls per minute and 50,000 calls per day per account. 
    Queries return up to 10,000 rows. 
Organic data Included
Non-organic data Included
Data freshness Intraday. Data is pulled for the current day and the previous two days. It means that historical data can change retroactively.
Historical data Available from the date the ad revenue feature is enabled in the platform.
Team member access The authorization token is available to the account admin in the dashboard.

Comments

0 comments

Article is closed for comments.

Powered by Zendesk