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 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:
|
| 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:
|
| 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:
|
| browser | string | Equals, NotEquals | Identifies the browser. Available options are:
|
| 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:
|
| biddingStrategy | string | Equals, NotEquals | Indicates the bidding strategy. Available values are:
|
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. |