Wiki
Clone wikimobile.mng-ads.com-mngperf / buyer-reporting-api
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 see campaign-list-service e.g adunitId[0]=1&adunitId[1]=2 |
| campaignId | no | array of campaigns IDs | Filter reporting on a specific campaign see campaign-list-service 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
#!bash $ 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.)
#!bash $ 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' \
#!json { "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
#!bash $ 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
#!json { "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
#!json [ { "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
#!bash curl -H "Authorization: cf45ea76682190d5daca73acc1cc57afa988f546" \ -X GET 'https://xxxx.com/campaigns'
Updated