-
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 |
| date_interval | date week month quarter year |
The interval in which to aggregate the data. Defaults to date
|
No |
| sort | date requests wins clicks impressions win_rate render_rate ctr cpm rcpm revenue platform_id country position creative_type source_id is_anonymous |
Column by which to sort the data. Defaults to date
|
No |
| sort_order | asc desc |
Determines whether data is sorted by ascending or descending order of the values specified in the sort field. Defaults to desc
|
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",
}Note: The maximum size of a GET request is usually limited to 2048 characters. If your GET request exceeds this limit due to the amount of query parameters it contains, the API also supports the above as a POST request, in which the query parameters described above are to be sent as form URL encoded POST body parameters instead.