Network Reporting API

The below spec outlines the process for the daily pull of performance data, updated every 24 hours. The guide is intended for use by software engineers, system architects, and product or project managers.

This API can only be used by networks integrated with MoPub as a server-side or SDK mediation partner.

Note: The Reporting API is required for all MoPub certified partners.

API Details

Request Parameters

Name Required? Default Value Description
user Required Login Username. Either user and pass or apiKey is required.
pass Required User Password. Either user and pass or apiKey is required.
apiKey Required

Client Key or API Key if supported. Either user and pass or apiKey is required.

Generally, Mopub recommends to use this instead of username/password for additional security.

fromDate Yes

Format YYYY-MM-DD

Example: 2010-01-07

toDate Yes

Format YYYY-MM-DD

Example: 2010-01-08

apps No all apps

This field contains the App IDs which the Network provided to the publisher for each app.

The field is used to Filter by Apps i.e. get results only for specified apps.

For multiple selections, separate them by comma.

Example: apps=appId1,appId2

countries Yes No Country Two Digit short code (ISO 3166) of the country for which the data is desired.
groupBy Yes date,appid,adunitid Comma-separated list of dimensions to group by; valid values include “appid”,”adunitid,”date”, and “country”.
  • The request must be in GET format.
  • If authentication fails, the response should have a HTTP 403 status.
  • Integration partner will provide Mopub with an end-point URL that accepts the Mopub Reporting Request with the specified parameters.
  • Response to a call to the end-point URL are detailed in the table below.
  • Both “https” and “http” are supported. However, due to security reasons – especially since username and password are being used – we strongly recommend using https protocol for data transfer.
  • Mopub will not be responsible for any security related issues which may arise out of using the less secure “http” protocol

Response

The response must be a CSV file with the following structure:

Row Type Content
Header Row A single row containing column headers of the report
Data Rows Multiple rows containing data results

Required Response Headers

Value Description
Date

Format is YYYY-MM-DD

Each day should correspond to 1 day in UTC

Appid

App IDs which the Network provided to the publisher for each app

Case sensitive

AdUnitid This must be a unique identifier and is a more granular placement ID

Case sensitive. IDs returned must match exactly what the publisher used to set up their placements

Requests Request made to the network to fill an impression
Impressions Impression shown to the user

Server-to-Server Partners: Reporting should be based off of Win Notification URL.

Clicks
Revenue In USD

Dollar amount

Should not have the ‘$’ prefix

Country Provide the 2 digit short code for the respective country (as per ISO 3166)

Sample Request

https://reporting.adnetwork.com/report.html?user=user&pass=123&fromDate=2010-01-07&toDate=2010-01-08&apps=123456&groupBy=date,appid,adunitid,country

Sample Response

CSV File

Date,Appid,AdUnitid,Requests,Impressions,Clicks,Revenue,Country
2014-01-07,1234,abc5678,5893562,3848585,49386,2078.24,US
2014-01-08,2345,abc6789,3265412,1828585,49386,2816.02,US
  • The report should be in CSV Format with a header row and data rows. The order of the columns do not matter.

  • Both to and from dates in the request should be included in the report.

  • Depending on what fields are specified in the groupBy parameter, the Header and Data rows should be adjusted accordingly.

  • Each day should correspond to 1 day in UTC

  • App and AdUnit IDs are case sensitive.

    • The IDs shown to the publisher when setting up their app or ad units should match exactly with what is returned from the reporting system
  • Server-to-Server Partners: Reporting should be based off of Win Notification URL.

  • Following are the descriptions of the columns itself:

    • Date: Format is YYYY-MM-DD

    • Appid – optional however either App or AdUnit ID are required

    • AdUnitid – optional however either App or AdUnit ID are required

    • Requests

    • Impressions

    • Clicks

    • Revenue

      • In USD

      • Dollar amount (See example above)

      • Should not have the ‘$’ prefix

    • Country

      • Provide the 2 digit shortcode for the respective country (as per ISO 3166)

Changelog

6/16/2015

  • Country is now required

10/24/2014

  • App and AdUnit IDs are case sensitive and the IDs returned should match exactly what the publisher sets in the FE

10/16/2014

  • Remove complete mention of AdUnitSize since it is not supported

10/8/2014

  • Either user and pass or apiKey is required

9/5/2014

  • Clarified revenue must be returned in a dollar amount

9/3/2014

  • Clarified country is not optimized against at this point in time and may be used in the future

8/14/14

  • GroupBy now required

  • Added HTTP 403 status as a requirement if authentication fails

8/7/14

  • Clarified revenue is USD

  • Clarified revenue should not have the ‘$’ prefix

  • Remove mention of AdUnitSize in groupBy since it’s not currently supported

7/20/14

  • Clarified each day should correspond to UTC Time Zone

  • Require either Appid or AdUnitid in the response

Last updated June 14, 2018

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2018 MoPub Inc.