Available dimensions and metrics

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

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

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.

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:

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:

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:

Frequency of scheduled reports

The frequency value in scheduled reports defines the recurrence of the report:

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:

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: get 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"
}