MoPub Publisher Reporting API

 

1. Introduction

This guide outlines the API specifications to pull daily direct, network, and marketplace stats and is intended for use by software engineers, system architects, and product or project managers.

Please review the change log periodically for updates

1.1 Overview

The MoPub Reporting API supports two separate CSV outputs where publishers can retrieve inventory or campaign performance data.

 

The inventory report output only contains information about apps and ad units. This report includes requests, impressions, conversions, clicks, and CTR metrics. Customer can calculate inventory fill rate based on request data. Note that ad source information is not available in this report.

 

The campaign report output contains both inventory and campaign level data. This report includes attempts, impressions, conversions, clicks, and CTR metrics. Customers can calculate ad source fill rate based on attempts to an ad source to fill an impression. Note that this CSV output does not contain an inventory request metric.

 

1.2 API Workflow

Users will make a GET request using the request parameters and endpoint outlined in Section 2 below. This URL will return a 302 redirect response. The link to download the report will be returned in the response location header.

 

Publishers can retrieve daily reports and specify a date in the fetcher request. Reports for the previous day will be available at 2PM UTC and customers can retrieve data up to the day before the API was enabled in the MoPub UI. The data is finalized as soon as it is made available.

1.3 Granting Permission to Access the Reporting API

In order to retrieve data, the API must first be enabled through the ‘Enable data access through API’ checkbox in the Reports page of the MoPub UI.  

 

After it is enabled, you can obtain your API and report keys by selecting the ‘View API Access Details’ link in the Reports page. Customers will also have the ability to reset their API Key in this modal.

 

If you still need to access your Account Key, please contact your account manager.

 




2. Request

2.1 Parameters

Request Field

Definition

account_key

Publisher unique authentication mechanism

  • Either account_key or api_key is required. Both keys are not supported in the same request.

  • Will be deprecated on December 1st, 2016

api_key

Publisher unique authentication mechanism

  • Either account_key or api_key is required. Both keys are not supported in the same request.

  • Will be required beginning December 1st 2016

report_key

ID of the report to fetch


MoPub will provide publishers with an inventory report ID and a campaign report ID

date

Date of the report


Format YYYY-MM-DD

 

2.2 Format

Must be HTTPs

 

https://app.mopub.com/reports/custom/api/download_report?report_key=REP_KEY&api_key=ACC_KEY&date=YYYY-MM-DD

 

2.3 Sample Request

https://app.mopub.com/reports/custom/api/download_report?report_key=317b8515f5b64868b771ba035074daa8&api_key=18427072dad33c4e3b089a0446225e1e&date=2016-06-12

3. CSV Output

3.1 Structure

The response will be in a CSV format with the following structure:

 

Row Type

Content

Header Row

A single row containing column headers of the report

Data Rows

Multiple rows containing data values

 

3.2 Inventory Report

3.2.1 Header Dimensions

Dimension

Definition

AdUnit Format

Format of the adunit

AdUnit

Adunit name as entered in the MoPub UI

AdUnit ID

ID of the adunit

App

App name as entered in the MoPub UI

App ID

ID of the app

Country

Two Digit short code (ISO 3166) of the country for which the data is desired

Day

Format YYYY-MM-DD

UTC timezone

Device

Device

OS

Operating system



3.2.2 Header Metrics

Dimension

Definition

Requests

An attempt to MoPub adserver to fill an impression. This will only be available in the inventory report

Impressions

Number of times an ad is served

Clicks

Number of times an ad is clicked

Revenue

Revenue generated


This will be “0” for networks

CTR

Click-through rate of an ad. The number of times the click is made on the ad divided by the number of impressions.

Conversions

Only applicable to publishers who use the MoPub conversion tracking feature with the MoPub SDK.


A customer action that has value on your app. Conversion tracking is used to properly measure the effectiveness of cross-promotions and direct sold advertisements.


