Reporting and Listing API Request Details

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Jun 6, 2017
Version 2Show Document
  • View in full screen mode

PubMatic API platform uses a  consistent format for query parameters to the Reporting and Listing API. Each query requires a start and end date. You may also supply additional query parameters such as dimensions, metrics, filters and sort order to refine your query.

 

This can be used with reporting and listing requests. Listing requests are served by the respective resource end points such as /deals, /flights, /insertionOrders and so on.

Query Parameters Summary

The following table summarizes the all the query parameters accepted by the Core reporting API. Click each parameter name for a detailed description.

                                                       

NameData TypeRequiredSummary
fromDateString

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.
toDateString

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.

metricsStringNoIndicates a list of comma-separated metrics, such as impressionCount,zeroBidRequests.If not provided all metric will available in response
dimensionsStringNoIndicates a list of comma-separated dimensions for your response data, such as pubId,siteId,campaginName.
sortStringNoIndicates a list of comma-separated dimensions and metrics indicating the sorting order and sorting direction for the returned data.
filtersStringNoIndicates the dimension or metric filters that restrict the data returned for your request.
pageNumberIntegerNoIndicates that you can use this parameter as a pagination.
pageSizeIntegerNoIndicates 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.
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.
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.
Example, dimensions=sitId,campaginId

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.
Example, metrics=impressionCount,zeroBid

Sort

Optional. A list of metrics and dimensions indicating the sorting order and sorting direction for the returned data.
Sorting direction defaults to ascending and can be changed to descending by using a minus sign (-) prefix on the 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.
Example, 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  grater than 10000  served by campaign name starts with the string xyz or end with abc.

&filters=impressionCount gt 10000&filters=campaignName like xyz*, campaignName like *abc

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:
1. Single filters should contain either Dimensions/metric.
2. Operator are not cases sensitive for example noteq and NOTEQ considered same.

Filter Operators

                                                       

OperatorDescriptionSupported Data TypesExamples
eqEqualsALL Data Types 
notEqNot EqualsALL Data Types 
gtGrater ThanNumaric and Date 
gtEqGrater Than or EqualsNumaric and Date 
ltLess ThanNumaric and Date 
lteqLess Than or EqualNumaric and Date 
likelikeString 
StringStringString 

Attachments

    Outcomes