Analytics API

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

PubMatic UAS 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

Methods               

                           

Method Path
HTTP
Method Type
Description
Link to Definition
/data/publisher/{id}
GET
Historic data query for a Publisher
Get the Bulk-Data Details for a Publisher
/data/buyer/{id}GET
Historic data query for a Buyer
Get the Bulk-Data Details for a Buyer

/data/dsp/{dspId}

GETHistoric data query for a DSPGet the Bulk-Data Details for a DSP

/topic/data/{topicId}/{day}

GETHistoric data query for a Topic Get the Bulk-Data for a Topic

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

         

URI
http://{domainName}//data/publisher/{publisherId}
HTTP Method
GET

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
string 
 Bearer
${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
 
Example:
 

Request Path Parameters                 

Parameter Name
Type
Required
Validations
Description
publisherId
Integer
Yes
Publishers can only query their own data.
Indicates the publisher ID.

Request Query Parameters                                                                     

Parameter Name
Type
Required
Description
fromDate
string
Yes
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.
toDate
string
Yes
End date of data retrieval.
 
Example:
2015-03-29T23:59
 
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.
compFromDate
string
No
Comparison period start date.
compToDate
string
No
Comparison period end date.
Note: The compFromDate/compToDate period should be within the same timespan as the original fromDate/toDate period.
dimensions
string
No
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>
metrics
string
Yes
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>
 
sort
string
No
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
 
Note: The sort parameter can be used only with measurements included in the metrics list.
filters
string
No
For more information on filters, see "Filters."
dateUnit
string
No
The date unit to query in the aggregation. Possible options are:
  • hour
  • date
  • week
  • month
  • quarter
 
pageSize
integer
No
Maximum number of rows to include in the response.
 
Example:
"40" returns up to 40 rows

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",
        "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"
],
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",
        "revenue"
    ],
    "rows": [
        [
            "10534",
            "PM-SUU63339",
            0
        ],

 

Sample Response JSON

      

{
  "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

                                                   

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

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

Ad Attributes                  

Dimension IDData TypeDescription
adFormatIdNumericType of Ad associated with the impression (e.g., video display)
adSizeIdNumericSize of the ad associated with the impression (e.g., 200 x 800)

Buyer                                              

Dimension IDData TypeDescription
adNetworkGroupIdNumericName of the parent Ad Network that monetized the impression.
adNetworkVariantIdNumericName of the parent Ad Network's campaign that monetized the impression.
advertiserIdNumericName of the advertiser associated with the ad.
domainIdNumericDomain name (web addresses) of the advertiser. The domains are identified by the landing page of the impression displayed.
atdIdNumericName of the agency, ATD or buyer associated with the DSP that won the impression.
campaignIdNumericCampaign of the advertiser associated with the ad.
advertiserCategoryIdNumericCategory of the advertiser.
dspIdNumericName of the DSP that won the impression.
dealMetaIdNumericName of the Marketplace Deal that won the impression.

 

General                 

Dimension IDData TypeDescription
channelIdNumericSales channel through which the impression was won (e.g., RTB, PMP).
platformIdNumericPlatform through which an impression was requested (e.g., Web, Mobile Web)

Geography            

Dimension IDData TypeDescription
countryIdNumericCountry from which an impression was requested.

Inventory                                      

Dimension IDData TypeDescription
adTagIdNumericName of the ad tag used when an impression was requested.
cookiedBooleanIndicates whether or not the DSP's cookies were dropped when an impression was requested.
foldPositionIdNumericFold placement associated with the ad tag used when an impression was requested.
secureStatusBooleanIndicates whether the inventory is secure.
siteIdNumericURL of the site from which the impression was requested.
categoryIdNumericCategory of the site from which an impression was selected.

Mobile                              

Dimension IDData TypeDescription
mobDeviceIdFlagBooleanIndicates whether the visitor's Device ID is present in the impression requests.
mobDeviceIdTypeIdNumericType of Device ID used by the visitor to generate an impression request. 
mobDeviceTypeIdNumericType 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.

Time Units                                 

Dimension IDData TypeDescription
dateStringDate (YYYY-MM-DD format) on which an impression was requested.
hourStringTime (YYY-MM-DD'T'HH format) at which an impression was requested.
monthStringMonth (YYYY-MM format) at which an impression was requested.
quarterStringQuarter (YYY'Q'qq format) at which an impression was requested.
weekStringWeek (YYY'W'ww format) at which an impression was requested.

 

Other Details (Available Metrics)

                                                                                                                                                     

Parameter
Data Type
Description
paidImpressions
numeric
Non-defaulted number of impressions.
totalImpressions
numeric
Total number of monetized impressions.
 
Formula:
totalImpressions = paidImpressions + passbackImpressions
pbImpressionsNet
numeric
Non-monetized impressions sent to passback networks.
pbImpressionsBot
numeric
Bot impressions sent to passback networks (the number of impressions filtered by the PubMatic Ad Server due to bots).
pbImpressionsNonApproved
numeric
Whitelisted impressions sent to passback networks. Supply-side whitelisting is done for publisher aggregators and will soon be extended to normal publishers.
ecpm
numeric
Average winning price per thousand paid impressions.
revenue
numeric
Revenue earned by publisher for paid impressions.
defaults
numeric
Number of impressions passed from one ad network to another.
fillRate
numeric
Percentage of times an ad is displayed to the visitor. Higher rates are better.
 
Formula:
fillRate = paidImpressions *100 / totalImpressions
clicks
numeric
Total number of clicks.
ctr
numeric
Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula:
CTR = clicks * 100 / paidImpressions
totalBidsRequestsDsp
numeric
Total number of bid requests sent to DSP.
totalBidAmount
numeric
The sum of all bids.
nonZeroBidResponses
numeric
Total non-zero bid responses from DSP.
nonZeroBidReceived
numeric
Total non-zero bids received (includes multi-bid).
totalLostBidsDsp
numeric
Total DSP bids lost due to reasons such as floor, block list, etc.
 
Formula:
totalLostBidsDsp = nonZeroBidResponses - paidImpressions
totalLostBidsAtd
numeric
Total buyer bids lost due to reasons such as floor, block list, etc.
 
Formula:
totalLostBidsAtd = nonZeroBidReceived - paidImpressions
totalLostBidsAdv
numeric
Total advertiser bids lost due to reasons such as floor, block list, etc.

 

Formula:
totalLostBidsAdv = nonZeroBidReceived - paidImpressions
lostBidsEcpmDsp
numeric
eCPM of lost bids for DSP.

 

Formula:
lostBidsEcpmDsp = lostBidsTotalAmount * 1000 / totalLostBidsDsp
lostBidsEcpmAtd
numeric
eCPM of lost bids for buyer.

 

Formula:
lostBidsEcpmAtd = lostBidsTotalAmount * 1000 / totalLostBidsAtd
lostBidsEcpmAdv
numeric
eCPM of lost bids for advertiser.

 

Formula:
lostBidsEcpmAdv = lostBidsTotalAmount * 1000 / totalLostBidsAdv
bidPercentageDsp
numeric
Percentage of bid responses compared to bid requests sent.

 

Formula:
bidPercentageDsp =  nonZeroBidResponses * 100 / totalBidsRequests
bidWinRateDsp
numeric
Rate of won bids expressed as a percentage of total bids for DSP.

 

Formula:
bidWinRateDsp = paidImpressions * 100 / nonZeroBidResponses
bidWinRateAtd
numeric
Rate of won bids expressed as a percentage of total bids for buyer.

Formula:
bidWinRateAtd = paidImpressions * 100 / nonZeroBidReceived
bidWinRateAdv
numeric
Rate of won bids expressed as a percentage of total bids for advertiser.

 

Formula:
bidWinRateAdv = paidImpressions * 100 / nonZeroBidReceived
averageBidEcpmDsp
numeric
Average bid ecpm for DSP.

 

Formula:
averageBidEcpmDsp = SUM(bidMaxEcpm) / nonZeroBidResponses
averageBidEcpmAtd
numeric
Average bid ecpm for buyer.

Formula:
averageBidEcpmAtd = SUM(bidMaxEcpm) / nonZeroBidReceived
averageBidEcpmAdv
numeric
Average bid ecpm for advertiser.

Formula:
averageBidEcpmAdv = SUM(bidMaxEcpm) / nonZeroBidReceived
lostBidsTotalAmount
numeric
Revenue of all lost bids.
Formula:
lostBidsTotalAmount = totalBidAmount - revenue
lostBidsByFloor
numeric
Number of bids lost due to floor filter.
lostBidsAmountByFloor
numeric
Revenue of lost bids due to floor filter.
lostBidsEcpmByFloor
numeric
eCPM of lost bids due to floor filter.
lostBidsByAuction
numeric
Number of bids lost in auction.
lostBidsAmountByAuction
numeric
Revenue of lost bids due in auction.
lostBidsByBlockList
numeric
Number of bids lost due to blocklist.
lostBidsAmountByBlockList
numeric
Revenue of lost bids due to blocklist.
lostBidsEcpmByBlockList
numeric
eCPM of lost bids due to blocklist.
lostBidsByDWLF
numeric
Number of bids lost due to Deal Whitelisted Flag (DWLF).
lostBidsAmountByDWLF
numericRevenue of lost bids due to DWLF.
lostBidsEcpmByDWLF
numericeCPM of lost bids due to DWLF.

 

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         

URI
http://{domainName}//data/buyer/{buyerId}
HTTP Method
GET

Request Headers                 

Header Name
Type
Value
Required
Description
Authorization
string 
 Bearer
${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
 
Example:
 

Request Path Parameters                 

Parameter Name
Type
Required
Validations
Description
buyerId
integer
Yes
Buyers can only query their own data.
Indicates the Buyer ID.

Request Query Parameters                                                                           

Parameter Name
Type
Required
Description
fromDate
string
Yes
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).
toDate
string
Yes
End date of data retrieval.
 
Example:
2015-03-29T23:59
 
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.
compFromDate
string
No
Comparison period start date.
compToDate
string
No
Comparison period end date.
Note: The compFromDate/compToDate period should be within the same timespan as the original fromDate/toDate period.
dimensions
string
No
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>
metrics
string
Yes
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>
 
sort
string
No
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
 
Note: The sort parameter can be used only with measurements included in the metrics list.
filters
string
No
For more information on filters, see "Filters."
dateUnit
string
No
The date unit to query in the aggregation. Possible options are:
  • hour
  • date
  • week
  • month
  • quarter
pageNumber
integer
No
Specifies which page number should be returned if there are multiple pages. The default value is 1.
pageSize
integer
No
Maximum number of rows to include in the response.
 
Example:
"40" returns up to 40 rows

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 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"
],
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 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
    ],
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:

                                                   

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