The conversion rate is the number of app conversions divided by the total number of ad clicks that can be tracked to a conversion.



3.3 Campaign Report

3.3.1 Header Dimensions

Dimension

Definition

AdUnit Format

Format of the adunit

AdUnit

Adunit name as entered in the MoPub UI

AdUnit ID

ID of the adunit

App

App name as entered in the MoPub UI

App ID

ID of the app

Country

Two Digit short code (ISO 3166) of the country for which the data is desired

Creative

Creative name as entered in the MoPub UI

Creative ID

ID of the Creative

Day

Format YYYY-MM-DD


UTC timezone

Device

Device

Line Item

Line item name


For network-segments, this will be

"{network_name} {segment_name}"

Line Item ID

ID of the line item

Line Item Type

Type of ad source


Values may be "Backfill Promotional", "Guaranteed", "Network", "Non-Guaranteed", " Private Marketplace", "Promotional", "Marketplace"

Priority

Line item priority

Network`

Network name


For network segments, custom network names are derived from the title field in the network creation page.


For custom network line items, the values will be “Custom Network” or “Custom Native Network”

Network ID

ID of the network


For network line items, the Network ID will be “N/A”

Order

Order name


For network-segments, this will be

"{network_name} {segment_name}"

Order ID

ID of the Order

OS

Operating System

Segment

Name of the segment the data is associated with


Segment name will be ‘N/A’ for line items

Segment ID

ID of the segment the data is associated with


Segment ID will be ‘N/A’ for line items



3.3.2 Header Metrics

 

Dimension

Definition

Attempts

An attempt to an ad network or Marketplace to fill an impression. This will only be available in the campaign report

Impressions

Number of times an ad is served

Clicks

Number of times an ad is clicked

Revenue

Revenue generated


This will be “0” for networks

CTR

Click-through rate of an ad. The number of times the click is made on the ad divided by the number of impressions.

Conversions

Only applicable to publishers who use the MoPub conversion tracking feature with the MoPub SDK.


A customer action that has value on your app. Conversion tracking is used to properly measure the effectiveness of cross-promotions and direct sold advertisements.


The conversion rate is the number of app conversions divided by the total number of ad clicks that can be tracked to a conversion.




4. Error Codes

 

HTTP Status

Error Message

Description

400

Missing required url parameter: {PARAM_NAME}

N/A

400

Date parameter is malformed. Date must be in YYYY-MM-DD format.

N/A

422

Invalid account_key.

N/A

422

Invalid api_key. (Either the api_key you provided was never correct or perhaps it was reset. Please click "View API Access Details" at the top of https://app.mopub.com/reports/custom/ to see your api_key.)

N/A

422

Invalid report_key.

N/A

422

Data not available before {START_DATE}.

Fetching data before the date the API was enabled in the MoPub UI

422

Data is not available for that date yet. Data is available after 2PM noon UTC on the following day.

N/A

422

Data is not available for that date.

There is not data for this date

 

5. FAQ

  1. Can I pull historical data?

    1. The API supports data for one day prior to the date the API checkbox was enabled in the MoPub UI. If there are dates when the API check box was not enabled then the data for those dates will not be availble. For example, if the checkbox is uncheck and then re-check X days later, the data for the X days on which it was unchecked with NOT be available.

  2. What does N/A represent?

    1. ‘N/A’ means there is no data tied to the header columns.

    2. You will see ‘N/A’ for the following:

      1. Segment header row for line items since line items are associated with an Order, not a segment.

      2. Creative and Creative ID header rows for line items that do not have an associated creative, such as Marketplace or Custom Native Networks

  3. Why am I seeing zeroes in the revenue column?

    1. Currently MoPub does not calculate network revenue

  4. What time will my reports be ready?

    1. Reports will be ready at 2 PM UTC

  5. Are historical reports updated with more finalized data?

    1. The data is finalized as soon as it is made available

Updated: September 2017