Page tree


Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
top
top
Table of Contents
indent20px
stylenone

The following methods are supported for pulling analytics data:

  • API pull (details below for pulling data for Publisher, Buyer or DSP)
    • The PubMatic Analytics API provides the ability to view and interact data insights to improve performance. Our APIs are designed to be easily integrated; they are simple HTTP requests supporting the GET protocol to send a request to the PubMatic Analytics API Server with mandatory and optional parameters in the query string. PubMatic's Analytics API provides query parameters such as dimensions, metrics, filters, and the query date range. The response is JSON format.


      The PubMatic Request contains the following set of details:

      • HTTP Request with GET protocol
      • HTTP parameters
      • HTTP head


Warning

Before using PubMatic APIs, first generate the API Token. For more information, refer to  Getting Started with PubMatic APIs .

  


Get the Bulk-Data Details for a Publisher

This API provides information about how to access bulk data details for a specific publisher. 


Sample Request Response

Request

         

URIhttp://{domainName}//data/publisher/{publisherId}
HTTP MethodGET


Request Headers               

Header NameTypeValueRequiredDescription
Authorizationstring  Bearer
${access_token}
Yes

The access token generated for authentication should be sent in place of ${access_token}.
 
Example:
 
curl  "http://api.pubmatic.com/v1/analytics/data/publisher/xxxxx?dateUnit=date&dimensions=siteId&filters=&fromDate=2015-01-01T00:00&metrics=revenue,paidImpressions,ecpm=1&pageSize=10&sort=-revenue&toDate=2015-01-31T23:59" -H "Authorization: Bearer BDxxxx9d"

Request Path Parameters                 

Parameter NameTypeRequiredValidationsDescription
publisherIdIntegerYesPublishers can only query their own data.Indicates the publisher ID.

Request Query Parameters                                                                     

Parameter NameTypeRequiredDescription
fromDatestringYes

Start date of data retrieval.
 
Example:
2013-03-01T00:00
 
PubMatic uses this standard date format even if the dateUnit parameter is different ‰ŰŇ for example, week.

toDatestringYes

End date of data retrieval.

Example:
2015-03-29T23:59

Info
Note: The conclusion time on the final end date (in this example, 3-29) should be 23:59. A date and time format of 03-30T00:00 would return some data from 3-30.


compFromDatestringNoComparison period start date.
compToDatestringNo

Comparison period end date.

Info
Note: The compFromDate/compToDate period should be within the same timespan as the original fromDate/toDate period.


dimensionsstringNo

Dimensions are attributes available in the PubMatic system.
 
Examples:
Country, Platform, Site
 
In case of multiple entries, use a comma-separated format.
 
Example: 
<dim1>,<dim2>

metricsstringYes

Metrics measure specified dimensions.
 
Example:
Publisher 123 has 500 impressions on the U.S. geo and mobile platform.
 
In case of multiple entries, use a comma-separated format.
 
Example:
<metric1>,<metric2>
 

sortstringNo

By default, the sort order is ascending. To change to descending, prefix a minus sign - to the requested field.

Example:
To determine which sites provide the most paidImpressions with fewest zero bids, use
sort=-paidImpressions,totalBidRequests

Info
Note: The sort parameter can be used only with measurements included in the metrics list.


filtersstringNoFor more information on filters, see "Filters."
dateUnitstringNo

The date unit to query in the aggregation. Possible options are:

  • hour
  • date
  • week
  • month
  • quarter

 
pageSizeintegerNo

Maximum number of rows to include in the response.
 
Example:
"40" returns up to 40 rowsResponse


Response Headers

             

Response Header NameTypeDescription
Content-Typeapplication/jsonJSON response

 

Response Body                                 

Response Body ParameterTypeDescription
alertstring

Alert message from server. In most cases, it will be null.
 
Example:
"alert": null

columnsstring[]

Dimension and metrics columns. Please see the relevant reference section for a complete list of dimensions and metrics and their limitations.
 
Example:

    "columns": [
        "dealMetaId",
        "revenue",
        "paidImpressions",
        "ecpm"
    ],
 
dealMetaId is a special dimension in query for additional columns to be added on returned response.
Example:
If we query on dealMetaId, revenue, paidImpressions, and ecmp, we shall have one more column (publisherdealId) added to the response. The rows section will also include the new column value.
 
"columns": [
    "dealMetaId",
    "publisherDealId",
    "revenue",
    "paidImpressions",
    "ecpm"
],

dataFreshnessobject

The date on which the settings of the dataset were last updated.
 
Example: 
    "dataFreshness": {
         "dataFreshnessHour": "2015-03-12T04",
         "timeZone": "PST"
     },
 

 displayValue object

The display value of the "ID."
 
