In this guide, we will provide you step by step instructions to integrate the APIs and make your first call. In addition, this guide includes information about the various APIs and their request and response parameters. Appropriate examples or sample codes are provided in this document for a better understanding of the API.

The Reports API allows you to create and submit a report request to the server. Based on the request parameters, you can customize the report as required.

A request is a combination of header and body parameters. This article provides more information about the header and the body parameters.

Identifying the Request Header Parameters

Endpoint: https://campaigns.performmedia.com/reportservice/api/v1/reports

While creating a request, you need to specify the following mandatory parameters in the header of the request.

Example with Request Header

POST campaigns.performmedia.com/reportservice/api/v1/reports HTTP/2

Host: campaigns.performmedia.com

Content-Type: application/json

Authorization: Bearer <ACCESS_TOKEN>

The following table provides information about the header parameters and their descriptions.

Header Parameters Description
POST The method of the request. Ensure that it is POST and the path is specified.
Host Indicates the endpoint host name.
Content-Type Specify the content type. For example, application/JSON
Authorization Specify Bearer and the ACCESS_TOKEN

 

 

Identifying the Request Body Parameters

You can create a report definition in a JSON format, where you specify the elements to be included in the report. The report definition is part of the body of the request.

Following is a sample request for generating a report based on campaign information for a particular date range.

The following table provides information about the body parameters in the request.

NEED ASSISTANCE BUILDING THIS TABLE SO THAT IT WORKS-MAYBE USE NEW TABLE BUILDER MODULE

Note: Parameters marked with * are mandatory in the API request.

 

 

Identifying the Response Parameters

If all the parameters are correctly defined in the request, you should receive an output with the requested data. However, if there are any issues with the request, then an error will be returned. For more information about the error message, refer to the API Validation Table.

Following is an example of a response.

The dimensions and measures are displayed using their outputName to reduce the size of the response. For more information about the supported dimensions and measures, refer to the List of Dimensions and List of Measures section.

The response consists of the following fields:

Metadata Field

This field provides the metadata information about the response. This field includes the following information.

rowCount The total number of matching rows present for this query. 

Note: rowCount will be independent of the total number of rows returned in the response

pageAggregations Returns the average or count of all the measures mapped with the provided outputName for a particular report in JSON format.

Data Field

The Data section includes the actual data that you have requested in the request. 

Identifying the Error Messages

There may be cases where you receive an error as a response. There are two primary types of error responses. 

Error Type #1: Bad Request (sample error format below)

In the above example, the error message is returned because the dimensions provided in the request are invalid. This can occur either if the dimension is unavailable or there is a spelling error. To know more about error codes, refer to the API Validation Table.

Error Type #2: Internal Server Error (sample error format below)

API Validation Table
The following table lists API validation fields and error codes associated with those fields.

Error Code Description API Validation Field 
DATE_FILTER_REQUIRED Returned if you do not specify the date range in the request. dateFilter
DATE_LOOKUP_INVALID Returned if the specified date exceeds the maximum look-back days. You can search for a maximum of 365 days. dateFilter
DATE_RANGE_INVALID This error message will be returned if the date range mentioned in the request is invalid. This can happen if:

  • The end date in the request is before the start date.
  • The start date and/or the end date in the request are later than the present date.
dateFilter
DATE_RANGE_EXCEEDED This error message is returned if the specified date range in the request exceeds the maximum number of days allowed. The date range should not be greater than a quarter. dateFilter
DIMENSION_OUTPUT_NAME_INVALID Returned if the outputName is invalid. The following characters are accepted in the outputName field:

  • [A to Z] and [a to z]
  • [0 to 9] and [ _ ]
dimensions[x].outputName
DIMENSION_OUTPUT_NAME_DUPLICATE Returned if the outputName is duplicated across measure and dimension.  dimensions[x].outputName
DIMENSION_FIELD_REQUIRED Returned if dimension field parameter is not specified in the request. dimensions[x].field
DIMENSION_INVALID Returned if the dimension specified in the request is invalid. This error will be returned if there is a spelling error in the dimension name or the dimension specified is not supported by the system.  dimensions[x].field
DIMENSIONS_REQUIRED Returned when you do not specify the dimension parameter in the request. dimensions
DIMENSIONS_TOO_FEW Returned when you specify the dimension parameter but do not specify the value. Ensure that you specify a minimum of 1 value in the dimension parameter. dimensions
DIMENSIONS_TOO_MANY Returned if more than 8 dimensions are specified in a request. dimensions
END_DATE_INVALID Returned if the end date is not in the valid format, YYYY-MM-DD. dateFilter.end
END_DATE_REQUIRED Returned if the end date is not specified in the request. dateFilter.end
FILTER_FIELD_INVALID Returned if the filter specified in the request is invalid. This error will be returned if there is a spelling error in the filter name or the filter specified is not supported by the system.  filters[x].field
FILTER_FIELD_REQUIRED Returned when you do not specify the filter parameter in the request. filters[x].field
FILTER_OPERATOR_REQUIRED Returned if you do not specify the filter operator in the request. filters[x].operator
FILTER_OPERATOR_INVALID Returned if the filter operator mentioned in the request is invalid. filters[x].operator
FILTER_VALUE_INVALID This error is returned when:

  • The data type in the filter value request is invalid. 
  • When you specify a filter that is not available in the system or there is a spelling error in the field
