Analytics API

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Feb 15, 2018
Version 16Show Document
  • View in full screen mode

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

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

 

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, best for large data setsGet 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 rowsResponse


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. 

                           

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 received.
weekstringWeek (YYY'W'ww format) at which an impression was received.
monthstringMonth (YYYY-MM format) at which an impression was received.
pubIdintegerPublisher associated with the impression requests.
siteIdnumericURL of the site from which an impression was requested.
categoryId   numericCategory of the site from which an impression was requested.   
platformIdnumericPlatform through which an impression was requested (e.g., Web, Mobile Web)
dspIdnumericName of the DSP that won the impression.
atdIdnumericName of the agency, ATD or buyer associated with the DSP that won the impression.
advertiserIdnumericName of the advertiser associated with the ad.
advertiserCategoryIdnumericCategory of the advertiser.
channelIdnumericSales channel through which the impression was won (e.g., RTB, PMP).
dealMetaIdnumericName of the Marketplace Deal that won the impression.
countryIdnumericCountry from which an impression was requested.
adFormatIdnumericType of Ad associated with the impression (e.g., video display)
adSizeIdnumericSize of the ad associated with the impression (e.g., 200 x 800)
adTagIdnumericName of the ad tag used when an impression was requested.
sectionIdnumericSection of the site from which an impression was requested.
adNetworkGroupIdnumericName of the parent Ad Network that monetized the impression.
adNetworkVariantIdnumericName of the parent Ad Network's campaign that monetized the impression.
secureStatusbooleanIndicates whether the inventory is secure.
foldPositionIdnumericFold placement associated with the ad tag used when an impression was requested.
cookiedbooleanIndicates whether or not the DSP's cookies were dropped when an impression was requested.
mobLatLongFlagbooleanIndicates whether the visitor's latitude/longitude details were included in the impression request.
mobDeviceIdFlagbooleanIndicates whether the visitor's Device ID is present in the impression requests.
mobGeoSourceFlagbooleanSource that provided the visitor's geographical location.
mobDeviceTypeIdnumericType of Device used by the visitor to generate an impression request. 
mobDeviceIdTypeIdnumericType of Device ID used by the visitor to generate an impression request. 
campaignIdnumericCampaign 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.
ecpmBucketIdnumericCPM Bucket Number.
creativeIdnumericThe type of ad associated with an impression.
publisherDealIdnumericThe Publisher Deal Id.
audienceGroupIdnumericAudience Group Id.
audiencestringAudience.
dataProviderIdnumericData Provider Id.
mobMakeModelIdnumericMobile Make/Model Id.
mobOsIdnumericMobile Operating System Id.
tldIdnumericTop level domain.
tldEntitynumericTop level domain Entity. Applicable in the case of mobile impressions.
ruleIdnumericWinning Rule ID and Ad Server logs.
ruleMetaIdnumericRule Meta ID for PMPF rule type.
pbReasonnumericReason for Passback.
videoEventIdnumericError. 
partnerIdnumericPartner Id.
profileIdnumericProfile Id.
videoErrorIdnumericVideo Error Id.
videoClientIdnumericVideo Client Id.

Available Metrics                                                                                                                                                     

Metric ID
Data Type
Description
paidImpressions
numeric
Number of impressions won by the demand partner.
totalImpressions
numeric
Total number of impressions sent by the publisher to the PubMatic system. This value does not include the number of defaulted impressions.               
pbImpressionsNet
numeric
Number of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system.                        
pbImpressionsBot
numeric
Number of impressions passed back to the publisher because requests came from a Web bot.    
pbImpressionsNonApproved
numeric
Number 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.  
pubEcpm
numericAverage CPM (cost per thousand) for the impressions.
ecpm
numeric
Average CPM (cost per thousand) for the impressions.
spend
numeric
Spend generated by an impression request.
revenue
numeric
Revenue amount generated by the winning impressions.
defaults
numeric
Number of impressions not served (defaulted) by an ad network configured in the PubMatic system.     
fillRate
numeric
Percentage of times an ad is displayed to the visitor. Higher rates are better.
clicks
numeric
Number of paid impressions clicked by users.   
ctr
numeric
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
totalBidsRequestsDsp
numeric
Total number of bid requests sent by PubMatic to a DSP.
totalBidAmount
numeric

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

 

Formula:

Total bids responses * Avg. bid eCPM        

nonZeroBidResponses
numeric
Number of bid responses from demand partners that had a non-zero bid value; indicates bid responses intended to participate in the auction.            
nonZeroBidReceived
numeric
 Number 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.               
totalLostBidsDsp
numeric
 Total number of DSP bid responses that did not win the impressions. 
