Sulvo offers an Advanced Reporting API
Users can get ad performance information by logging into Surge and using its UI or using Advances Reports for receiving additional data through CSV reports. However, Sulvo also offers a Reporting API (application programming interface) as an alternative for receiving the same data without accessing the UI.
Authentication (API key)
The Reporting API uses keys to authenticate requests. Users can get and manage their keys in Surge under the API Key section of My Account. All of the following operations are done there.
For developers: all the operations with API keys are done on the /api/me/api-key url.
An API key is a string of text which you must attach to any request made to the API. It works similarly to a physical key in that it gives a user access to his or her reports. It looks like this:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2eWE0N2FoREUyQzk0WlJ4aSIsImFjY291bnRJZCI6IjVlOWYxZTkxNTMyNGRlMjIzMmI5NWJhZSIsImFwaUtleUlkIjoxfQ.38AnpOavKs9l_QTmMVIjSN0InKSjTRCezSDoBrvb7GYA user can start using the API by generating a key and disable the feature by deleting the key. Each account can have only one key and the key is valid for any request made to the API as long as the key is active
An API Key is only valid for the HTTP requests described in this document, and only provides data for the domains the account has access to. All the API requests use the GET method and are read-only, the API does not allow write-access or permissions changes.
Step 1: Generate an API Key
To start using it, a user must first generate an API Key by clicking the Generate new key button in My Account.
This will generate a new key and return its value.
Step 2: Get the API key
Once you have generated a key you should keep the key secure. The API is available as soon as the key is generated.
Re-generate API key
If you lose your key or the key security is compromised you should re-generate a new key.
After re-generating the key, a user should replace it where he has been using the other one as soon as possible, otherwise, the requests to the API will start to fail. There is a two-hour window in which you can still use the old one. This gives ample time to replace keys without disrupting their systems. After that time has passed, the old key will no longer be valid.
Delete API key
You can delete the API key when you will no longer be using the API. No key will be valid after this until a new key is generated.
API Reference
Ad Units
Returns the available Ad Inventory for a publisher, meaning all the domains they manage and their associated ad units.
This is a fundamental request and should be the first one used when working with the API as it gives a full list of the units the user is getting information about. All the reports will refer to these units and most of the requests can be configured to show data about individual domains or units, giving a great deal of flexibility and maximizing its utility.
HTTP Request
GET /api/v1/inventory/ad-units-by-domain
Required Parameters
None
Optional Parameters
None
Example Request
curl https://surge.sulvo.com/api/v1/inventory/ad-units-by-domain
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"domain": "example.com",
"adRoots": [ "example.com_responsive_h", "example.com_sticky_mobile"]
},
{
"domain": "mydomain.com",
"adRoots": [ "mydomain.com_sticky_desktop", "mydomain.com__responsive_v"]
}
]
}
Performance By Date
Returns a list of reports within a range of dates for the selected ad units (all by default) divided and ordered by date.
Each report includes the following aggregated metrics for a single day:
Impressions
Requests
Earnings
Clickthrough Rate (CTR)
Viewable Cost Per Mille (vCPM)
HTTP Request
GET /api/v1/reports/by-date?start=<start>&end=<end>&domains=<domains>&adRoots=<adRoots>
Required Parameters
start: a date the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
domains: a list of domains separated by commas (without spaces)
adRoots: a list of ad roots separated by commas (without spaces)
Example Request
curl https://surge.sulvo.com/api/v1/reports/by-date?start=2020-01-01&end=2020-01-02&domains=mydomain.com&adRoots=example.com_sticky_mobile
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"date": "2020-01-01T07:00:00.000Z",
"impressions": 33232,
"earnings": 21.67,
"adRequests": 43351,
"ctr": 0.0235,
"vcpm": 0.44
},
{
"date": "2020-01-02T07:00:00.000Z",
"impressions": 258613,
"earnings": 86.38,
"adRequests": 328700,
"ctr": 0.0239,
"vcpm": 0.46
},
]
}
Performance By Domain and Ad Unit
Returns a list of reports within a range of dates for the selected ad units (all by default) divided and domain and ad unit.
Each report includes the following aggregated metrics of all the selected ad-units of a single domain (as aggregates), and then a list with the same metrics for each ad unit individually:
Impressions
Requests
Earnings
Clickthrough Rate (CTR)
Average View Viewable (AVV)
Average View Time (AVT)
Also, for each ad unit the following data is included:
Title and textual description
Viewable Cost Per Mille (vCPM) for the whole ad unit
Earnings, Cost Per Mille (CPM) and vCPM divided in 2 segments
A percentage comparison between segments' earnings named eBar
HTTP Request
GET /api/v1/reports/by-domain-and-ad-unit?start=<start>&end=<end>&domains=<domains>&adRoots=<adRoots>
Required Parameters
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
domains: a list of domains separated by comas (without spaces)
adRoots: a list of ad roots separated by comas (without spaces)
Example Request
curl https://surge.sulvo.com/api/v1/reports/by-domain-and-ad-unit?start=2020-01-01&end=2020-01-02&domains=mydomain.com&adRoots=mydomain.com_sticky_desktop
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"domain": "mydomain.com",
"totals": {
"earnings": 212.17,
"impressions": 52399,
"adRequests": 60485,
"avv": 0.3294,
"avt": 7.6,
"ctr": 0.0166
},
"ads": [
{
"domain": "mydomain.com",
"adRoot": "mydomain.com_sticky_desktop",
"title": "Sticky Desktop",
"description": "A sticky ad for desktop",
"earnings": 212.17,
"impressions": 52399,
"adRequests": 60485,
"avv": 0.3294,
"avt": 7.6,
"ctr": 0.0166,
"vcpm": 2.41,
"segments": [
{
"earnings": 102.18,
"cpm": 1.42,
"vcpm": 1.39,
"eBar": 21.80
},
{
"earnings": 109.99,
"cpm": 3.11,
"vcpm": 3.43,
"eBar": 100.00
}
]
}
]
}
]
}
Performance By Date and Ad Unit
Returns a list of reports within a range of dates for the selected ad units (all by default) divided by date and ad unit.
Each report includes the following aggregated metrics for a single day and a single ad unit:
Impressions
Requests
Earnings
Clickthrough Rate (CTR)
Average View Viewable (AVV)
Average View Time (AVV)
Viewable Cost Per Mille (vCPM) for the whole ad unit
HTTP Request
GET /api/v1/reports/by-date-and-ad-unit?start=<start>&end=<end>&domains=<domains>&adRoots=<adRoots>
Required Parameters
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
domains: a list of domains separated by comas (without spaces)
adRoots: a list of ad roots separated by comas (without spaces)
Example Request
curl https://surge.sulvo.com/api/v1/reports/by-date-and-ad-unit?start=2020-01-01&end=2020-01-02&adRoots=mydomain.com_sticky_desktop
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"date": "2020-01-01",
"adRoot": "mydomain.com_sticky_desktop",
"impressions": 497971,
"earnings": 107.84,
"adRequests": 645246,
"avv": 0.7789,
"avt": 11.58,
"ctr": 0.0145,
"vcpm": 0.28
},
{
"date": "2020-02-01",
"adRoot": "mydomain.com_sticky_desktop",
"impressions": 510319,
"earnings": 146.11,
"adRequests": 664486,
"avv": 0.775,
"avt": 11.68,
"ctr": 0.0142,
"vcpm": 0.37
},
]
}
Bot Filtering
Returns reports with the number of requests that have been blocked within a range of dates for the selected domains. Requests are blocked when they were made by automated bots.
The response includes two different views: one by date showing blocked requests for all the domains on a single day and another one by domain showing blocked requests for each domain within the range.
HTTP Request
GET /api/v1/reports/bot-filtering?start=<start>&end=<end>&domains=<domains>
Required Parameters
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
domains: a list of domains separated by comas (without spaces)
Optional Parameters
None
Example Request
curl https://surge.sulvo.com/api/v1/reports/bot-filtering?start=2020-01-01&end=2020-01-02&domains=mydomain.com,example.com
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": {
"byDate": [
{
"date": "2020-01-01T07:00:00.000Z",
"blockedRequests": 15952
},
{
"date": "2020-01-02T07:00:00.000Z",
"blockedRequests": 20774
}
],
"byDomain": [
{
"domain": "example.com",
"blockedRequests": 26621
},
{
"domain": "mydomain.com",
"blockedRequests": 10105
}
]
}
}
Bot Scoring
Returns reports with the number of impressions and the score showing their average trust score within a range of dates for the selected ad units. The score shows how certain it is -on average- that impressions weren't made made by a bot. The score ranges from 0 to 100 and the higher the better.
The response includes two different views: one by date showing impressions and the average for all selected the ad units on a single day and another one by adRoot impressions and the average score for each ad unit within the range.
HTTP Request
GET /api/v1/reports/bot-scoring?start=<start>&end=<end>&adRoots=<adRoots>
Required Parameters
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
adRoots: a list of ad units separated by comas (without spaces)
Optional Parameters
None
Example Request
curl https://surge.sulvo.com/api/v1/reports/bot-scoring?start=2020-01-01&end=2020-01-03&adRoots=example.com_responsive_h,mydomain.com__responsive_v
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": {
"byDate": [
{
"date": "2020-04-30T07:00:00.000Z",
"totalImpressions": 25531,
"averageTrustScore": 92.7
},
{
"date": "2020-05-01T07:00:00.000Z",
"totalImpressions": 25096,
"averageTrustScore": 93.46
}
],
"byAdRoot": [
{
"root": "example.com_responsive_h",
"totalImpressions": 27820,
"averageTrustScore": 92.16
},
{
"root": "mydomain.com__responsive_v",
"totalImpressions": 22807,
"averageTrustScore": 94.31
}
]
}
}
Prebid Analysis
Returns reports on the performance of third-party ad providers' bidding. The reports are divided by domain and ad unit for the selected and show the performance on:
Requests
Average Bid Price
Average Response Time
Bid Response Rate
Number of timeouts
It also includes a number of items to identify the ad unit like title and description.
HTTP Request
GET /api/v1/reports/direct-bidder-analysis?start=<start>&end=<end>&directBidder=<directBidder>
Required Parameters
directBidder: a single third party ad provider, you need the corresponding Prebid connector activated for this
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
None
Example Request
curl https://surge.sulvo.com/api/v1/reports/direct-bidder-analysis?start=2020-01-01&end=2020-01-03&directBidder=oneBidder
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": {
"my-domain.com": [
{
"adUnit": {
"title": "Sticky Desktop",
"description": "A sticky ad for desktop"
},
"domain": "my-domain.com",
"size": {
"width": 300,
"height": 250
},
"type": "sticky_display",
"directRequests": 10093,
"directTimedout": 150,
"directBidsResponses": 2215,
"directAveragePrice": 0.03,
"directAverageResponseTime": 298.58,
"directBidResponseRate": 0.3727
},
]
}
}
Performance By Date (other providers)
Returns a list of reports within a range of dates for the selected ad units (all by default) divided and ordered by date. These results are only of the requested third-party ad provider and the ad units of the domains you have configured with them.
Each report includes the following aggregated metrics for a single day:
Impressions
Requests
Earnings
Cost Per Mille (CPM)
HTTP Request
GET /api/v1/reports/by-date?start=<start>&end=<end>&adProvider=<adProvider>&domains=<domains>&adRoots=<adRoots>
Required Parameters
adProvider: a single third party ad provider, you need the corresponding Prebid connector activated for this
start: a date the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
domains: a list of domains separated by comas (without spaces)
adRoots: a list of ad roots separated by comas (without spaces)
Example Request
curl https://surge.sulvo.com/api/v1/reports/by-date?start=2020-01-01&end=2020-01-02&adProvider=oneProvider&domains=mydomain.com&adRoots=example.com_sticky_mobile
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"date": "2020-01-01T07:00:00.000Z",
"impressions": 1826,
"earnings": 1.84,
"adRequests": 81203,
"cpm": 1.01
},
{
"date": "2020-01-02T07:00:00.000Z",
"impressions": 1616,
"earnings": 1.75,
"adRequests": 77875,
"cpm": 1.09
},
]
}
Performance By Domain and Ad Unit (other providers)
Returns a list of reports within a range of dates for the selected ad units (all by default) divided and domain and ad unit. These results are only of the requested third-party ad provider and the ad units of the domains you have configured with them.
Each report includes the following aggregated metrics of all the selected ad-units of a single domain (as aggregates), and then a list with the same metrics for each ad unit individually:
Impressions
Requests
Earnings
Cost Per Mille (CPM)
Also, for each ad unit the following data is included:
Title and textual description
HTTP Request
GET /api/v1/reports/by-domain-and-ad-unit?start=<start>&end=<end>&adProvider=<adProvider>&domains=<domains>&adRoots=<adRoots>
Required Parameters
adProvider: a single third party ad provider, you need the corresponding Prebid connector activated for this
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
domains: a list of domains separated by comas (without spaces)
adRoots: a list of ad roots separated by comas (without spaces)
Example Request
curl https://surge.sulvo.com/api/v1/reports/by-domain-and-ad-unit?start=2020-01-01&end=2020-01-02&adProvider=oneProvider&adRoots=mydomain.com_sticky_desktop
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"domain": "mydomain.com",
"totals": {
"impressions": 1823,
"earnings": 1.84,
"adRequests": 6680,
"cpm": 1.01
},
"ads": [
{
"domain": "mydomain.com",
"adRoot": "mydomain.com_sticky_desktop",
"title": "Sticky Desktop",
"description": "A sticky ad for desktop",
"impressions": 1823,
"earnings": 1.84,
"adRequests": 6680,
"cpm": 1.01
}
]
}
]
}
Performance By Date and Ad Unit (other providers)
Returns a list of reports within a range of dates for the selected ad units (all by default) divided by date and ad unit. These results are only of the requested third-party ad provider and the ad units of the domains you have configured with them.
Each report includes the following aggregated metrics for a single day and a single ad unit:
Impressions
Requests
Earnings
Cost Per Mille (CPM)
HTTP Request
GET /api/v1/reports/by-date-and-ad-unit?start=<start>&end=<end>&adProvider=<adProvider>&domains=<domains>&adRoots=<adRoots>
Required Parameters
adProvider: a single third party ad provider, you need the corresponding Prebid connector activated for this
start: a date indicating the start of the range in UTC with the ISO 8601 format YYYY-MM-DD
end: a date indicating the end of the range in UTC with the ISO 8601 format YYYY-MM-DD
Optional Parameters
domains: a list of domains separated by comas (without spaces)
adRoots: a list of ad roots separated by comas (without spaces)
Example Request
curl https://surge.sulvo.com/api/v1/reports/by-date-and-ad-unit?start=2020-01-01&end=2020-01-02&adProvider=oneProvider&adRoots=mydomain.com_sticky_desktop,example.com_sticky_mobile
-H "Authorization: Bearer your.api.key"
-H "Accept: application/json"
Example Response
{
"data": [
{
"date": "2020-01-01",
"adRoot": "mydomain.com_sticky_desktop",
"impressions": 19,
"earnings": 0.02,
"adRequests": 4612,
"cpm": 1.23
},
{
"date": "2020-01-01",
"adRoot": "example.com_sticky_mobile",
"impressions": 185,
"earnings": 0.22,
"adRequests": 4737,
"cpm": 1.18
},
{
"date": "2020-01-02",
"adRoot": "mydomain.com_sticky_desktop",
"impressions": 249,
"earnings": 0.27,
"adRequests": 5789,
"cpm": 1.09
},
{
"date": "2020-06-05",
"adRoot": "example.com_sticky_mobile",
"impressions": 193,
"earnings": 0.2,
"adRequests": 20234,
"cpm": 1.06
}
]
}