Reporting and Listing API Request Details
PubMatic API platform uses a consistent format for query parameters to the Reporting and Listing APIs. Each query requires a start and end date. You can also supply additional query parameters with reporting and listing requests such as, dimensions, metrics, filters, and sort, to refine your query. Respective resource endpoints such as /deals, /flights, /insertionOrders, and so on, serve listing requests.
Query Parameters Summary
The following table summarizes the all the query parameters accepted by the Core reporting API.
| Name | Data Type | Required | Summary |
|---|---|---|---|
| fromDate | String | Yes for Reporting No for Listing using a resource. | Indicates the start date for fetching reporting data. Requests can specify a start date formatted as YYYY-MM-DD. |
| toDate | String | Yes for Reporting No for Listing using a resource. | Indicates the end date for fetching reporting data. Requests can specify a start date formatted as YYYY-MM-DD. |
| metrics | String | No | Indicates a list of comma-separated metrics, such as impressionCount,zeroBidRequests.If not provided all metric will available in response |
| dimensions | String | No | Indicates a list of comma-separated dimensions for your response data, such as pubId,siteId,campaginName. |
| sort | String | No | Indicates a list of comma-separated dimensions and metrics indicating the sorting order and sorting direction for the returned data. |
| filters | String | No | Indicates the dimension or metric filters that restrict the data returned for your request. |
| pageNumber | Integer | No | Indicates that you can use this parameter as a pagination. |
| pageSize | Integer | No | Indicates the maximum number of rows to include in the response. |
fromDate
Required for all reporting data requests must specify a date range. If you do not include fromDate and toDate parameters in the request, the server returns an error. Date values should be for a specific date by using the pattern YYYY-MM-DD; for example, fromDate=2014-01-01.
toDate
Required for all reporting data requests must specify a date range. If you do not include fromDate and toDate parameters in the request, the server returns an error. Date values should be for a specific date by using the pattern YYYY-MM-DD; for example, XA toDate=2014-01-31.
Dimensions
Optional.The dimensions parameter breaks down metrics by common criteria; for example, by siteId or campaginId While you can ask for the total number of impressions to your site, it might be more interesting to ask for the number of impressions broken down by site. In this case, you'll see the number of impressions from all sites; for example, dimensions=sitId,campaginId. See Reporting Glossary for a list of available dimensions.
Metrics
Optional. The aggregated statistics of various entities such as impressionCount, bid requests etc. If a query has no dimensions parameter, the returned metrics provide aggregate values for the requested date range. However, when dimensions are requested, values are grouped by dimension value. For example impressionCount requested with siteId returns the total impressionCount per site. If a query has no metrics then all metrics will be available in response; for example, metrics=impressionCount,zeroBid. See Reporting Glossary for a list of available metrics.
Sort
Optional. A list of metrics and dimensions indicating the sorting order and sorting direction for the returned data.
Sorting direction defaults to ascending but you can change it to descending using a minus sign (-) prefix for a requested field.
Sorting the results of a query enables you to ask different questions about your data. For example, to address the question "What are my top sites, and which impressionsCount do they provide most with less zero bids?" you can make a query with the the following parameter: sort=-impressionCount,zeroBid.
Filters
Optional. The filters query string parameter restricts the data returned from your request. To use the filters parameter, supply a dimension or metric on which to filter, followed by the filter expression. For example, the following query requests impressionCount greater than 10000 served by campaign name starts with the string xyz or ends with abc.
&filters=impressionCount gt 10000&filters=campaignName like xyz*, campaignName like *abc
Searchable Fields
Name | Data Type | Required | Summary | Sample Filter Data | Sample Sort Data | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
loggedInOwnerId | Long | Yes | A valid Publisher ID, DSP ID, or Buyer ID |
| |||||||||
loggedInOwnerTypeId | Integer | Yes | One of the following integer values that indicates the account type of the issuing the request:
|
| |||||||||
id | Long | No | SEARCH and SORT is supported. Plain SEARCH is depreciated as we have a separate endpoint for it. |
| For ascending order, use ?sort=id For descending order, use ? | ||||||||
name | String | No | SEARCH and SORT is allowed in this field. |
When name search is used, we also search for dealId. | For ascending order, use ?sort=name For descending order, use ?sort=-name | ||||||||
additionalInfo | String | No | Search deal by its message component. SORT is depreciated for this field. |
| |||||||||
status | Integer | No | SEARCH and SORT is allowed in this field. |
| For ascending order, use ?sort=status For descending order, use ?sort=-status | ||||||||
auctionType | Integer | No | SEARCH and SORT is allowed in this field. |
| For ascending order, use ?sort=auctionType For descending order, use ? | ||||||||
startDate | Date | No | SEARCH and SORT supported. BETWEEN attribute is not currently supported. But you can use filters like
|
| ?sort=-startDate | ||||||||
endDate | Date | No | SEARCH and SORT supported. |
| |||||||||
| flooreCPM | Integer | No | SEARCH and SORT supported. | ?filters=flooreCPM gt 1 | |||||||||
| channelType | Integer | No | SEARCH is supported on this field | ?filters=channelType eq 6 | |||||||||
| dealCategory | Integer | No | SEARCH is supported on this field | ?filters=dealCategory eq 1 |
Sample Calls:
https://api.pubmatic.com/v3/pmp/deals?view=summary&filters=loggedInOwnerId%20eq%2080&filters=loggedInOwnerTypeId%20eq%205&pageSize=2&filters=name+like+*PM-CLOM-8057*
https://api.pubmatic.com/v3/pmp/deals?view=summary&filters=loggedInOwnerId%20eq%2080&filters=loggedInOwnerTypeId%20eq%205&pageSize=2&filters=channelType+eq+6&filters=status+eq+1
https://api.pubmatic.com/v3/pmp/deals?view=summary&filters=loggedInOwnerId%20eq%2080&filters=loggedInOwnerTypeId%20eq%205&pageSize=2&filters=dealCategory+eq+1
Filter Syntax
A single filter uses the form:
name operator value
In this syntax:
- name - the name of the dimension or metric to filter on. Example, campaignName filters on the impressionCount metric.
- operator - defines the type of filter match to use. Operators are specific to either dimensions or metrics.
- value - states the values to be included in or excluded from the results.In case of String * character supported to find like query and all % character will be ignored.
- There should be space between name, operator and value.
Note…
- Single filters should contain either Dimensions/metric.
- Operators are not cases sensitive for example
noteqandNOTEQare equal.
Filter Operators
| Operator | Description | Supported Data Types |
|---|---|---|
eq | Equals | ALL Data Types |
notEq | Not Equals | ALL Data Types |
gt | Grater Than | Numaric and Date |
gtEq | Grater Than or Equals | Numaric and Date |
lt | Less Than | Numaric and Date |
lteq | Less Than or Equal | Numaric and Date |
like | like | String |
String | String | String |
Overview
Content Tools