totalLostBidsAtd
numeric
Total number of buyer bid responses that did not win the impressions.    
totalLostBidsAdv
numeric
Total number of advertiser bid responses that did not win the impressions. 
bidPercentageDsp
numeric

Number of bids responded as % of bid request sent.

 

Formula:

bidPercentageDsp = ( nonZeroBidResponses / totalBidsRequests ) * 100   

bidWinRateDsp
numeric

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

 

Formula:

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

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

bidWinRateAdv
numeric
Rate of won bids expressed as a percentage of total bids for advertiser.

 

Formula:
bidWinRateAdv = paidImpressions * 100 / nonZeroBidReceived
averageBidEcpmDsp
numeric
Average CPM of the bid responses received from a DSP.    
averageBidEcpmAtd
numeric
Average CPM of the bid responses associated with a buyer.    
averageBidEcpmAdv
numeric
Average CPM of the bid responses associated with an advertiser.  
lostBidsTotalAmount
numeric
Total amount of the bid responses that lost due to a reason other than that described in the Lost Bids Amount (Auction) metric. 
lostBidsByFloor
numeric
Number 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.                              
lostBidsAmountByFloor
numeric
Amount of the bid responses that lost because their value was below the floor set in the Marketplace Rule Manager.                    
lostBidsEcpmByFloor
numeric
eCPM of the bid responses which lost because their value was below the floor set in the Marketplace Rule Manager.
lostBidsByAuction
numeric
Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).    
lostBidsAmountByAuction
numeric
Amount of the bid responses that lost to the winning bid response in the auction. 
lostBidsEcpmByAuction
numeric
eCPM of the bid responses that lost to the winning bid response in the auction.       
lostBidsByBlockList
numeric
Number 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. 
lostBidsAmountByBlockList
numeric
Amount of the bid responses that lost to the winning bid response in the Brand Control blocklist.
lostBidsEcpmByBlockList
numeric
eCPM of the bid responses that lost because the advertiser's associated category/name/domain was added in the Brand Control blocklist. 
lostBidsByDWLF
numeric
Number of bid responses that did not win the impression because the associated Marketplace deal's whitelist did (DWLF) not include the advertiser.
lostBidsAmountByDWLF
numericAmount of the bid responses that lost because the advertiser's associated category/name/domain was not included in the Marketplace deals.
lostBidsEcpmByDWLF
numericeCPM of the bid responses that lost because the advertiser'sassociated category/name/domain was not included in the Marketplace deals' whitelist. 
lostBidsEcpmDspnumericeCPM of the bid responses associated with a DSP that lost the impressions.      
lostBidsEcpmAtd
numeric
eCPM of the bid responses associated with a buyer that lost the impressions.
lostBidsEcpmAdv
numeric
eCPM of the bid responses associated with an advertiser that lost the impressions. 
timeoutRate
numeric

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

 

Formula:

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

bidEcpm
numeric
Bid Ecpm. This metric is used for calculation of averageBidEcpmAtd and averageBidEcpmAdv metrics.
avgCompEcpm                   numericAvg. Competitor eCPM
medianCompEcpm              
numericMedian Competitor eCPM
maxCompEcpm                 
numericMax. Competitor eCPM
minCompEcpm numericMin. Competitor eCPM
sownumericShare of Wallet (SOW)
medianCompSow numericMedian Competitor SOW
avgCompSownumericAvg. Competitor SOW
maxCompSow numericMax. Competitor SOW
minCompSownumericMin. Competitor SOW
sovnumericShare of Voice (SOV)
medianCompSovnumericMedian Competitor SOV
avgCompSov numericAvg. Competitor SOV
maxCompSovnumericMax. Competitor SOV
minCompSov numericMin. Competitor SOV
floornumericFloor
potentialRevenuenumericPotential Revenue
revenueOpportunitynumericRevenue Opportunity 
potentialEcpmnumericMedian eCPM
ecpmOpportunity numericDifference in eCPM 
requestsnumericThe number of requests associated with a campaign. 
indexValue numericIndex Value. 
percentageValuenumericPercentage Value.
totalRequestsnumericTotal Requests
timeoutCountnumericTimeout Count 
winningImpressions numericNumber of times PubMatic responds with a bid response.
ssExpectedRevenue numericPotential revenue generated by all PubMatic bid responses.
phantomBidsnumericHow often PubMatic bid response loses to others.
winRatenumericPubMatic Paid Impressions/Total Requests.
pbImpressions numericNumber of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system. 
measuredImpressionsnumericNumber of impressions measured by IAS 
suspiciousImpressionsnumericNumber of impressions marked as suspicious by IAS
percentViewabilitynumeric(%) of Ad in viewable area. 
percentInViewForMoreThan5secnumeric(%) of Ad in viewable area more than 5 seconds.
percentInViewForMoreThan15secnumeric(%) of Ad in viewable area more than 15 seconds. 
videoEventCount numericError Count
video25PercentCountnumeric25% Video Count  
video50PercentCountnumeric50% Video Count  
video75PercentCountnumeric75% Video Count
videoCompleteCountnumericVideo Complete Count    
videoClicksCountnumericVideo Click Count 
lostBidsAmountByCBLKnumericLost Bid Amount (Creative Block)
lostBidsByCBLK numericLost Bid Count (Creative Block)
timeoutTotalnumericTotal Timeout for requests in milliseconds
timeoutAvg numericAverage Timeout = Total Timeout / No of requests
latencyAvgnumericAverage Latency = Total Latency / No of responses
bidRatenumericBid Rate - Responses/Requests
videoStartCountnumericVideo Start Event Count
videoErrorCountnumericVideo Error Count
videoImpressionsnumericVideo Distinct Impressions
vtrnumericVideo Through Rate 
vctrnumericClick Through Rate
gEcpmnumericGross Ecpm 

 

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.

                                                         

