-
Notifications
You must be signed in to change notification settings - Fork 2
Nimbus Reporting API Documentation
Dmitry Traytel edited this page Mar 16, 2023
·
19 revisions
The Nimbus Reporting API provides real-time data and analytics for your application's Nimbus integration. Using a RESTful interface with JSON responses, it powers the Nimbus Dashboard as well as supporting custom integrations that end-users can leverage for their own data integrations.
All requests should be made to the following hostname:
https://dashboard.adsbynimbus.com
Users are asked to request two items from their account manager in order to access the API:
-
publisher_key: The string key used to refer to a given publisher's app integration, ex: "timehop" -
api_key: A JSON Web Token (JWT) representing a Nimbus Dashboard user's access the API.
The API implements Bearer Token Authentication . An `Authorization header with a bearer token is required when making any API requests:
Authorization: Bearer {api_key}
GET /v1/reporting/{publisher_key}
| Request Parameter | Allowed Values | Description | Required |
|---|---|---|---|
| start_date | YYYY-MM-DD | Date from which to get reporting data | Yes |
| end_date | YYYY-MM-DD | Date to which to get reporting data | Yes |
| displayed_info[] | requests wins impressions clicks win_rate render_rate ctr cpm rcpm revenue |
Explicitly specify the fields to return in the response payload. Unspecified values may be returned as empty strings or zero values. There is also a duplicate of each field with a _raw suffix that can be passed to return an unformatted decimal version of the value. Note: Requests and Win Rate may not be available when grouping by creative_type or source_id in grouped_by[] field |
Yes |
| grouped_by[] | date position platform_id country creative_type source_id |
Group reporting data by any or all of these properties. For simple daily reporting numbers, we recommend starting off by passing only date
|
No |
| Response Fields | Type | Description |
|---|---|---|
| data | array | An array of objects, grouped by the properties from the grouped_by[] field in the request, each containing the following fields in their respective formats as well as their raw unformatted values: publisher source_id wins impressions render_rate cpm revenue |
| totals | object | An object containing the totals for the entire date range from the request. Totals include: requests wins impressions win_rate render_rate cpm revenue |
| download_url | string | url relative to the api hostname that resolves to a CSV file containing the same data as the response |
Example Request:
curl 'https://dashboard.adsbynimbus.com/v1/reporting/{publisher_key}?start_date=2019-07-14&end_date=2019-07-22&grouped_by%5B%5D=date&displayed_info%5B%5D=requests&displayed_info%5B%5D=wins&displayed_info%5B%5D=impressions&displayed_info%5B%5D=win_rate&displayed_info%5B%5D=render_rate&displayed_info%5B%5D=cpm&displayed_info%5B%5D=revenue&sort_by=date&sort_order=desc' -H 'Authorization: Bearer {api_key}'
Response:
{
"data": [
{
"date": "2019-01-07",
"requests": "4,134,505",
"wins": "2,781,695",
"impressions": "1,959,410",
"win_rate": "67.28%",
"render_rate": "70.44%",
"cpm": "$5.00",
"revenue": "$9,804.81",
"requests_raw": 4134505,
"wins_raw": 2781695,
"impressions_raw": 1959410,
"win_rate_raw": 67.28,
"render_rate_raw": 70.44,
"cpm_raw": 5,
"revenue_raw": 9804.81
},
{
"date": "2019-01-06",
"requests": "4,260,594",
"wins": "2,812,372",
"impressions": "1,952,565",
"win_rate": "66.01%",
"render_rate": "69.43%",
"cpm": "$5.29",
"revenue": "$10,338.77",
"requests_raw": 4260594,
"wins_raw": 2812372,
"impressions_raw": 1952565,
"win_rate_raw": 66.01,
"render_rate_raw": 69.43,
"cpm_raw": 5.29,
"revenue_raw": 10338.77
},
{
"date": "2019-01-05",
"requests": "4,126,545",
"wins": "2,895,895",
"impressions": "1,995,511",
"win_rate": "70.18%",
"render_rate": "68.91%",
"cpm": "$5.10",
"revenue": "$10,180.75",
"requests_raw": 4126545,
"wins_raw": 2895895,
"impressions_raw": 1995511,
"win_rate_raw": 70.18,
"render_rate_raw": 68.91,
"cpm_raw": 5.1,
"revenue_raw": 10180.75
},
{
"date": "2019-01-04",
"requests": "4,192,555",
"wins": "2,998,682",
"impressions": "2,109,216",
"win_rate": "71.52%",
"render_rate": "70.34%",
"cpm": "$4.63",
"revenue": "$9,770.13",
"requests_raw": 4192555,
"wins_raw": 2998682,
"impressions_raw": 2109216,
"win_rate_raw": 71.52,
"render_rate_raw": 70.34,
"cpm_raw": 4.63,
"revenue_raw": 9770.13
},
{
"date": "2019-01-03",
"requests": "4,246,121",
"wins": "2,962,267",
"impressions": "2,142,986",
"win_rate": "69.76%",
"render_rate": "72.34%",
"cpm": "$4.59",
"revenue": "$9,841.05",
"requests_raw": 4246121,
"wins_raw": 2962267,
"impressions_raw": 2142986,
"win_rate_raw": 69.76,
"render_rate_raw": 72.34,
"cpm_raw": 4.59,
"revenue_raw": 9841.05
},
{
"date": "2019-01-02",
"requests": "4,562,271",
"wins": "2,778,839",
"impressions": "2,002,498",
"win_rate": "60.91%",
"render_rate": "72.06%",
"cpm": "$4.41",
"revenue": "$8,836.96",
"requests_raw": 4562271,
"wins_raw": 2778839,
"impressions_raw": 2002498,
"win_rate_raw": 60.91,
"render_rate_raw": 72.06,
"cpm_raw": 4.41,
"revenue_raw": 8836.96
},
{
"date": "2019-01-01",
"requests": "5,689,264",
"wins": "3,732,470",
"impressions": "2,621,207",
"win_rate": "65.61%",
"render_rate": "70.23%",
"cpm": "$4.42",
"revenue": "$11,584.93",
"requests_raw": 5689264,
"wins_raw": 3732470,
"impressions_raw": 2621207,
"win_rate_raw": 65.61,
"render_rate_raw": 70.23,
"cpm_raw": 4.42,
"revenue_raw": 11584.93
}
],
"totals": {
"requests": "31,211,855",
"wins": "20,962,220",
"impressions": "14,783,393",
"win_rate": "67.16%",
"render_rate": "70.52%",
"cpm": "$4.76",
"revenue": "$70,357.40"
},
"download_url": "/v1/reporting/{publisher_key}?start_date=2019-01-01&end_date=2019-01-07&format=csv&grouped_by%5B%5D=date&displayed_info%5B%5D=requests&displayed_info%5B%5D=wins&displayed_info%5B%5D=impressions&displayed_info%5B%5D=win_rate&displayed_info%5B%5D=render_rate&displayed_info%5B%5D=cpm&displayed_info%5B%5D=revenue&sort_by=date&sort_order=desc",
}