Example:
dealMetaId "13497" has a description (name) of "xxx"
 
    "displayValue": {
        "dealMetaId": {
            "13497": "xxx",
            "16083": "yyy",

 rows array of array

The main table-like data structure, in which each column in the row corresponds to the columns definition in the same sequence.
 
Example:
The records below would be presented in columns ["dealMetaId,","publisherDealId," "revenue," "paidImpressions," "ecpm"]
"rows": [
    [
        "16651",
        "PM-XXX339",
        83365.114596,
        10126407.0,
        8.232448
    ],


Info
Note: When using the dealMetaId dimension, the publisherDealId must be associated.



Example:
   "columns": [
        "dealMetaId",
        "publisherDealId",
        "revenue"
    ],
    "rows": [
        [
            "10534",
            "PM-SUU63339",
            0
        ],

 

Sample Response JSON   

Code Block
languagejs
linenumberstrue
{
  "columns": [
    "date",
    "paidImpressions",
    "revenue"
  ],
  "rows": [
    [
      "2016-06-01",
      25249100,
      42000.554432
    ],
    [
      "2016-06-02",
      28841014,
      51154.094958
    ],
    [
      "2016-06-03",
      25200705,
      63640.230188
    ],
    [
      "2016-06-04",
      35254500,
      71632.23456
    ],
    [
      "2016-06-05",
      237219940,
      87654.32123
    ]
  ],
  "displayValue": {
    "date": {
      "2016-06-02": "2016-06-02",
      "2016-06-01": "2016-06-01",
      "2016-06-05": "2016-06-05",
      "2016-06-03": "2016-06-03",
      "2016-06-04": "2016-06-04"
    }
  },
  "currency": "USD",
  "alert": null,
  "dataFreshness": {
    "dataFreshnessHour": "2016-06-16T05",
    "timeZone": "PST"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Below are the common HTTP status codes sent in REST API response by PubMatic API platform:


HTTP Status Codes

                                                   

StatusDescriptionTypeDescription
200OKsuccessThe request has been successfully processed; check contents of body.
400Bad Requestclient-side errorThere is some validation failure; check the response body for error details.
401Unauthorized There is an authentication or authorization failure; check the response body for specific details.
403Forbidden You are not subscribed to this feature of the Platform.
404Not Found The server does not have this resource.
413Request Entity Too Large The request content exceeds the size limit.  This may be the number of records or the actual content size.
500Internal Server ErrorAPI-side errorThere is problem in the PubMatic API Platform. Please contact the PubMatic API support team.

Available Dimensions


Dimensions for Historic Data

Dimensions are attributes, such as Country, Platform, and Site, available in the PubMatic system. The following tables provides information about dimension grouping. 


Dimension IDData TypeDescription
adFormatId numericType of Ad associated with the impression (e.g., video display)
adNetworkGroupId  numericName of the parent Ad Network that monetized the impression.
adNetworkVariantId numericName of the parent Ad Network's campaign that monetized the impression.
pbReasonnumericReason for Passback.
tldEntitynumericTop level domain Entity. Applicable in the case of mobile impressions.
tldIdnumericTop level domain.
adSizeIdnumericSize of the ad associated with the impression (e.g., 200 x 800)
adTagIdnumericName of the ad tag used when an impression was requested.
advertiserCategoryIdnumericCategory of the advertiser.
advertiserId numericName of the advertiser associated with the ad.
atdIdnumericName of the agency, ATD or buyer associated with the DSP that won the impression.
campaignIdnumericCampaign of the advertiser associated with the ad.
categoryIdnumericCategory of the site from which an impression was requested.  
channelIdnumericSales channel through which the impression was won (e.g., RTB, PMP).
cookied booleanIndicates whether or not the DSP's cookies were dropped when an impression was requested.
countryId numericCountry from which an impression was requested. (Refer to How Countries are Reported in Analytics Reports for more information)
creativeIdnumericThe creative id delivered in the ad response. This applies to video ads ONLY.
datestringDate (YYYY-MM-DD format) on which an impression was requested.
dealMetaIdnumericName of the Marketplace Deal that won the impression.
domainId  numericDomain name (web addresses) of the advertiser. The domains are identified by the landing page of the impression displayed.
dspIdnumericName of the DSP that won the impression.
foldPositionId numericFold placement associated with the ad tag used when an impression was requested.
hourstringTime (YYY-MM-DD'T'HH format) at which an impression was received.
mobDeviceIdFlagbooleanIndicates whether the visitor's Device ID is present in the impression requests.
mobDeviceIdTypeIdbooleanType of Device ID used by the visitor to generate an impression request. 
mobDeviceTypeId booleanType of Device used by the visitor to generate an impression request. 
mobGeoSourceFlagbooleanSource that provided the visitor's geographical location.
mobLatLongFlagbooleanIndicates whether the visitor's latitude/longitude details were included in the impression request.
mobMakeModelIdnumericMobile Make/Model Id.
mobOsId  numericMobile Operating System Id.
monthstringMonth (YYYY-MM format) at which an impression was  received .
platformId numericPlatform through which an impression was requested (e.g., Web, Mobile Web)
publisherDealId numericThe Publisher Deal Id.
sectionIdnumericSection of the site from which an impression was requested.
secureStatusbooleanIndicates whether the inventory is secure.
siteIdnumericURL of the site from which an impression was requested.
videoClientIdnumericThis will be present when a video tracker (e.g. event, impression, error) is fired by the PubMatic VPAID component. This ID will represent whether it is a Flash VPAID component (1) or HTML/JS VPAID component (2), otherwise if not present (NULL) it means the PubMatic VPAID component was not present.
videoErrorId numericVideo Error Code. Includes the IAB VAST error codes along with PubMatic custom video error codes that provide more granularity for debugging.
videoEventIdnumericEvent id represents the type of video tracker event that was fired by the video player. Events can include start event, click event, 25%, 50%, completion, etc.
weekstringWeek (YYY'W'ww format) at which an impression was  received .

Dimensions for Domain Data

Info
The Domain report is available only for whitelisted publishers and channel parters for dimensions visible in the PubUI.
                                 
Dimension IDData TypeDescriptionadNetworkVariantId   numericName of the parent Ad Network that monetized the impression.adTagIdnumericName of the ad tag used when an impression was requested.campaignIdnumericCampaign of the advertiser associated with the ad.date stringDate (YYYY-MM-DD format) on which an impression was requested.pbReasonnumeric Reason for Passback. pubIdintegerPublisher associated with the impression requests.siteIdnumericURL of the site from which an impression was requested.tldEntitynumericTop level domain Entity. Applicable in the case of mobile impressions.tldIdnumericTop level domain.

Please note that not all dimensions and metrics are supported together. For more information and verification, login to PubMatic Analytics UI.

Dimensions for Rule Data (RTB Rules Report in MBC Analytics)

Dimension IDData TypeDescription
campaignId numericCampaign of the advertiser associated with the ad.
datestringDate (YYYY-MM-DD format) on which an impression was requested.
pubIdintegerPublisher associated with the impression requests.
ruleIdnumericWinning Rule ID and Ad Server logs.
ruleMetaIdnumericRule Meta ID for PMPF rule type.
siteIdnumericURL of the site from which an impression was requested.


Available Metrics   

Metrics for Historic Data


Metric IDData TypeDescription
averageBidEcpmAdvnumericAverage CPM of the bid responses associated with an advertiser.  
averageBidEcpmAtdnumericAverage CPM of the bid responses associated with a buyer.  
averageBidEcpmDsp numericAverage CPM of the bid responses received from a DSP. 
pbImpressionsnumericNumber of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system.
bidPercentageDspnumeric

Number of bids responded as % of bid request sent.

 

Formula :

bidPercentageDsp = ( nonZeroBidResponses / totalBidsRequests ) * 100   

bidWinRateAdvnumericRate of won bids expressed as a percentage of total bids for advertiser.

 

Formula :
bidWinRateAdv = paidImpressions * 100 / nonZeroBidReceived
bidWinRateAtd numeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.

 

Formula

(Paid Impressions * 100) / Non-Zero Bids Received

bidWinRateDspnumeric

A DSP's paid impressions divided by non-zero bid responses, expressed as a percentage.

 

Formula:

(Paid Impressions * 100) / Non-Zero Bid Responses

clicksnumericNumber of paid impressions clicked by users.   
ctrnumeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula :
clicks / paidImpressions *100

defaultsnumericNumber of impressions not served (defaulted) by an ad network configured in the PubMatic system. 
ecpmnumericAverage CPM (cost per thousand) for the impressions.
fillRate numericPercentage of times an ad is displayed to the visitor. Higher rates are better.
gEcpmnumericGross Ecpm
lostBidsAmountByAuctionnumericAmount of the bid responses that lost to the winning bid response in the auction.
lostBidsAmountByBlockList numericAmount of the bid responses that lost to the winning bid response in the Brand Control blocklist.
lostBidsAmountByCBLK numericLost Bid Amount (Creative Block)
lostBidsAmountByDWLFnumericAmount of the bid responses that lost because the advertiser's associated category/name/domain was not included in the Marketplace deals.
lostBidsAmountByFloornumericAmount of the bid responses that lost because their value was below the floor set in the Marketplace Rule Manager. 
lostBidsByAuctionnumericNumber of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  
lostBidsByBlockListnumericNumber of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s whitelist. 
lostBidsByCBLK  numericLost Bid Count (Creative Block)
lostBidsByDWLFnumericNumber of bid responses that did not win the impression because the associated Marketplace deal's whitelist did (DWLF) not include the advertiser.
lostBidsByFloor numericNumber of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.     
lostBidsEcpmAdvnumericAverage CPM of the bid responses associated with an advertiser.  
lostBidsEcpmAtd numericAverage CPM of the bid responses associated with a buyer.
lostBidsEcpmByAuctionnumericeCPM of the bid responses that lost to the winning bid response in the auction. 
lostBidsEcpmByBlockListnumericeCPM of the bid responses that lost because the advertiser's associated category/name/domain was added in the Brand Control blocklist. 
lostBidsEcpmByDWLFnumericeCPM of the bid responses that lost because the advertiser'sassociated category/name/domain was not included in the Marketplace deals' whitelist. 
lostBidsEcpmByFloornumericeCPM of the bid responses which lost because their value was below the floor set in the Marketplace Rule Manager.
lostBidsEcpmDsp numericeCPM of the bid responses associated with a DSP that lost the impressions.  
lostBidsTotalAmount numericTotal amount of the bid responses that lost due to a reason other than that described in the Lost Bids Amount (Auction) metric. 
measuredImpressionsnumericNumber of impressions measured by IAS 
nonZeroBidReceivednumericNumber of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually. 
nonZeroBidResponsesnumericNumber of bid responses from demand partners that had a non-zero bid value; indicates bid responses intended to participate in the auction.
paidImpressionsnumericNumber of impressions won by the demand partner.
pbImpressionsBotnumericNumber of impressions passed back to the publisher because requests came from a Web bot.
pbImpressionsNet numeriNumber of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system. 
pbImpressionsNonApproved numericNumber of impressions passed back to the publisher because its site URL was either not included in the publisher's whitelisted domains or included in the global supply-side blocklist.  
percentInViewForMoreThan15secnumeric(%) of Ad in viewable area more than 15 seconds.
percentInViewForMoreThan5sec numeric(%) of Ad in viewable area more than 5 seconds.
percentViewabilitynumeric(%) of Ad in viewable area.
phantomBidsnumericHow often PubMatic bid response loses to others.
revenue numericRevenue amount generated by the winning impressions.
ssExpectedRevenuenumericPotential revenue generated by all PubMatic bid responses.
suspiciousImpressions numericNumber of impressions marked as suspicious by IAS
totalBidAmountnumeric

Amount of the total bid responses received by the PubMatic system.

 

Formula:

Total bids responses * Avg. bid eCPM

totalBidsRequestsDspnumericTotal number of bid requests sent by PubMatic to a DSP.
totalImpressionsnumericTotal number of impressions sent by the publisher to the PubMatic system. This value does not include the number of defaulted impressions.
totalLostBidsAdvnumericTotal number of advertiser bid responses that did not win the impressions. 
totalLostBidsAtd numericTotal number of buyer bid responses that did not win the impressions. 
totalLostBidsDspnumeric Total number of DSP bid responses that did not win the impressions.
totalRequests numericTotal Requests.
vctr  numericClick Through Rate
video25PercentCountnumeric25% Video Count 
video50PercentCountnumeric50% Video Count  
video75PercentCountnumeric75% Video Count
videoClicksCount   numericVideo Click Count 
videoCompleteCount numericVideo Complete Count 
videoErrorCountnumericVideo Error Count
videoEventCount numericError Count
videoImpressions numericVideo Distinct Impressions
videoStartCountnumericVideo Start Event Count
vtrnumericVideo Through Rate 
winningImpressionsnumericNumber of times PubMatic responds with a bid response
winRate numericPubMatic Paid Impressions/Total Requests
spendnumericSpend generated by an impression request.

                                                                          

Metrics for Domain Data

Metrics IDData TypeDescription
clicksnumericNumber of paid impressions clicked by users. 
defaultsnumericNumber of impressions not served (defaulted) by an ad network configured in the PubMatic system. 
paidImpressionsnumericNumber of impressions won by the demand partner.
pbImpressionsnumericNumber of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system.
revenuenumericRevenue amount generated by the winning impressions.
spendnumericSpend generated by an impression request.
totalRequestsnumericTotal Requests


Metrics for Rules Data

Metrics IDData TypeDescription
paidImpressionsnumericNumber of impressions won by the demand partner.
revenuenumericRevenue amount generated by the winning impressions.
spendnumericSpend generated by an impression request.
totalRequestsnumericTotal Requests


Get the Bulk-Data Details for a Buyer

This API provides information about how to access bulk-data details for a specific Buyer. 

Sample Request Response

Example of a request and various responses.

Request         

URIhttp://{domainName}//data/buyer/{buyerId}
HTTP MethodGET

Request Headers                 

Header NameTypeValueRequiredDescription
Authorizationstring  Bearer
${access_token}
Yes

The access token generated for authentication should be sent in place of ${access_token}.
 
Example:
 
curl  "http://api.pubmatic.com/v1/analytics/data/buyer/xxxxx?dateUnit=date&dimensions=siteId&filters=&fromDate=2015-01-01T00:00&metrics=spend,paidImpressions,ecpm&pageNumber=1&pageSize=10&sort=-spend&toDate=2015-01-31T23:59" -H "Authorization: Bearer BDxxxx9d"

Request Path Parameters                 

Parameter NameTypeRequiredValidationsDescription
buyerIdintegerYesBuyers can only query their own data.Indicates the Buyer ID.

Request Query Parameters                                                                           

Parameter NameTypeRequiredDescription
fromDatestringYes

Start date of data retrieval.
 
Example:
2013-03-01T00:00
 
PubMatic uses this standard date format even if the dateUnit parameter is different (for example, week).

toDatestringYes

End date of data retrieval.

Example:
2015-03-29T23:59

Info
Note: The conclusion time on the final end date (in this example, 3-29) should be 23:59. A date and time format of 03-30T00:00 would return some data from 3-30.


compFromDatestringNoComparison period start date.
compToDatestringNo

Comparison period end date.

Info
Note: The compFromDate/compToDate period should be within the same timespan as the original fromDate/toDate period.


dimensionsstringNo

Dimensions are attributes available in the PubMatic system.
 
Examples: Country, Platform, Site
 
In case of multiple entries, use a comma-separated format.
 
Example: 
<dim1>,<dim2>

metricsstringYes

Metrics measure specified dimensions.
 
Example:
Buyer 123 has 500 impressions on the U.S. geo and mobile platform.
 
In case of multiple entries, use a comma-separated format.
 
Example:
<metric1>,<metric2>
 

sortstringNo

By default, the sort order is ascending. To change to descending, prefix a minus sign to the requested field.

Example:
To determine which sites provide the most paidImpressions with the fewest zero bids, use
sort=-paidImpressions,totalBidRequests

Info
Note: The sort parameter can be used only with measurements included in the metrics list.


filtersstringNoFor more information on filters, see "Filters."
dateUnitstringNo

The date unit to query in the aggregation. Possible options are:

  • hour
  • date
  • week
  • month
  • quarter
pageNumberintegerNoSpecifies which page number should be returned if there are multiple pages. The default value is 1.
pageSizeintegerNo

Maximum number of rows to include in the response.
 
Example:
"40" returns up to 40 rows

Response

Response Headers             

Response Header NameTypeDescription
Content-Typeapplication/jsonJSON response

Response Body                               

Response Body ParameterTypeDescription
Alertstring

Alert message from server. In most cases, it will be null.
Example:
"alert": null

columnsstring[]

Dimension and metrics columns. Please see the relevant reference section for a complete list of dimensions and metrics and their limitations.
Example:
    "columns": [
        "dealMetaId",
        "spend",
        "paidImpressions",
        "ecpm"
    ],
dealMetaId is a special dimension in the query that will result in additional columns returned in the response.
Example:
If we query on dealMetaId, spend, paidImpressions, and ecpm, we shall have one more column (publisherDealId) added to the response. The rows section will also include the new column value.
"columns": [
    "dealMetaId",
    "publisherDealId",
    "spend",
    "paidImpressions",
    "ecpm"
],

dataFreshnessobject

The date on which the settings of the dataset were last updated.
Example: 
    "dataFreshness": {
         "dataFreshnessHour": "2015-03-12T04",
         "timeZone": "PST"
     },

 displayValue object

The display value of the "ID."
Example:
dealMetaId "13497" has a description (name) of "xxx"
    "displayValue": {
        "dealMetaId": {
            "13497": "xxx",
            "16083": "yyy",

 rows array of array

The main table-like data structure, in which each column in the row corresponds to the column‰ŰŞs definition in the same sequence.
Example:
The records below would be presented in columns ["dealMetaId,","publisherDealId," "revenue," "paidImpressions," "ecpm"]
"rows": [
    [
        "16651",
        "PM-XXX339",
        83365.114596,
        10126407.0,
        8.232448
    ],

Info
Note: When using the dealMetaId dimension, the publisherDealId must be associated.
Example:


   "columns": [
        "dealMetaId",
        "publisherDealId",
        "spend"
    ],
    "rows": [
        [
            "10534",
            "PM-SUU63339",
            0
        ],

 

HTTP Status Codes

Below are the common HTTP status codes sent in REST API response by the PubMatic API platform:

                                                   

StatusErrorTypeDescription
200OKsuccessThe request has been successfully processed; check contents of body.
400Bad Requestclient-side errorThere is some validation failure; check the response body for error details.
401Unauthorized There is an authentication or authorization failure; check the response body for specific details.
403Forbidden You are not subscribed to this feature of the Platform.
404Not Found The server does not have this resource.
500Internal Server ErrorAPI-side errorThere is problem in the PubMatic API Platform. Please contact the PubMatic API support team.
503  Service not available or too many requests.

Available Dimensions

Dimensions are attributes, such as Country, Platform, and Site, available in the PubMatic system.

    

Dimensions for Historic Data

Dimension IDData TypeDescription
averageBidEcpmAdvnumericAverage CPM of the bid responses associated with an advertiser. 
averageBidEcpmAtd numericAverage CPM of the bid responses associated with a buyer.  
bidLossRateAdvnumeric

Number of lost bids as % of total bids for Advertiser.


Formula:

bidLossRateAdv = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidLossRateAtdnumeric

Number of lost bids as % of total bids for ATD.


Formula:

bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidPercentageAdv numeric

Number of non-zero bids received as % of bid received.


Formula:

bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidPercentageAtd

numeric

Number of non-zero bids received as % of bids received.


Formula:

bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidWinRateAdv numeric

An advertiser's paid impressions divided by non-zero bids received, expressed as a percentage.


Formula: 

(Paid Impressions * 100) / Non-Zero Bids Received$$    

bidWinRateAtd numeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.


Formula: 

(Paid Impressions * 100) / Non-Zero Bids Received

clicksnumericNumber of paid impressions clicked by users.
ctrnumeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula :
(Clicks / Paid Impressions) * 100

ecpmnumericAverage CPM (cost per thousand) for the impressions.
lostBidsByAuctionnumericNumber of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks). 
lostBidsByBlockListnumericNumber of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s whitelist.
lostBidsByDWLFnumericNumber of bid responses that did not win the impression because the associated Marketplace deal's whitelist did not include the advertiser associated with the bid. 
lostBidsByFloornumericNumber of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.
nonZeroBidReceivednumericNumber of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually.
paidImpressions numericNumber of impressions won by the demand partner.    
spendnumericSpend generated by an impression request.      
totalLostBidsAdvnumericTotal number of advertiser bid responses that did not win the impressions.

 

Formula :
totalLostBidsAdv = nonZeroBidReceived - paidImpressions
totalLostBidsAtdnumeric

Total number of buyer bid responses that did not win the impressions.
 
Formula :
totalLostBidsAtd = nonZeroBidReceived - paidImpressions

Please note that not all dimensions and metrics are supported together. For more information and verification, login to PubMatic Analytics UI.

Available Metrics     

Metrics for Historical Data


Metric IDData TypeDescription
averageBidEcpmAdvnumericAverage CPM of the bid responses associated with an advertiser. 
averageBidEcpmAtdnumericAverage CPM of the bid responses associated with a buyer.
bidLossRateAdvnumeric

Number of non-zero bids received as % of bid received.

Formula:
bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidLossRateAtd numeric

Number of lost bids as % of total bids for ATD.

Formula:
bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidPercentageAdvnumeric

Number of non-zero bids received as % of bid received.

Formula:
bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidPercentageAtdnumeric

Number of non-zero bids received as % of bids received.

Formula:
bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidWinRateAdvnumeric

Number of non-zero bids received as % of bid received.

Formula:
bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidWinRateAtdnumeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.

 

Formula   

(Paid Impressions * 100) / Non-Zero Bids Received

clicks numericNumber of paid impressions clicked by users.
ctrnumeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula :
CTR = clicks/paidImpressions *100

ecpm numericAverage CPM (cost per thousand) for the impressions.
lostBidsByAuctionnumericNumber of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  
lostBidsByBlockListnumericNumber of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s whitelist.
lostBidsByDWLFnumericlostBidsByDWLF
lostBidsByFloornumericNumber of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.  
nonZeroBidReceivednumericNumber of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually.
paidImpressions numericNumber of impressions won by the demand partner.
spendnumericSpend generated by an impression request.
totalLostBidsAdvnumericTotal number of advertiser bid responses that did not win the impressions. 
totalLostBidsAtdnumericTotal number of buyer bid responses that did not win the impressions. 

Get the Bulk-Data Details for a DSP

This API provides information about how to access bulk-data details for a DSP. 

Sample Request Response

Example of a request and various responses.

Request

         

URIhttp://{domainName}//data/dsp/{dspId}
HTTP MethodGET

Request Headers           

Header NameTypeValueRequiredDescription
Authorizationstring  Bearer
${access_token}
YES 

The access token generated for authentication should be sent in place of ${access_token}.
 
Example:
 
curl  "http://api.pubmatic.com/v1/analytics/data/dsp/xxxxx?dateUnit=date&dimensions=siteId&filters=&fromDate=2015-01-01T00:00&metrics=spend,paidImpressions,ecpm&pageNumber=1&pageSize=10&sort=-spend&toDate=2015-01-31T23:59" -H "Authorization: Bearer BDxxxx9d"


Request Path Parameters               

Parameter NameTypeRequiredValidationsDescription
dspIdIntegerYESDSPs can only query their own data.Indicates the DSP ID.

Request Query Parameters                                                                           

Parameter NameTypeRequiredDescription
fromDateStringYES

Start date of data retrieval.
 
Example:
2013-03-01T00:00
 
PubMatic uses this standard date format even if the dateUnit parameter is different ‰ŰŇ for example, week.

toDatestringYES

End date of data retrieval.

Example:
2015-03-29T23:59

Info
Note: The conclusion time on the final end date (in this example, 3-29) should be 23:59. A date and time format of 03-30T00:00 would return some data from 3-30.


compFromDatestringNOComparison period start date.
compToDatestringNO

Comparison period end date.

Info
Note: The compFromDate/compToDate period should be within the same timespan as the original fromDate/toDate period.


DimensionsstringNO

Dimensions are attributes available in the PubMatic system.
 
Examples:
CountryId PlatformIdSiteId
 
In case of multiple entries, use a comma-separated format.
 
Example: 
<dimention1>,<dimention2>

MetricsstringYES

Metrics measure specified dimensions.
 
Example:
Publisher 123 has 500 impressions on the U.S. geo and mobile platform.
 
In case of multiple entries, use a comma-separated format.
 
Example:
<metric1>,<metric2>
 

SortstringNO

By default, the sort order is ascending. To change to descending, prefix a minus sign  to the requested field.

Example:
To determine which sites provide the most paidImpressions with fewest zero bids, use
sort=-paidImpressions,totalBidRequests

Info
Note: The sort parameter can be used only with measurements included in the metrics list.


FiltersstringNOFor more information on filters, see "Filters"
dateUnitstringNO

The date unit to query in the aggregation. Possible options are:

  • hour
  • date
  • week
  • month
  • quarter
pageNumberintegerNOSpecifies which page number should be returned if there are multiple pages. The default value is 1
pageSizeintegerNO

Maximum number of rows to include in the response.

Example:
"40" returns up to 40 rows

Info
Note: If the customer does not specify page size, then by default 256000 page size value will appear.



Response


Response Headers           

Response Header Name

Type

Description

Content-Type

application/json

JSON response

Response Body                                 

Response Body Parameter

Type

Description

Alert

string

Alert message from server. In most cases, it will be null.

 

Example:

"alert": null

Columns

string[]

Dimension and metrics columns. Please see the relevant reference section for a complete list of dimensions and metrics and their limitations.

 

Example:

    "columns": [

        "dealMetaId",

        "spend",

        "paidImpressions",

        "ecpm"

    ],

 

dealMetaId is a special dimension in query for additional columns to be added on returned response.

Example:

If we query on dealMetaId, spend, paidImpressions, and ecpm, we shall have one more column (publisherdealId) added to the response. The rows section will also include the new column value.

 

"columns": [

    "dealMetaId",

    "publisherDealId",

    "spend",

    "paidImpressions",

    "ecpm"

],

dataFreshness

object

The date on which the settings of the dataset were last updated.

 

Example: 

    "dataFreshness": {

         "dataFreshnessHour": "2015-03-12T04",

         "timeZone": "PST"

     },

 displayValue

 object

The display value of the "ID."

 

Example:

dealMetaId "13497" has a description (name) of "xxx"

 

    "displayValue": {

        "dealMetaId": {

            "13497": "xxx",

            "16083": "yyy",

 Rows

 array of array

The main table-like data structure, in which each column in the row corresponds to the columns definition in the same sequence.

 
Example:
The records below would be presented in columns ["dealMetaId,","publisherDealId," "revenue," "paidImpressions," "ecpm"]
"rows": [

    [

        "16651",

        "PM-XXX339",

        83365.114596,

        10126407.0,

        8.232448

    ],

Note: When using the dealMetaId dimension, the publisherDealId must be associated.

Example:

   "columns": [

        "dealMetaId",

        "publisherDealId",

        "spend"

    ],

    "rows": [

        [

            "10534",

            "PM-SUU63339",

            0

        ],

HTTP Status Codes

Below are the common HTTP status codes sent in REST API response by PubMatic API platform:

                                           

StatusDescriptionTypeDescription
400Bad Requestclient-side errorThere is some validation failure; check the response body for error details.
401Unauthorized There is an authentication or authorization failure; check the response body for specific details.
403Forbidden You are not subscribed to this feature of the Platform.
404Not Found The server does not have this resource.

 

503

  
 

Service Not Available or too many requests.

500Internal Server ErrorAPI-side errorThere is problem in the PubMatic API Platform. Please contact the PubMatic API support team.

Available Dimensions 

Dimensions are attributes, such as Country, Platform, and Site, available in the PubMatic system.


Dimensions for Historic Data

Metric IDData TypeDescription
adFormatIdnumericType of ad associated with the impression (example: video, display).
adSizeId numericSize of ad associated with the impression (example: 200x800).
advertiserCategoryId numericIndicates category of advertiser.
advertiserIdnumericName of the advertiser associated with the ad.
atdIdnumericName of the ATD, agency, or buyer associated with the DSP that won the impression
campaignIdnumericCampaign of the advertiser associated with the ad.
categoryIdnumericCategory of the site from which an impression was requested.
channelIdnumericSales channel through which the impression was won (example: PMP, RTB).
cookiednumericIndicates whether the DSP's cookies were dropped when an impression was requested.
countryId numericCountry from which an impression was requested.
dataCenter numericData Center
datenumericDate (YYYY-MM-DD format) on which an impression was requested. 
dealMetaIdnumericName of the Marketplace deal that won the impression
domainIdnumericAdvertiser Domain is the domain name (Web address) of the advertiser. These domains are identified by the landing page of the impression displayed.
foldPositionIdnumericFold placement associated with the ad tag used when an impression was requested.
hournumericTime (YYYY-MM-DD'T'HH format) at which an impression was received. 
mobDeviceIdFlagnumericIndicates whether the user's device ID is present in the impression requests.
mobDeviceIdTypeIdnumericType of device used by the visitor to generate an impression request.
mobDeviceTypeIdnumericType of device ID used by the visitor to generate an impression request.
mobGeoSourceFlagnumericSource that provided the visitor's geographical location.
mobLatLongFlagnumericIndicates whether the visitor's latitude/longitude details were included in the impression request.
monthnumericMonth (YYYY-MM format) at which an impression was received.
multiBidsnumericTotal number of bid responses for a bid request.
platformIdnumericPlatform through which an impression was requested (example: Web, Mobile Web).
pubIdnumericPublisher associated with the impression requests.
secureStatusnumericIndicates whether the inventory is secure.
siteIdnumericURL of the site from which an impression was requested.
weeknumericWeek (YYYYWww format) at which an impression was received.

Dimensions for Domain Data

Info
Domains displayed in the Domain report are only for whitelisted publishers and channel partners.
                                 
Dimension IDData TypeDescription
applicationIdnumericMobile Application
bundleIdnumericMobile Bundle
dspTldIdnumericMobile Bundle

   

Available Metrics

Metrics for Historical Data

Header 1Header 2Header 3
averageBidEcpmAdv numericAverage CPM of the bid responses associated with an advertiser.      
averageBidEcpmAtdnumericAverage CPM of the bid responses associated with a buyer.        
averageBidEcpmDsp numericAverage CPM of the bid responses received from a DSP.
bidLossRateAdvnumeric

Number of lost bids as % of total bids for Advertiser.

Formula:
bidLossRateAdv = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived  

bidLossRateAtdnumeric

Number of lost bids as % of total bids for ATD.

Formula:
bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidLossRateDspnumeric

Number of lost bids as % of total bids for DSP.

Formula :
bidLossRateDsp = (nonZeroBidResponses - paidImpressions) * 100 / nonZeroBidResponses

bidPercentageAdvnumeric

Number of non-zero bids received as % of bid received.

Formula:
bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidPercentageAtdnumeric

Number of non-zero bids received as % of bids received.

Formula:
bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidPercentageDsp numeric

Number of non-zero bids received as % of bids received.

Formula:
bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidRequestCount numericBid Request Count
bidWinRateAdv numeric

An advertiser's paid impressions divided by non-zero bids received, expressed as a percentage.

 

Formula    

(Paid Impressions * 100) / Non-Zero Bids Received

bidWinRateAtdnumeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.

 

Formula   

(Paid Impressions * 100) / Non-Zero Bids Received

bidWinRateDspnumeric

A DSP's paid impressions divided by non-zero bid responses, expressed as a percentage.

 

Formula

(Paid Impressions * 100) / Non-Zero Bid Responses

clicksnumericNumber of paid impressions clicked by users.
ctrnumeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula :
CTR = clicks/paidImpressions *100

ecpmnumericAverage CPM (cost per thousand) for the impressions.
lostBidsAmountByCBLKnumericLost Bid Amount (Creative Block)  
lostBidsByAuctionnumericNumber of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  
lostBidsByBlockListnumericNumber of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s whitelist.
lostBidsByCBLK numeric Lost Bid Count (Creative Block) 
lostBidsByDWLFnumericNumber of bid responses that did not win the impression because the associated Marketplace deal's whitelist did not include the advertiser associated with the bid.
lostBidsByFloornumericNumber of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.
nonZeroBidReceived  numericNumber of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually. 
nonZeroBidResponsesnumericNumber of bid responses from demand partners that had a non-zero bid value; indicates bid responses intended to participate in the auction.  
paidImpressionsnumericNumber of impressions won by the demand partner.  
queryPerSecond numericQueries Per Second
spend numericSpend generated by an impression request.
timeoutRatenumeric

Rate at which the ad timed out or failed to load.


Formula:

(Number of timeouts / Total number of requests to the DSP) * 100    

totalBidResponses  numericTotal bid responses received by the PubMatic system. 
totalBidsRequestsDspnumericTotal number of bid requests sent by PubMatic to a DSP.    
totalLostBidsAdv numericTotal number of advertiser bid responses that did not win the impressions.
totalLostBidsAtdnumericTotal number of buyer bid responses that did not win the impressions.
totalLostBidsDspnumericTotal number of DSP bid responses that did not win the impressions.  
totalRequestsnumericTotal Requests
vctrnumericClick Through Rate
video25PercentCountnumeric25% Video Count
video50PercentCountnumeric50% Video Count
video75PercentCountnumeric75% Video Count
videoClicksCountnumericVideo Click Count
videoCompleteCountnumericVideo Complete Count  
vtrnumeric Video Through Rate       

Retrieve the Bulk-Data Details for a Topic

Overview

If your data size is very large, the report takes too long to process, or the report generation is timing out, use this API method. This allows you to register the topic (query pattern) and get the data using the topicId generated by the registration process, when the data has been prepared and can manage large data sets more efficiently.

Request         

URIhttp://{domainName}/topic/data/{topicId}/{day}
HTTP MethodGET

Request Headers                     

Header Name

Type

Required

Description

AuthorizationstringYes

Need to send the access token generating for authentication at the place of ${access_token} for App/User.
Format, "Bearer + Space + Token"
Example, "Bearer 9c7xxxe3c"
 

Accept-Encoding: gzipstringYesAllows to compress data before transfer by network, client will receive compressed data in bytes.
Example, 154 megabytes file can be compressed to 17 megabytes

Request Path Parameters                     

Parameter Name

Type

Required

Validations

Description

topicIdintegerYes Publishers can only query their own dataUnique topic ID
daystringYes YYYY-MM-DD

Sample Request

http://api.pubmatic.com/v1/analytics/topic/data/1/2015-11-11


Response         

Response Header Name

Type

Description

Content-Typeapplication/jsonJson response

Response Body                    

Response Body Parameter

Type

Description

alertstring

alert message from server, in most cases it is null.

Example,

"alert": null

columnsstring

dimension and metrics columns (see reference section for the complete list of dimensions and metrics and their limitations)
Example,

    "columns": [

        "siteId",

        "revenue",

        "paidImpressions",

        "ecpm"

    ],

dealMetaId is a special dimension in query for additional columns to be added on returned response.

Example, query on dealMetaId, revenue, paidImpressions, eCPM shall have one more column added for the response. Also, the rows section shall have the new column value.

    "columns": [

        "dealMetaId",

        "publisherDealId",

        "revenue",

        "paidImpressions",

        "ecpm"

    ],

dataFreshnessobject

date on which the settings of the given dataset were last updated.

Example,

    "dataFreshness": {

        "dataFreshnessHour": "2015-03-12T04", 

        "timeZone": "PST"

    },

 displayValue object

 display value of the "ID".

Example,

dealMetaId "13497" is with the description (name) of "xxx"

    "displayValue": {

        "dealMetaId": {

            "13497": "xxx",

            "16083": "yyy",

 rowsarray of array

It is in tabular data structure, each column in the row matches to the columns definition in the same sequence.

Example,

these records below represents the record in columns ["dealMetaId", "publisherDealId", "revenue", "paidImpressions", "ecpm"]

 

    "rows": [

        [

            "16651",

            "PM-XXX339",

            83365.114596,

            10126407.0,

            8.232448

        ],

Sample Response JSON

analytics-example-resp.json



Code Block
languagejs
linenumberstrue
{
    "alert": null,
    "columns": [
        "dealMetaId",
        "revenue",
        "paidImpressions",
        "ecpm"
    ],
    "currency": "USD",
    "dataFreshness": {
        "dataFreshnessHour": "2015-03-12T04",
        "timeZone": "PST"
    },
    "displayValue": {
        "dealMetaId": {
            "13497": "Criteo_Criteo_ALL_ROS_ALL_0708_3.50",
            "16083": "Target_RON_4.00_MediaMath",
            "16091": "Target_Women'sLifestyle_7.00_MediaMath",
            "16651": "Netflix_Entertainment_8.00_DBM",
            "17698": "AT&T_RON_6.50_MEC_AppNexus",
            "3504": "P&G_RON_6.50_AudienceScience",
            "3740": "MaxPoint Interactive_Maxpoint Interactive_ALL_FLNEWS_ALL_6.00",
            "3743": "MaxPoint Interactive_Maxpoint Interactive_ALL_FLTODAY_ALL_6.00",
            "6189": "Invite_Geico_RON_ALL_2.00",
            "8763": "MaxPoint Interactive_Maxpoint Interactive_ALL_RON_ALL_2.00"
        }
    },
    "rows": [
        [
            "16651",
            83365.114596,
            10126407,
            8.232448
        ],
        [
            "8763",
            77102.258791,
            38541211,
            2.000515
        ],
        [
            "3504",
            73710.9945,
            11340153,
            6.5
        ],
        [
            "3740",
            60776.184,
            10129364,
            6
        ],
        [
            "17698",
            54480.049734
            8096994,
            6.728429
        ],
        [
            "13497",
            45204.601177,
            11099020,
            4.072846
        ],
        [
            "6189",
            34021.467339,
            16561790,
            2.054214
        ],
        [
            "16091",
            30320.486,
            4331498,
            7
        ],
        [
            "3743",
            20962.92,
            3493820,
            6
        ],
        [
            "16083",
            10852.705205,
            2364376,
            4.590093
        ]
    ]
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

 

Error Codes

                               

Error Code

Error Description

500Internal Server Error
400Bad Request
401Unauthorized
403Access Denied
404Data Not Found
503Service Not Available or too many requests