Seller Reporting API

Quick Reference

All API access is over HTTPS, and accessed via the https://xxx.com domain (ask to your Madvertise contact).

Request Format

For POST requests, the request body must be JSON, with the Content-Type header set to application/json.

Response format

The response format for all requests is a JSON object.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure.

POST /auth-reporting : Authentication Service

see auth-reporting section.

POST /seller-reporting : Publisher Reporting Service

Use the token returned by auth-reporting service when making calls to /seller-reporting. You POST the JSON request and get back a report ID.

Metrics

Metric	Definition
requests	An attempt to MAS adserver to fill an impression.
displays	Number of times an ad is served and displayed according Viewbility .
clicks	Number of times an ad is clicked.
downloads	Number of conversions from Conversion API or Appsfire [Buyer Integration]
leads	Number of leads from Conversion API or Appsfire [Buyer Integration]
landings	Number of landings from Conversion API or Appsfire [Buyer Integration]
revenueEuro	Revenue generated in €.
revenueDollar	Revenue generated in $.

Breakdowns/Dimensions list

Optionally, use one of the following options in the breakdowns param to specify which dimension.

Dimension	Definition
DAILY	Provides a breakdown by day (can't be combined with HOURLY, RANGE and DAILY)
HOURLY	Provides a breakdown by hour (can't be combined with MONTHLY, RANGE and DAILY)
MONTHLY	Provides a breakdown by Month (can't be combined with HOURLY, RANGE and DAILY)
RANGE	Provides a breakdown according since and until dates (can't be combined with HOURLY, MONTHLY and DAILY)
ADNETWORK	Provides a breakdown by our core Ad network (mngperf or appsfire)
ZONE	Provides a breakdown by placement (banner, Interstitial, NativeAd, ...)
PUBLISHER	Provides a breakdown by Publisher
SUBPUBLISHERID	Provides a breakdown by Sub Publisher Id for appsfire adnetwork, arg3 parameter on adrequest
SUBSUBPUBLISHERID	Provides a breakdown by Sub Publisher Id for appsfire adnetwork, arg4 parameter on adrequest
APPCOUNTY	Provides a breakdown by country (FR, DE or IT), Madvertise manage apps from different countries
APP	Provides a breakdown by App
BUNDLEID	Provides a breakdown by packageName for android and bundleId for IOS
FORMAT	Provides a breakdown by format (interstitial, banner, nativeAd ...)
COUNTRY	Provides a breakdown by country (FR, US,...)
REGION	Provides a breakdown by Region (Admin Level 1)
DEPARTMENT	Provides a breakdown by Department (Admin Level 2)
CITY	Provides a breakdown by City (Paris, ...)
POSTALCODE	Provides a breakdown by Postal Code
OS	Provides a breakdown by mobile OS
DEVICETYPE	Provides a breakdown by DeviceType (phone or tablet)
DEVICEBRAND	Provides a breakdown by BrandName (e.g Apple)
DEVICEMODEL	Provides a breakdown by Model (e.g iPhone 7 Plus)
CARRIER	Provides a breakdown by Carrier (e.g Orange) Mobile carrier name or Wireless carrier
BUYERNAME	Provides a breakdown by buyer (Vectaury, Adot, Bidswitch,..) connected to madvertiseSSP
DEALID	Provides a breakdown by deal connected to madvertiseSSP
DMP	Provides a breakdown by dmp (Adobe, 1px, ...) connected to madvertiseSSP

Filters

Parameter name	Required?	Format	Definition
since	Yes	europe/paris unix timestamp	e.g 1417392000
until	Yes	europe/paris unix timestamp	e.g 1420070399
breakdowns	No	array of string	see breakdowns-list section, e.g breakdowns[0]=HOURLY&breakdowns[1]=ZONE
publisherId	no	array of publishers IDs	For admin only Filter reporting on specific publishers e.g publisherId[0]=1&publisherId[1]=2
subPublisherId	no	array of subpublishers IDs	Filter reporting on specific sub publishers e.g subPublisherId[0]=1
subSubPublisherId	no	array of subSubPublisherId IDs	Filter reporting on specific sub publishers e.g subSubPublisherId[0]=1
platformId	no	array of platformId	Filter reporting on specific platformId e.g platformId[0]=1
appId	no	array of apps IDs	Filter reporting on specific apps e.g appId[0]=1&appId[1]=2
s	no	array of placements IDs	Filter reporting on a specific placement e.g s[0]=1&s[1]=2
osId	no	Array of mobile OS	Filter reporting on a mobile OS see os-list e.g osId[0]=1&osId[1]=2
formatId	no	Array of format	Filter reporting on a specific placement format formats-list e.g formatId[0]=1&formatId[1]=2
countryId	no	Array	Filter reporting on a specific placement country based on geonameid
regionId	no	Array	Filter reporting on a specific placement region (admin level 1) based on geonameid
departmentId	no	Array	Filter reporting on a specific placement department (admin level 2) based on geonameid
cityId	no	Array	Filter reporting on a specific placement city based on geonameid
postalcode	no	Array	Filter reporting on a specific placement postalcode based on geonameid
adNetworkId	no	Array	Filter reporting on a specific Ad network
carrier	no	Array Filter reporting on a specific carrier (free, Orange,...)
deviceTypeId	no	Array	Filter reporting on a specific brandId
deviceBrandId	no	Array	Filter reporting on a specific brandId
deviceModel	no	Array	Filter reporting on a specific model (iPhone X, ...)
buyerId	no	Array	Filter reporting on a buyer connected to Madvertise SSP
dealId	no	Array	Filter reporting on a deal created by Madvertise SSP
dmpId	no	Array	Filter reporting on a dmp created by Madvertise SSP
dmpSourceId	no	Array	Filter reporting on a dmp (1px, Adobe, ...) created by Madvertise SSP

output

{
  "response": {
    "status": "OK",
    "report_id": "20e5cee104f3ebb0011fbeb8852fafdf9d237113"
  }
}

Example

$ curl -H 'Authorization: fbe74e915898ee0d560643d0f3dd722eb17bade3' \
-H 'Accept: application/json' \
-H "Content-Type: application/x-www-form-urlencoded" \
-X POST  "https://xxx.com/seller-reporting" \
--data 'metrics=requests,displays,clicks,downloads,leads,landings,revenueEuro,eyesTrackings' \
--data 'since=1508485191' \
--data 'until=1508830791' \
--data 'publisherId[0]=5961' \
--data 'breakdowns[1]=PUBLISHER' \
--data 'breakdowns[2]=APP' \
--data 'breakdowns[4]=APPCOUNTRY'

POST /status-reporting : Request the status of a report

Make a POST call with the report ID to retrieve the status of the report. Continue making this call until the status is ready. Then use the /download-reporting end point to save the reporting data to a file. (This is described in the next step.)

$ curl -H 'Authorization: 1be3546f0bed0e3f03b08673d1a635c81fb55bba' \
-H 'Accept: application/json' \
-H "Content-Type: application/x-www-form-urlencoded" \
-X POST  "https://xxx.com/status-reporting" \
--data 'id=7e65da22fca0cad8db34556f11466960b11dba74' \

{
  "response": {
    "status": "progress",
    "message": "progress",
    "report_id": "7e65da22fca0cad8db34556f11466960b11dba74"
  }
}

POST /download-reporting : Retrieve report data

To download the report data to a file, make another POST call with the report ID. You can find report ID on previous POST response (/status-reporting), **for ready status only. Must be called when /status-reporting returns ready status

$ curl -H 'Authorization: 1be3546f0bed0e3f03b08673d1a635c81fb55bba' \
-H 'Accept: application/json' \
-H "Content-Type: application/x-www-form-urlencoded" \
-X POST  "https://xxx.com/download-reporting" \
--data 'id=7e65da22fca0cad8db34556f11466960b11dba74' > /tmp/seller_stats.csv

Response

{
  "data": [
    {
      "country": "France",
      "city": null,
      "eyesTrackings": 0,
      "requests": 0,
      "displays": 59,
      "platform": "Android",
      "zoneHash": "/1085857/banner/af",
      "downloads": 0,
      "postalcode": null,
      "appId": "1085857",
      "subpublisherId": null,
      "landings": 0,
      "deviceType": "phone",
      "os": "Android",
      "subSubPublisherId": null,
      "appName": "FR_Mondadori_PleineVie_App_AndroidTab_Madvertise",
      "adminLevel1": null,
      "adminLevel2": null,
      "format": "banner",
      "bundleId": "com.mondadori.pleinevie",
      "appOwner": "MBRAND",
      "encodedSubpublisherId": null,
      "carrier": "orange",
      "leads": 0,
      "publisher": "Mondadori",
      "clicks": 2,
      "valueDollar": 0,
      "deviceModel": "B3-A20",
      "Adnetwork": "appsFire",
      "deviceBrand": null,
      "revenueEuro": 0
    },
    ...
  ],
  "summary": {
    "since": "2017-10-20T09:39:51+0200",
    "until": "2017-10-24T09:39:51+0200",
    "breakdowns": [
      "PUBLISHER",
      "APP",
      "OS",
      "FORMAT",
      "DEVICETYPE",
      "BUNDLEID",
      "DEVICEBRAND",
      "DEVICEMODEL",
      "COUNTRY",
      "REGION",
      "ZONE",
      "SUBPUBLISHERID",
      "ADNETWORK",
      "DEPARTMENT",
      "CITY",
      "POSTALCODE",
      "SUBSUBPUBLISHERID",
      "PLATFORM",
      "CARRIER"
    ],
    "timezone": "europe/paris"
  }
}