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.