Available Dimensions for Historic Data

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

                                                         

AdAttributes
Buyer
General
Geography
Inventory
TimeUnits
Mobile
AdFormatId
pubId
platformId
countryId
siteId
date
mobLatLongFlag
adSizeId
dspId
channelId
 
categoryId
hour
mobDeviceIdFlag
 
advertiserId
 
 
secureStatus
 
mobGeoSourceFlag
 
advertiserCategoryId
 
 
foldPositionId
 
mobDeviceTypeId
 
dealMetaId
 
 
cookied
 
mobDeviceIdTypeId

Other Details (Available Metrics)

                                                                                                             

Parameter
Data Type
Description
StandardMetrics
paidImpressions
numeric
Non-defaulted number of impressions.
Ecpm
numeric
Average winning price per thousand paid impressions.
Spend
numeric
Spend earned by Buyer for paid impressions.
BidMetrics
Clicks
numeric
Total number of clicks.
Clickthrough rate (CTR)
numeric
Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula:
CTR = clicks * 100 / paidImpressions
nonZeroBidReceived
numeric
Total non-zero bids received (includes multi-bid).
totalLostBidsAtd
numeric
Total Buyer bids lost due to reasons such as floor and block list.
 
Formula:
totalLostBidsAtd = nonZeroBidReceived - paidImpressions
totalLostBidsAdv
numeric
Total Advertiser bids lost due to reasons such as floor and block list.

 

