Overview

This article covers Equativ’s reporting API, allowing you to request, generate and retrieve reports.

Authentication

For information about how to authenticate, refer to API authentication.

Base URL and endpoints

The base URL for reporting API requests is:

https://supply-api.eqtv.io/

Available dimensions and metrics

Learn more about the available dimensions and metrics in these articles:

• Reporting API: dimension reference
• Reporting API: metric reference

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/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/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.

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"]
}