Buyer 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 /buyer-reporting : Advertiser Reporting Service

Use the token returned by auth-reporting service when making calls to /buyer-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 $.
eyesTrackings	[eyes-tracking]

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)
CAMPAIGN	Provides a breakdown by campaign
ADUNIT	Provides a breakdown by Ad
ADVERTISER	Provides a breakdown by Advertiser
PUBLISHERID	Provides a breakdown by publisherId
FORMAT	Provides a breakdown by format (interstitial, banner, nativeAd ...)
OS	Provides a breakdown by mobile OS
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

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
advertiserId	no	array of advertiser IDs	For admin only Filter reporting on specific advertisers e.g advertiserId[0]=1&advertiserId[1]=2
adunitId	no	array of adUnits IDs	Filter reporting on a specific adunitId e.g adunitId[0]=1&adunitId[1]=2
campaignId	no	array of campaigns IDs	Filter reporting on a specific campaign e.g campaignId[0]=1&campaignId[1]=2
osId	no	Array	Filter reporting on a mobile OS see os-list e.g osId[0]=1&osId[1]=2
formatId	no	Array	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	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, ...)

Example

$ curl -H 'Authorization: fbe74e915898ee0d560643d0f3dd722eb17bade3' \
-H 'Accept: application/json' \
-H "Content-Type: application/x-www-form-urlencoded" \
-X POST  "https://xxx.com/buyer-reporting" \
--data 'metrics=displays,clicks,downloads,leads,landings,revenueEuro,eyesTrackings' \
--data 'since=1508485191' \
--data 'until=1508830791' \
--data 'advertiserId[0]=58' \
--data 'breakdowns[7]=ADUNIT' \ 
--data 'breakdowns[8]=FORMAT' \
--data 'breakdowns[9]=DEVICETYPE' \
--data 'breakdowns[10]=CAMPAIGN'

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": null,
      "city": null,
      "eyesTrackings": 0,
      "displays": 1,
      "billingEntity": "Mbrand3",
      "platform": "Ios",
      "creativeId": "0",
      "adUnitLimitType": "0",
      "downloads": 0,
      "postalcode": null,
      "subpublisherId": null,
      "landings": 0,
      "deviceType": "phone",
      "advertiser": "Mobile Network Group-Advertiser",
      "adName": "SSP_Appnexus_app_interstitial",
      "os": null,
      "campaignId": "1072",
      "adminLevel1": null,
      "adminLevel2": null,
      "bundleId": "com.meteo.meteofrance",
      "adUnitLimitValue": "0",
      "carrier": "free",
      "adId": "4760",
      "leads": 0,
      "clicks": 0,
      "valueDollar": 0,
      "deviceModel": null,
      "Adnetwork": "appnexus S2S",
      "campaignName": "SSP_Appnexus",
      "deviceBrand": null,
      "revenueEuro": 0
    },
    ...
  ],
  "summary": {
    "since": "2017-10-20T09:39:51+0200",
    "until": "2017-10-24T09:39:51+0200",
    "breakdowns": [
      "OS",
      "ADUNIT",
      "DEVICETYPE",
      "CAMPAIGN",
      "BUNDLEID",
      "DEVICEBRAND",
      "DEVICEMODEL",
      "COUNTRY",
      "REGION",
      "SUBPUBLISHERID",
      "ADNETWORK",
      "ADVERTISER",
      "DEPARTMENT",
      "CITY",
      "POSTALCODE",
      "PLATFORM",
      "CARRIER",
      "CREATIVE"
    ],
    "timezone": "europe/paris"
  }
}

GET /campaigns : Campaign List Service

Returns all campaigns and adunits for campaigns

Output

[
  {
    "advertiserId": "56",
    "advertiserName": "Mobile Network Group-Advertiser",
    "campaignId": "1",
    "campaignName": "my campaign",
    "campaignStartDate": "2018-03-27 00:00:00",
    "campaignEndDate": "2028-03-27 18:14:00",
    "adunits": [
      {
        "adunitName": "my campaign 1",
        "adunitId": "1"
      }
    ]
  },
  {
    "advertiserId": "56",
    "advertiserName": "Mobile Network Group-Advertiser",
    "campaignId": "2",
    "campaignName": "my campaign 2",
    "campaignStartDate": "2018-03-27 00:00:00",
    "campaignEndDate": "2028-03-27 18:14:00",
    "adunits": [
      {
        "adunitName": "my campaign 1",
        "adunitId": "1"
      }
    ]
  }
]

Example

curl -H "Authorization: cf45ea76682190d5daca73acc1cc57afa988f546" \
-X GET 'https://xxxx.com/campaigns'

Quick Reference​

Request Format​

Response format​

POST /auth-reporting : Authentication Service​

POST /buyer-reporting : Advertiser Reporting Service​

Metrics​

Breakdowns/Dimensions list​

Filters​

Example​

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

POST /download-reporting : Retrieve report data​

Response​

GET /campaigns : Campaign List Service​

Output​

Example​

Quick Reference

Request Format

Response format

POST /auth-reporting : Authentication Service

POST /buyer-reporting : Advertiser Reporting Service

Metrics

Breakdowns/Dimensions list

Filters

Example

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

POST /download-reporting : Retrieve report data

Response

GET /campaigns : Campaign List Service

Output

Example