Formula:
totalLostBidsAdv = nonZeroBidReceived - paidImpressions
bidPercentageAtd
numeric
Number of non-zero bids received as % of bids received from Buyers.
 
Formula:
bidPercentageAtd =  nonZeroBidReceived * 100 / totalBidsRequestsAtd
bidPercentageAdv
numeric
Number of non-zero bids received as % of bid received from Advertisers.
 
Formula:
bidPercentageAdv =  nonZeroBidReceived * 100 / totalBidsRequestsAdv
bidLossRateAtd
numeric
Number of lost bids as a percentage of total bids for the ATD.
 
Formula:
bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceive
 
bidLossRateAdv
numeric
Number of lost bids as a percentage of total bids for the Advertiser.
 
Formula:
bidLossRateAdv = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived
bidWinRateAtd
numeric
Rate of won bids expressed as a percentage of total bids for the Buyer.

Formula:
bidWinRateAtd = paidImpressions * 100 / nonZeroBidReceived
bidWinRateAdv
numeric
Rate of won bids expressed as a percentage of total bids for the Advertiser.

 

Formula:
bidWinRateAdv = paidImpressions * 100 / nonZeroBidReceived
averageBidEcpmAtd
numeric
Average bid eCPM for the Buyer.

Formula:
averageBidEcpmAtd = SUM(bidMaxEcpm) / nonZeroBidReceived
averageBidEcpmAdv
numeric
Average bid eCPM for the Advertiser.