filters[x].values[x]
FILTER_VALUES_TOO_FEW Returned when you specify the filter parameter but do not specify the value. Ensure that you specify a minimum of 1 value in the filter parameter. filters[x].values
MEASURE_OUTPUT_NAME_INVALID Returned if the field outputName is invalid. The following characters are accepted in the outputName field:

  • [A to Z] and [a to z]
  • [0 to 9] and [ _ ]
measures[x].outputName
MEASURE_OUTPUT_NAME_DUPLICATE Returned if the outputName is duplicated across measure and dimension.  measures[x].outputName
MEASURE_INVALID Returned when the measure specified in the request is invalid. A spelling error or a measure not supported by the system will return this error.  measures[x].field
MEASURE_FIELD_REQUIRED Returned if the measure field parameter is not specified in the request. measures[x].field
MEASURES_REQUIRED Returned when you do not specify the measure parameter in the request. measures
MEASURES_TOO_FEW Returned when you specify the measure parameter but do not specify the value. Ensure that you specify a minimum of 1 value in the measure parameter. measures
PAGE_NUMBER_TOO_LOW Returned when the number of pages mentioned in your request is less than 1. paging.pageNumber
PAGE_SIZE_TOO_LOW Returned when the number of records to be displayed on the page is less than 50. paging.pageSize
PAGE_SIZE_TOO_HIGH Returned when the number of records to be displayed on the page is more than 5000. paging.pageSize
START_DATE_INVALID Returned if the start date is not in the valid format, YYYY-MM-DD. dateFilter.start
START_DATE_REQUIRED Returned if the start date is not specified in the request. dateFilter.start
SORTING_FIELD_INVALID Returned if the sorting field mentioned in the request is invalid.  sorting.field
SORTING_ORDER_INVALID Returned if the sorting order is invalid.

Note: Sorting field value must be added either as dimension or measure

sorting.order

 

Appendix A: List of Dimensions

The following table provides a list of supported dimensions:

Field Name Data Type Filter Operators Supported Notes
date dateTime Indicates the date. Should be in the following format:

YYYY-MM-DD

hour int Equals, NotEquals Indicates the hour of the day. The acceptable values are:

[0, 1, 2, 3,…,23]

month string Equals, NotEquals Indicates the month. The available values are:

[January, February,…, December]

campaign string Equals, NotEquals, Like Indicates the Campaign name.
campaignId int Equals, NotEquals Indicates the Campaign ID.
campaignTag string Equals, NotEquals, Like Indicates the campaign tag for that campaign. For example,
campaignType string Equals, NotEquals Indicates the type of campaign. The values are following:

  • Search
  • Keyword Sponsorship
  • Native
adGroup string Equals, NotEquals, Like Indicates the name of the Ad group.
adGroupId int Equals, NotEquals Indicates the Ad group ID.
adId int Indicates the Ad ID.
keywordMatchType string Equals, NotEquals Indicates the keyword match type. Available options are:

  • Broad
  • Phrase
  • Exact
matchedTerm string Equals, NotEquals, Like Indicates the Match Term that will be used to match your Ads with searches.
category string Indicates the category name. For example, health -> vision care
device string Equals, NotEquals Indicates the device. The available options are:

  • Desktop
  • Tablet
  • Smart Phone
  • Others
browser string Equals, NotEquals Identifies the browser.  Available options are:

  • Google Chrome
  • Internet Edge
  • Internet Explorer
  • Mozilla Firefox
  • Safari
  • Others
countryCode string Equals, NotEquals Indicates the country code. Supports ISO ALPHA-2 Codes. For example, US.
publisherId string Equals, NotEquals, Like Indicate the Publisher Identifiers.
conversionEvent string Equals, NotEquals, Like Indicates the conversion event.
biddingType string Equals, NotEquals Indicates the bidding type used. Available values are:

  • CPM
  • CPC
  • CPA
biddingStrategy string Equals, NotEquals Indicates the bidding strategy. Available values are:

  • Auto
  • Manual

 

Appendix B: List of Measures

The following table provides a list of supported dimensions:

Field Name Data Type Description
impressions int Indicates the total number of served Ad impressions.
clicks int Indicates the total number of Ad clicks.
ctr decimal Indicates the click-through rate for an Ad. It defines how often people who see your Ad end up clicking it.
cost decimal Indicates the total billing amount.
conversions decimal Sum of weighted events which are counted as conversions.
conversionRate decimal The average number of conversions per Ad interaction, shown as a percentage.
conversionValue decimal Indicates the aggregated Value of weighted conversions as specified by the advertiser.
cpc decimal Indicates the average cost per click.
cpm decimal Indicates the average cost per 1000 impressions.
cpa decimal Indicates the average cost per action.
valuePerConversion decimal Indicates approximately how much, on average, each of your conversions is worth.