Overview
This article covers Equativ’s latest reporting API, allowing you to request, generate and retrieve reports. Its main benefits, compared to the legacy API, are its greatly improved performance, scalability and usability.
The reporting API is rolled out to customers in waves and coexists with the legacy reporting API until the rollout is completed.
Legacy reporting API vs. new reporting API
Until the new API is rolled out to all customers, the legacy reporting API documentation remains available, including the related documentation:
Below is a list of key differences between the legacy reporting API and the new reporting API:
- Metrics/dimensions
- Different filter syntax
- Validity of link to csv file containing report data:
- Legacy reporting API: 30 days
- New reporting API: 2 days
Credentials
Reach out to your support contact at Equativ to get your reporting API credentials. Any reporting API account is associated with a standard account and gets its user rights. A standard account is an account used to access the
EMP user interface. Both accounts have the same user name, but the reporting API user has a dedicated password.
Make sure you assign the desired user rights to the associated standard user (e. g. enable the “Access to RTB module” permission to be able to retrieve programmatic data).
For more details about user rights, read the
User management article.
Authentication
To authenticate, provide your credentials in the request header as follows:
Authorization: Basic YYY
YYY is the base64 representation of the concatenation of the login and the password, separated by a colon (":").
If your API platform manages the base64 encoding automatically, simply add the header:
Authorization = Basic login:password
Equativ will soon introduce a new authentication method using FusionAuth’s authentication solution.
Base URL and endpoints
The base URL for reporting API requests is:
https://supply-api.eqtv.io/insights/
| Method | Endpoint | Description |
|---|
| GET | /report-async | Returns all reports available for the authenticated user. |
| POST | /report-async | Generates an asynchronous report, based on the specified configuration. |
| GET | /report-async/{id} | Returns a specific report by id. |
| DELETE | /report-async/{id} | Deletes a report – either a one-time or a scheduled report |
Available dimensions and metrics
Learn more about the available dimensions and metrics in these articles:
Do not use commas ( , ) or semicolons ( ; ) in field names to avoid errors in the csv report files. The default field separator of the API is semicolon; thus, field names with semicolons might be treated as two columns. To avoid such problems, the report API puts fields in quotation marks automatically to ensure proper processing. However, the usage of semicolons is still not recommended.
Creating a basic report
Step 1 - Configure report parameters
Before you create the report, you must configure its parameters.
The sample below shows a configuration for a simple report with these characteristics:
- report name: doc_sample_1_simple_report
- includes data for the time frame Nov. 09, 2023 to Nov. 10, 2023*
- dimensions: by Day
- metrics: Impressions and Clicks
- e-mail address example@example.com will be notified once the report is ready
- useCaseId: Adserving - the report contains data related to direct campaigns/insertions only; i. e. RTB (programmatic) data is not included
{
"reportName": "doc_sample_1_simple_report",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
"Day"
],
"metrics":[
"Impressions",
"Clicks"
],
"useCaseId": "Adserving",
"onFinishEmails": ["example@example.com"]
}
Step 2 - Generate report
To generate the report configured in Step 1, make a POST request to the
/report-async endpoint, specifying the report configuration in the request body:
POST https://supply-api.eqtv.io/insights/report-async
You should receive a Status 200 (Success) response with the report Id.
Sample
ca327b57-335a-4068-bb22-c4c31c70cbef
Step 3 - Request report
To request the report, make a
GET request to the
/report-async/{id} endpoint, attaching the report Id received in Step 2.
Sample
GET https://supply-api.eqtv.io/insights/report-async/ca327b57-335a-4068-bb22-c4c31c70cbef
Step 4 - Retrieve report
The response to the requested report contains the download link (URL) to the final report in csv format.
Sample
{
"id": "ca327b57-335a-4068-bb22-c4c31c70cbef",
"name": "doc_sample_1_simple_report",
"creationDate": "2023-11-22T12:34:43.27672Z",
"killed": false,
"configuration": "{\"StartDate\":\"2023-11-09T00:00:00\",\"EndDate\":\"2023-11-10T00:00:00\",\"Fields\":[{\"Field\":\"Day\",\"OrderBy\":null,\"OutputName\":\"Day\",\"DateFormat\":null},{\"Field\":\"Impressions\",\"OrderBy\":null,\"OutputName\":\"Impressions\",\"DateFormat\":null},{\"Field\":\"Clicks\",\"OrderBy\":null,\"OutputName\":\"Clicks\",\"DateFormat\":null}],\"Filters\":[[{\"Field\":\"IsRtb\",\"Operator\":\"IN\",\"Values\":[0]}]],\"FileFormat\":\"CSV\",\"IanaTimezone\":\"Europe/Paris\",\"UseCase\":\"AdServing\",\"Parameters\":{\"ClientId\":\"54585\"}}",
"status": 1,
"taskId": "c4761849-d02d-4e4c-b9d6-6a9db4c86b5e",
"instanceId": "https://storage.googleapis.com/bkt-dwh-read-reporting-prod-eu-reporting_output/2023/11/22/result_147020cc-6113-4060-a8e9-c4cadc74293c.csv.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=webapi%40fs-async-reporting-prod.iam.gserviceaccount.com%2F20231122%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20231122T123457Z&X-Goog-Expires=172800&X-Goog-SignedHeaders=host&X-Goog-Signature=0184317f034f03608485b0588ec89b0ab3d5a9723e05d27bd0ebd96bbce0de6ab6dbf0161cc9c2bcc0a83982a94b3d3c4511978d0a1fc425d1772c6c876d058bd4e9986142f2a9e7e2da2d6188f9b231d71178972dd11179b8957164f0223fe71297e52e1acdb852525df0b11928e91f453b5b1e6278b8cae2b8e49e9ab977f16193e1feca82628cf9f785743c77195c4028889f3cf9ca7dade2bd0a1b18db0adf093325096900f4cb479e3ee59ec9909b259f0b83d5bf5d8f09609286f8f3be944a6f433e2aea7d8f987a42e6736fb22cfe1514057a8a4ab00977fe057c9e609f00420c62be7467ca07d9ee28a324bb89e44e10ef5a255507d0bf9369738d56",
"networkId": 73,
"userId": 54585,
"isScheduled": false,
"schedulingStartDate": "2023-11-22T12:34:24.674345Z",
"schedulingEndDate": "2023-11-22T12:34:24.674353Z",
"datasource": "GCP"
}
Likewise, an email is sent from report@smartadserver.com to the e-mail address specified in the
onFinishEmails field, containing the download link. The link is freely accessible without credentials, but valid for two days only.
Report status
The table below lists the statuses returned in the the
status field in the response to a requested report.
Report
status Id | Report status description |
|---|
| 0 | IN_PROGRESS |
| 1 | SUCCESS |
| 4 | CSV_AVAILABLE_REPORT_TOO_BIG_FOR_XLSX (Not considered as failed) |
| 9 | JOB_FAILED |
| 17 | DELETED |
| 18 | SCHEDULED |
Use cases
The reporting API differentiates
metrics and
dimensions through the
useCaseId field, which can take one of the following values:
- Adserving - returns data related to direct (non-programmatic) campaigns/insertions
- RTB - returns programmatic data
- Holistic - returns both direct campaign/insertion data and programmatic data
Some dimensions and metrics can be used in both use cases, while others are specific to either the
Adserving use case or
RTB use case.
Sample Adserving use case
{
"reportName": "doc_sample_2_adserving",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
"Day"
],
"metrics":[
"Impressions",
"Clicks"
],
"useCaseId": "Adserving",
"onFinishEmails": ["example@example.com"]
}
Sample RTB use case
{
"reportName": "doc_sample_3_rtb",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
"Day"
],
"metrics":[
"Impressions",
"Clicks"
],
"useCaseId": "RTB",
"onFinishEmails": ["example@example.com"]
}
Translator
The Translator transforms legacy report configurations into the format of the new reporting API.
To use the translator:
- Prepare your report configuration in the format of the legacy reporting API (use legacy field names, legacy filtering syntax etc.).
- Make a POST request to the /translate endpoint, using the report configuration you prepared in the previous step in the body of your request: https://reporting.smartadserverapis.com/[yournetworkId]/translate (make sure you replace [networkId] by the ID of your network at Equativ).
- Copy the response you received from previous step. This response contains the report configuration you prepared in the first step, translated into the format of the new reporting API (new field names, new filtering syntax etc.).
- Finally, call the new reporting API, making a POST request to the the /report-async endpoint: https://supply-api.eqtv.io/insights/report-async ; in the request body of this request, use the report configuration you received in the previous step.
Example
Below is a request body to the /translate endpoint, containing a report configuration in the format of the legacy reporting API.
POST https://reporting.smartadserverapis.com/12345/translate
Request body
{
"startDate": "2024-02-15T00:00:00",
"endDate": "2024-02-16T00:00:00",
"fields": [
{
"PageId": {}
},
{
"Banners": {}
}
],
"advancedFilter": [
[
{
"InsertionId": {
"operator": "IN",
"values": [
12095985
]
}
}
]
]
}
Below is a response body, containing the report configuration in the format of the new reporting API.
Response body
{
"startDate": "2024-02-15T00:00:00",
"endDate": "2024-02-16T00:00:00",
"metrics": [
{
"field": "Impressions",
"outputName": "Banners",
"emptyValue": "0"
}
],
"dimensions": [
{
"field": "PageId",
"outputName": "PageId",
"emptyValue": "0"
}
],
"filters": [
[
{
"field": "InsertionId",
"operator": "IN",
"values": [
"12095985"
]
}
]
],
"useCaseId": "AdServing",
"dateFormat": "yyyy-MM-dd'T'HH:mm:ss",
"timezone": "UTC",
"onFinishEmails": [],
"urlConfiguration": "testBugfest",
"reportName": "Report 2024-03-21T12:26:30",
"onErrorEmails": [],
"simulate": false
}
Related resources