Formula:
averageBidEcpmAdv = SUM(bidMaxEcpm) / nonZeroBidReceived
lostBidsByAuction
numeric
Number of bids lost in auction.
lostBidsByBlockList
numeric
Number of bids lost due to the block-list.
lostBidsByDWLF
numeric
Number of bids lost due to the Deal Whitelisted Flag (DWLF).

 

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

         

URI
http://{domainName}//data/dsp/{dspId}
HTTP Method
GET

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
string 
 Bearer
${access_token}
YES 
The access token generated for authentication should be sent in place of ${access_token}.
 
Example:
 

Request Path Parameters

               

Parameter Name
Type
Required
Validations
Description
dspId
Integer
YES
DSPs can only query their own data.
Indicates the DSP ID.

Request Query Parameters                                                                           

Parameter Name
Type
Required
Description
fromDate
String
YES
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.
toDate
string
YES
End date of data retrieval.
 
Example:
2015-03-29T23:59
 
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.
compFromDate
string
NO
Comparison period start date.
compToDate
string
NO
Comparison period end date.
Note: The compFromDate/compToDate period should be within the same timespan as the original fromDate/toDate period.
Dimensions
string
NO
Dimensions are attributes available in the PubMatic system.
 
Examples:
CountryId, PlatformId, SiteId
 
In case of multiple entries, use a comma-separated format.
 
Example: 
<dimention1>,<dimention2>
Metrics
string
YES
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>
 
Sort
string
NO
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
 
Note: The sort parameter can be used only with measurements included in the metrics list.
Filters
string
NO
For more information on filters, see "Filters"
dateUnit
string
NO
The date unit to query in the aggregation. Possible options are:
  • hour
  • date
  • week
  • month
  • quarter
pageNumber
integer
NO
Specifies which page number should be returned if there are multiple pages. The default value is 1
pageSize
integer
NO
Maximum number of rows to include in the response.
 
Example:
"40" returns up to 40 rows
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:

                                           

Status
Description
Type
Description
400
Bad Request
client-side error
There is some validation failure; check the response body for error details.
401
Unauthorized
 
There is an authentication or authorization failure; check the response body for specific details.
403
Forbidden
 
You are not subscribed to this feature of the Platform.
404
Not Found
 
The server does not have this resource.
 
503
 
 
 
Service Not Available or too many requests.
500
Internal Server Error
API-side error
There is problem in the PubMatic API Platform. Please contact the PubMatic API support team.

Available Dimensions for Historic Data

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

                                                                                     

adAttributes
buyer
general
geography
Inventory
timeUnits
mobile
adFormatId
dspId
platformId
countryId
siteId
Date
mobLatLongFlag
adSizeId
atdId
channelId
 
categoryId
Hour
mobDeviceIdFlag
 
advertiserId
 
 
siteGroupId
 
mobGeoSourceFlag
 
advertiserCategoryId
 
 
adTagId
 
mobDeviceTypeId
 
campaignId
 
 
sectionId
 
mobDeviceIdTypeId
 
dealMetaId
 
 
secureStatus
 
 
 
adNetworkGroupId
 
 
foldPositionId
 
 
 
adNetworkVariantId
 
 
cookied
 
 
 
 
 
 
multiBids
 
 
 

Other Details (Available Metrics)

                                                                                                                                                                                                                     

Parameter
Data Type
Description
paidImpressions
numeric
Non-defaulted number of impressions.
totalImpressions
numeric
Total number of monetized impressions.
 
Formula:
totalImpressions = paidImpressions + passbackImpressions
pbImpressionsNet
numeric
Non-monetized impressions sent to passback networks.
pbImpressionsBot
numeric
Bot impressions sent to passback networks (the number of impressions filtered by the PubMatic Ad Server due to bots).
pbImpressionsNonApproved
numeric
Whitelisted impressions sent to passback networks. Supply-side whitelisting is done for DSP aggregators and will soon be extended to normal DSPs.
ecpm
numeric
Average winning price per thousand paid impressions.
spend
numeric
Spend earned by DSP for paid impressions.
defaults
numeric
Number of impressions passed from one ad network to another.
fillRate
numeric
Percentage of times an ad is displayed to the visitor. Higher rates are better.
 