Dimension IDData TypeDescription
adFormatId numericType of ad associated with the impression (example: video, display). 
adSizeIdnumericSize of ad associated with the impression (example: 200x800).
advertiserCategoryIdnumeric
Indicates category of advertiser.
advertiserId numeric
Name of the advertiser associated with the ad. 
categoryIdnumeric
Category of the site from which an impression was requested.
channelIdnumeric
Sales channel through which the impression was won (example: PMP, RTB).
cookied numericIndicates whether the DSP's cookies were dropped when an impression was requested.
countryId numericCountry from which an impression was requested. 
date numericDate (YYYY-MM-DD format) on which an impression was requested.
dealMetaIdnumericName of the Marketplace deal that won the impression.
dspIdnumericName of the DSP that won the impression.
foldPositionIdnumericFold placement associated with the ad tag used when an impression was requested.
hour numericTime (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 ID used by the visitor to generate an impression request.
mobDeviceTypeIdnumericType of device used by the visitor to generate an impression request.
mobGeoSourceFlag numericSource 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.
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.

 

Available Metrics                                                                                                        

Parameter
Data Type
Description
paidImpressions
numeric
Number of impressions won by the demand partner.    
ecpm
numeric
Average CPM (cost per thousand) for the impressions.
spend
numeric
Spend generated by an impression request.      
clicks
numeric
Number of paid impressions clicked by users..
ctr
numeric
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
nonZeroBidReceived
numeric
Number 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.  
totalLostBidsAtd
numeric
 Total number of buyer bid responses that did not win the impressions.
 
Formula:
totalLostBidsAtd = nonZeroBidReceived - paidImpressions
totalLostBidsAdv
numeric
Total number of advertiser bid responses that did not win the impressions.

 

Formula:
totalLostBidsAdv = nonZeroBidReceived - paidImpressions
bidPercentageAtd
numeric

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

 

Formula:

bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidPercentageAdv
numeric

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

bidLossRateAdv
numeric

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

 

Formula:

bidLossRateAdv = (nonZeroBidReceived - 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

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

averageBidEcpmAtd
numeric
Average CPM of the bid responses associated with a buyer.      

Formula:
averageBidEcpmAtd = SUM(bidMaxEcpm) / nonZeroBidReceived
averageBidEcpmAdv
numeric
Average CPM of the bid responses associated with an advertiser.    

Formula:
averageBidEcpmAdv = SUM(bidMaxEcpm) / nonZeroBidReceived
lostBidsByAuction
numeric
 Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).            
lostBidsByBlockList
numeric
Number 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.
lostBidsByDWLF
numeric
Number 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. 
lostBidsByFloor
numeric
Number 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.
demandEcpm
numeric
Average CPM (cost per thousand for the impressions.
totalRequests
numeric
Total Requests.

 

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.

                                                                                     

Dimension IDData TypeDescription
datenumericDate (YYYY-MM-DD format) on which an impression was requested. 
hour numericTime (YYYY-MM-DD'T'HH format) at which an impression was received. 
week
numeric
Week (YYYYWww format) at which an impression was received.
month
numeric
Month (YYYY-MM format) at which an impression was received.
pubId
numeric 
Publisher associated with the impression requests.
siteId
numericURL of the site from which an impression was requested.
categoryIdnumericCategory of the site from which an impression was requested.
platformIdnumericPlatform through which an impression was requested (example: Web, Mobile Web).
dspIdnumericName of the DSP that won the impression.
atdIdnumericName of the ATD, agency, or buyer associated with the DSP that won the impression.
advertiserIdnumericName of the advertiser associated with the ad.
advertiserCategoryIdnumericIndicates category of advertiser.
channelIdnumericSales channel through which the impression was won (example: PMP, RTB).
dealMetaIdnumericName of the Marketplace deal that won the impression.
countryIdnumericCountry from which an impression was requested.
adFormatIdnumericType of ad associated with the impression (example: video, display).
adSizeIdnumericSize of ad associated with the impression (example: 200x800).
secureStatusnumericIndicates whether the inventory is secure.
foldPositionIdnumericFold placement associated with the ad tag used when an impression was requested.
cookiednumericIndicates whether the DSP's cookies were dropped when an impression was requested.
mobLatLongFlagnumericIndicates whether the visitor's latitude/longitude details were included in the impression request.
mobDeviceIdFlagnumericIndicates whether the user's device ID is present in the impression requests.
mobGeoSourceFlagnumericSource that provided the visitor's geographical location.
mobDeviceTypeIdnumericType of device used by the visitor to generate an impression request.
mobDeviceIdTypeIdnumericType of device ID used by the visitor to generate an impression request.
multiBidsnumericTotal number of bid responses for a bid request.
campaignIdnumericCampaign of the advertiser associated with the ad.
domainIdnumericAdvertiser Domain is the domain name (Web address) of the advertiser. These domains are identified by the landing page of the impression displayed. 
dataCenternumericData Center
applicationIdnumericMobile Application
bundleIdnumericMobile Bundle
dspTldIdnumericMobile Bundle
 

Other Details (Available Metrics)

                                                                                                                                                                                                                     

Metric ID
Data Type
Description
paidImpressions
numeric
Number of impressions won by the demand partner.     
demandEcpm 
Average CPM (cost per thousand) for the impressions.
ecpm
numeric
Average CPM (cost per thousand) for the impressions.
spend
numeric
Spend generated by an impression request.
clicks
numeric
Number of paid impressions clicked by users.
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/paidImpressions *100
totalBidsRequestsDsp
numeric
Total number of bid requests sent by PubMatic to a DSP.
nonZeroBidResponses
numeric
Number of bid responses from demand partners that had a non-zero bid value; indicates bid responses intended to participate in the auction.     
nonZeroBidReceived
numeric
Number 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.  
totalLostBidsDsp
numeric
Total number of DSP bid responses that did not win the impressions.        
totalBidResponses
numeric
Total bid responses received by the PubMatic system.  
totalLostBidsAtd
numeric
Total number of buyer bid responses that did not win the impressions.  
totalLostBidsAdv
numeric
Total number of advertiser bid responses that did not win the impressions.
bidPercentageDsp
numeric
Percentage of bid responses compared to bid requests sent.

 

Formula:
bidPercentageDsp =  nonZeroBidResponses * 100 / totalBidsRequests
bidPercentageAtd
numeric
Number of non-zero bids received as % of bids received.
Formula:
bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100
bidPercentageAdv
numeric
Number of non-zero bids received as % of bid received.
Formula:
bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100
bidLossRateDsp
numeric
Number of lost bids as % of total bids for DSP.
Formula:
bidLossRateDsp = (nonZeroBidResponses - paidImpressions) * 100 / nonZeroBidResponses
bidLossRateAtd
numeric
Number of lost bids as % of total bids for ATD.
Formula:
bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived
bidLossRateAdv
numeric
Number of lost bids as % of total bids for Advertiser.
Formula:
bidLossRateAdv = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived  
bidWinRateDsp
numeric

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

 

Formula

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

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

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

averageBidEcpmDsp
numeric
Average CPM of the bid responses received from a DSP.
averageBidEcpmAtd
numeric
Average CPM of the bid responses associated with a buyer.        
averageBidEcpmAdv
numeric
Average CPM of the bid responses associated with an advertiser.      
lostBidsByFloor
numeric
Number 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.
lostBidsByAuction
numeric
Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  
lostBidsByBlockList
numeric
Number 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.
lostBidsByDWLF
numeric
Number 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.
timeoutRate
numeric

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

 

Formula:

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

bidRequestCountnumericBid Request Count
totalRequestsnumericTotal Requests
queryPerSecondnumericQueries Per Second
video25PercentCountnumeric25% Video Count
video50PercentCountnumeric50% Video Count
video75PercentCountnumeric75% Video Count
videoCompleteCountnumericVideo Complete Count
videoClicksCountnumericVideo Click Count   
lostBidsAmountByCBLKnumericLost Bid Amount (Creative Block)  
lostBidsByCBLKnumericLost Bid Count (Creative Block) 
vtrnumericVideo Through Rate
vctrnumericClick 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
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