Related resources
Available dimensions and metrics
Learn more about the available dimensions and metrics in these articles:
Field options for metrics and dimensions
When requesting metrics and dimensions, you can use the following advanced field options:
- OutputName: modifies the name of a field (dimension/metric) in the final report
- Parameters: allows for the definition of additional parameters for specific types of fields
Modifying the output name of a field (dimension/metric)
You can specify an output name for any field (dimension/metric); in the final retrieved report, the field will have the specified output name, instead of the field’s default name.
The special characters , ) ( & ; - are prohibited in the outputName field. Using such characters will result in an error.
The sample below:
- changes the dimension Day to Day new name
- changes the metric Impressions to Ad Impressions
{
"reportName": "doc_sample_4_output_names",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
{
"field": "Day",
"outputName": "Day new name"
}
],
"metrics":[
{
"field": "Impressions",
"outputName": "Ad Impressions"
},
{
"field": "Clicks"
}
],
"useCaseId": "RTB",
"onFinishEmails": ["example@example.com"]
}
Specifying field parameters
For some metrics, you can/must specify additional parameters.
Parameters for the EventCount metric
The EventCount metric counts the number of times an event occurred. This metric requires the additional parameter EventId to be specified.
The sample below requests the number of times the event with ID 18 (= mute) occurred:
{
"reportName": "doc_sample_5_event_count",
"startDate": "2023-11-09T00:00:00",
"endDate": "2023-11-10T00:00:00",
"dimensions":[
{
"field": "Day"
}
],
"metrics":[
{
"field": "Impressions",
"outputName": "Ad Impressions"
},
{
"field": "Clicks"
},
{
"field": "EventCount",
"parameters": {
"EventId": "18"
},
"OutputName": "Number of Mute events"
}
],
"useCaseId": "RTB",
"onFinishEmails": ["example@example.com"]
}
EventIds
The table below contains the EventIds you can use as parameters of the EventCount metric.
| Event Id | Event Name |
|---|
| 1 | timeview |
| 2 | start |
| 3 | stop |
| 4 | restart |
| 5 | expand |
| 6 | collapse |
| 7 | audioon |
| 8 | audiooff |
| 9 | clickposition |
| 10 | truecount |
| 11 | serverside |
| 12 | visibility |
| 13 | creativeview |
| 14 | firstquartile |
| 15 | midpoint |
| 16 | thirdquartile |
| 17 | complete |
| 18 | mute |
| 19 | unmute |
| 20 | pause |
| 21 | rewind |
| 22 | resume |
| 23 | fullscreen |
| 24 | exitfullscreen |
| 25 | acceptinvitationlinear |
| 26 | closelinear |
| 27 | skip |
| 28 | progress |
| 29 | v_firstsecond |
| 30 | v_firstquartile |
| 31 | v_midpoint |
| 32 | v_thirdquartile |
| 33 | v_complete |
| 34 | timetoclick |
| 35 | ad |
| 36 | noad |
| 37 | timeout |
| 38 | bid |
| 39 | winnotice |
| 40 | wrapper |
| 43 | adexpand |
| 44 | adskip |
| 45 | adcollapse |
| 46 | adslidecount |
| 48 | close |
| 49 | vnoad |
| 50 | download |
| 58 | otherAdInteraction |
| 59 | minimize |
| 60 | overlayViewDuration |
| 10007 | inventory |
| 10008 | click |
| 10009 | videoerror |
| 10010 | loaded |
| 10012 | mraidImpression |
| 10013 | omidImpression |
| 10014 | hbRenderSuccess |
| 10015 | hbRenderFailed |
| 10016 | classicImpression |
| 10017 | vmapimpression |
| 10018 | like |
| 10019 | reblog |
| 10020 | share |
| 10021 | comment |
| 10022 | userengagement |
| 10023 | vmapstart |
| 10024 | ServerSideHeaderBiddingWin |
| 10025 | bumper |
| 10026 | ServerSideHeaderBiddingLoss |
| 10027 | impressionsonepx |
| 10028 | impressionsthirtysec |
| 10029 | impressionsonrender |
Date format
Absolute dates must be formatted in the format: yyyy-MM-dd'T'HH:mm:ss (example: 1984-12-28T10:10:00).
End dates - best practices
If you intend to include an entire day in your report, make sure you set the endDate to the following day at 00:00:00. For instance, if you need the report to cover the entire day of Sept. 1, 2024, you would set:
"startDate": "2024-09-01T00:00:00",
"endDate": "2024-09-02T00:00:00",
Requesting a report with "endDate": "2024-09-01T23:59:59" would include reporting data from 2024-09-01T00:00:00 till 2024-09-01T23:00:00.
Timezone
The Timezone field sets the timezone of the report and can take the values:
- Network - sets the timezone to the timezone specified in the given Equativ customer network; it is usually specified during the initial setup process, i. e. when customers start working with Equativ
- UTC - sets the timezone to UTC
Filtering
Operators
The following operators can be used for filtering:
| Operator name | Operator full name | Applied to data type | Description |
|---|
|
contains
| contains | STRING | keeps only values contained in an element of the given list |
| gt | greater than | INTEGER | keeps only values greater than the provided value |
| in | in | INTEGER or STRING | keeps only values in the provided list |
| is | is | BOOLEAN | keeps only values equal to the provided value |
| lt | less than | INTEGER | keeps only values less than the unique provided value |
| not_in | not in | INTEGER | keeps only values different from the provided list |
Filtering sample
The report configuration sample below requests a report with the following filter criteria: InsertionId=123 AND (EnvironmentTypeId=0 OR CountryId=11)
{
"reportName": "doc_sample_4_filters",
"StartDate": "2023-10-01T00:00:00",
"EndDate": "2023-10-02T00:00:00",
"metrics": [
"Impressions"
],
"dimensions": [
"EnvironmentTypeName",
"CountryName"
],
"filters": [
[
{
"Field": "InsertionId",
"Operator": "IN",
"Values": [
123
]
}
],
[
{
"Field": "EnvironmentTypeId",
"Operator": "IN",
"Values": [
0
]
},
{
"Field": "CountryId",
"Operator": "IN",
"Values": [
11
]
}
]
],
"dateFormat": "yyyy-MM-dd",
"onFinishEmails": [
"example@example.com"
],
"timezone": "UTC",
"useCaseId": "Adserving"
}
Note that filter criteria within the same list (i. e. criteria inside the same pair of square brackets) are connected using the OR operator. Lists of criteria are connected with other lists of criteria using the AND operator.
The sample below shows the first rows of the generated csv report file for the report configuration above:
| EnvironmentTypeName | CountryName | Impressions |
|---|
| Web | costa rica | 17 |
| Web | tunisia | 0 |
| Web | estonia | 0 |
| Web | paraguay | 0 |
| Web | guatemala | 15 |
| Web | haiti | 3 |
| Web | el salvador | 7 |
| Web | colombia | 2 |
| Web | spain | 2 |
| Web | russian federation | 0 |
| … | … | … |
Report scheduling
You can use report scheduling to have a report generated on a regular basis.
Scheduled report sample
The sample below shows a report configuration for a scheduled report, generated once per day, containing data of the previous day.
{
"reportName": "doc_sample_5_scheduling",
"metrics": [
"impressions"
],
"dimensions": [
"insertionName"
],
"dateFormat": "yyyy-MM-dd",
"onFinishEmails": [
"example@example.com"
],
"timezone": "UTC",
"useCaseId": "RTB",
"scheduling": {
"frequency": "DAILY",
"period": "PREVIOUS_DAY",
"schedulingStartDate": "2023-10-16T11:05:00",
"schedulingEndDate": "2023-10-19T00:00:00"
}
}
This table summarizes all report instances the sample above will generate:
| Report # | Date/Time | Data contained in report |
| 1 | Oct. 16, 2023 at 11:05 | data from Oct. 15, 2023 |
| 2 | Oct. 17, 2023 at 11:05 | data from Oct. 16, 2023 |
| 3 | Oct. 18, 2023 at 11:05 | data from Oct. 17, 2023 |
Frequency of scheduled reports
The frequency value in scheduled reports defines the recurrence of the report:
| Frequency value | Frequency description | Example |
|---|
| FIXED_DATE/yyyy-MM-dd'T'HH:mm:ss | once, at the specified date | FIXED_DATE/2016-07-27T17:00:00 |
| HOURLY | every hour | |
| HOURLY*x | every x hours | HOURLY*4 |
| DAILY | every day | |
| DAILY*x | every x days | DAILY*4 |
| WEEKLY | every week | |
| WEEKLY*x | every x weeks | WEEKLY*4 |
| MONTHLY | every month | |
| MONTHLY*x | every x months | MONTHLY*2 |
Period of scheduled reports
The period value in scheduled reports defines the time frame each instance of the scheduled report will cover; for instance PREVIOUS_DAY means that each report will contain data from the previous day. The period field supports the following values:
- LAST_HOUR
- CURRENT_DAY
- PREVIOUS_DAY
- LAST_7_DAYS
- PREVIOUS_WEEK
- CURRENT_MONTH
- PREVIOUS_MONTH
Consolidation of reporting data for previous day
The consolidation of reporting data for any given day is completed within the first 6 hours (UTC) of the following day. Generating a report before the consolidation is completed leads to incomplete reporting data for the previous day.
For instance, if you set up a scheduled report with "frequency": "DAILY" and "period": "PREVIOUS_DAY", make sure you set the UTC time in "schedulingStartDate" to a value no earlier than T06:00:00 (for instance: "schedulingStartDate": "2024-10-16T06:00:00").
Relative dates
The following relative dates can be used in date fields:
| Value________________________ | Description | Example value______________ | Example value meaning |
|---|
| CURRENT_DAY+-x | the current day at midnight (0 hours, 0 minutes, 0 seconds, 0 ms), with the specified modifier | CURRENT_DAY-1
CURRENT_DAY+1 | yesterday
tomorrow at midnight |
| CURRENT_HOUR+-x | the current hour (lowered to the 0th minute) with the specified modifier | CURRENT_HOUR+1 | 15h00 (e. g. if the current time is 14h45) |
| CURRENT_WEEK+-x | the current week (lowered to Monday morning at 00h00) with the specified modifier | CURRENT_WEEK+1 | Monday morning at 00h00 in the upcoming week (e. g. if today is Wednesday) |
| CURRENT_MONTH+-x | the current month (lowered to the first day of the month at 00h00) with the specified modifier | CURRENT_MONTH+1 | 01 November at 00h00 (e. g. if today is 16th October) |
Delete report
Use the DELETE method to delete a one-time or a scheduled report. For more information, see section "Base URL and endpoints" in
Reporting API – Getting started.
Output format
File format
You can specify the file format of the report, using the FileFormat parameter:
- csv sets the file format to csv format (default format, applied if FileFormat is not specified)
- xlsx sets the file format to Excel format
The example report configuration below shows the FileFormat field set to xlsx.
{
"ReportName": "Reporting-Smart-20240619",
"OnFinishEmails": [
],
"StartDate": "2024-06-18T00:00:00",
"EndDate": "2024-06-19T00:00:00",
"Simulate": false,
"Metrics": [
{
"Field": "Impressions"
}
],
"Dimensions": [
"Attstatus"
],
"Filters": [
[
{
"Field": "PublisherId",
"Operator": "IN",
"Values": [
3491
]
}
]
],
"AllFilterFields": [],
"DateFormat": "yyyy-MM-dd",
"UseCaseId": "Adserving",
"Separator": "\t",
"FileFormat": "xlsx"
}
Custom column separator in csv reports
If FileFormat is set to csv or if it is not specified, you can specify a custom column separator (default separator: comma):
- \t in order to obtain a report containing tab separated values
- any other character, provided it is not longer than one single character.
The example report configuration below requests a report with tab separated values ("Separator": "\t") :
{
"ReportName": "Reporting-Smart-20240619",
"OnFinishEmails": [
],
"StartDate": "2024-06-18T00:00:00",
"EndDate": "2024-06-19T00:00:00",
"Simulate": false,
"Metrics": [
{
"Field": "Impressions"
}
],
"Dimensions": [
"Attstatus"
],
"Filters": [
[
{
"Field": "PublisherId",
"Operator": "IN",
"Values": [
3491
]
}
]
],
"AllFilterFields": [],
"DateFormat": "yyyy-MM-dd",
"UseCaseId": "Adserving",
"Timezone": "Network",
"FileFormat": "csv",
"Separator": "\t"
}