Formula:
fillRate = paidImpressions *100 / totalImpressions
clicks
numeric
Total number of clicks.
Clickthrough rate (CTR)
numeric
Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.
 
Formula:
CTR = clicks * 100 / paidImpressions
totalBidsRequestsDsp
numeric
Total number of bid requests sent to DSP.
totalBidAmount
numeric
The sum of all bids.
nonZeroBidResponses
numeric
Total non-zero bid responses from DSP.
nonZeroBidReceived
numeric
Total non-zero bids received (includes multi-bid).
totalLostBidsDsp
numeric
Total DSP bids lost due to reasons such as floor, block list, etc.
 
Formula:
totalLostBidsDsp = nonZeroBidResponses ‰ŰŇ paidImpressions
totalLostBidsAtd
numeric
Total buyer bids lost due to reasons such as floor, block list, etc.
 
Formula:
totalLostBidsAtd = nonZeroBidReceived ‰ŰŇ paidImpressions
totalLostBidsAdv
numeric
Total advertiser bids lost due to reasons such as floor, block list, etc.

 

Formula:
totalLostBidsAdv = nonZeroBidReceived ‰ŰŇ paidImpressions
lostBidsEcpmDsp
numeric
eCPM of lost bids for DSP.

 

Formula:
lostBidsEcpmDsp = lostBidsTotalAmount * 1000 / totalLostBidsDsp
lostBidsEcpmAtd
numeric
eCPM of lost bids for buyer.

 

Formula:
lostBidsEcpmAtd = lostBidsTotalAmount * 1000 / totalLostBidsAtd
lostBidsEcpmAdv
numeric
eCPM of lost bids for advertiser.

 

Formula:
lostBidsEcpmAdv = lostBidsTotalAmount * 1000 / totalLostBidsAdv
bidPercentageDsp
numeric
Percentage of bid responses compared to bid requests sent.

 

Formula:
bidPercentageDsp =  nonZeroBidResponses * 100 / totalBidsRequests
bidWinRateDsp
numeric
Rate of won bids expressed as a percentage of total bids for DSP.

 

Formula:
bidWinRateDsp = paidImpressions * 100 / nonZeroBidResponses
bidWinRateAtd
numeric
Rate of won bids expressed as a percentage of total bids for buyer.

Formula:
bidWinRateAtd = paidImpressions * 100 / nonZeroBidReceived
bidWinRateAdv
numeric
Rate of won bids expressed as a percentage of total bids for advertiser.

 

Formula:
bidWinRateAdv = paidImpressions * 100 / nonZeroBidReceived
averageBidEcpmDsp
numeric
Average bid ecpm for DSP.

 

Formula:
averageBidEcpmDsp = SUM(bidMaxEcpm) / nonZeroBidResponses
averageBidEcpmAtd
numeric
Average bid ecpm for buyer.

Formula:
averageBidEcpmAtd = SUM(bidMaxEcpm) / nonZeroBidReceived
averageBidEcpmAdv
numeric
Average bid ecpm for advertiser.

Formula:
averageBidEcpmAdv = SUM(bidMaxEcpm) / nonZeroBidReceived
lostBidsTotalAmount
numeric

Spend of all lost bids.

Formula:
lostBidsTotalAmount = totalBidAmount ‰ŰŇ spend

lostBidsByFloor
numeric
Number of bids lost due to floor filter.
lostBidsAmountByFloor
numeric
Spend of lost bids due to floor filter.
lostBidsEcpmByFloor
numeric
eCPM of lost bids due to floor filter.
lostBidsByAuction
numeric
Number of bids lost in auction.
lostBidsAmountByAuction
numeric
Spend of lost bids due in auction.
lostBidsEcpmByAuction
numeric
Spend of lost bids due in auction.
lostBidsByBlockList
numeric
Number of bids lost due to blocklist.
lostBidsAmountByBlockList
numeric
Spend of lost bids due to blocklist.
lostBidsEcpmByBlockList
numeric
eCPM of lost bids due to blocklist.
lostBidsByDWLF
numeric
Number of bids lost due to Deal Whitelisted Flag (DWLF).
lostBidsAmountByDWLF
numeric
Spend of lost bids due to DWLF.
lostBidsEcpmByDWLF
numeric
eCPM of lost bids due to DWLF.

Retrieve the Bulk-Data Details for a Topic

Overview

This API 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 (same availability like other historic data API).

Request         

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

Request Headers                     

Header Name
Type
Required
Description
Authorization
string
Yes
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

 


{
    "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

Attachments

    Outcomes