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

Note: Please check with your Account Manager to provide the required Bearer Token to make a successful API Request.

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 specifythe date range in the request. dateFilter
DATE_LOOKUP_INVALID Returned if the specified dateexceeds the maximum look-back days. You can search for a maximum of 365 days. dateFilter
DATE_RANGE_INVALID Thiserror message will be returned if the date range mentioned in the request isinvalid. This can happen if:The end date in therequest is before the start date.The start date and/or theend date in the request are later than the present date. dateFilter
DATE_RANGE_EXCEEDED This error message is returnedif the specified date range in the request exceeds the maximum number of daysallowed. The date range should not be greater than a quarter. dateFilter
DIMENSION_OUTPUT_NAME_INVALID Returnedif the outputName is invalid. The following characters are accepted in theoutputName field:[A to Z] and [a to z][0 to 9] and [ _ ] dimensions[x].outputName
DIMENSION_OUTPUT_NAME_DUPLICATE Returned if the outputName isduplicated across measure and dimension. dimensions[x].outputName
DIMENSION_FIELD_REQUIRED Returned if dimension fieldparameter is not specified in the request. dimensions[x].field
DIMENSION_INVALID Returned if the dimensionspecified in the request is invalid. This error will be returned if there isa spelling error in the dimension name or the dimension specified is notsupported by the system. dimensions[x].field
DIMENSIONS_REQUIRED Returned when you do notspecify the dimension parameter in the request. dimensions
DIMENSIONS_TOO_FEW Returned when you specify thedimension parameter but do not specify the value. Ensure that you specify aminimum of 1 value in the dimension parameter. dimensions
DIMENSIONS_TOO_MANY Returned if more than 8dimensions are specified in a request. dimensions
END_DATE_INVALID Returned if the end date is notin the valid format, YYYY-MM-DD. dateFilter.end
END_DATE_REQUIRED Returned if the end date is notspecified in the request. dateFilter.end
FILTER_FIELD_INVALID Returned if the filterspecified in the request is invalid. This error will be returned if there isa spelling error in the filter name or the filter specified is not supportedby the system. filters[x].field
FILTER_FIELD_REQUIRED Returned when you do notspecify the filter parameter in the request. filters[x].field
FILTER_OPERATOR_REQUIRED Returned if you do not specifythe filter operator in the request. filters[x].operator
FILTER_OPERATOR_INVALID Returned if the filter operatormentioned in the request is invalid. filters[x].operator
FILTER_VALUE_INVALID Thiserror is returned when:The data type in thefilter value request is invalid. When you specify a filterthat is not available in the system or there is a spelling error in thefield filters[x].values[x]
FILTER_VALUES_TOO_FEW Returned when you specify thefilter parameter but do not specify the value. Ensure that you specify aminimum of 1 value in the filter parameter. filters[x].values
MEASURE_OUTPUT_NAME_INVALID Returnedif the field outputName is invalid. The following characters are accepted inthe outputName field:[A to Z] and [a to z][0 to 9] and [ _ ] measures[x].outputName
MEASURE_OUTPUT_NAME_DUPLICATE Returned if the outputName isduplicated across measure and dimension. measures[x].outputName
MEASURE_INVALID Returned when the measurespecified in the request is invalid. A spelling error or a measure notsupported by the system will return this error. measures[x].field
MEASURE_FIELD_REQUIRED Returned if the measure fieldparameter is not specified in the request. measures[x].field
MEASURES_REQUIRED Returned when you do notspecify the measure parameter in the request. measures
MEASURES_TOO_FEW Returned when you specify themeasure parameter but do not specify the value. Ensure that you specify aminimum of 1 value in the measure parameter. measures
PAGE_NUMBER_TOO_LOW Returned when the number ofpages mentioned in your request is less than 1. paging.pageNumber
PAGE_SIZE_TOO_LOW Returned when the number ofrecords to be displayed on the page is less than 50. paging.pageSize
PAGE_SIZE_TOO_HIGH Returned when the number ofrecords to be displayed on the page is more than 5000. paging.pageSize
START_DATE_INVALID Returned if the start date isnot in the valid format, YYYY-MM-DD. dateFilter.start
START_DATE_REQUIRED Returned if the start date isnot specified in the request. dateFilter.start
SORTING_FIELD_INVALID Returned if the sorting fieldmentioned in the request is invalid. sorting.field
SORTING_ORDER_INVALID Returnedif the sorting order is invalid.Note: Sorting field value must beadded 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.