Page tree



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

  
  

Description

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

Request

Sample Request Response         

URIhttp://{domainName}/data/phoenix/{entityId}
HTTP MethodGET

Request Headers

                 

Header NameTypeValueRequiredDescription
PubTokenstring
YesPublisher Token to authenticate and authorize the user calling the Unified Ad Server API.


Send the access token generated for authentication at the place of ${access_token} in the request. For more information about access tokens, refer to Getting Started with PubMatic APIs.
Authorizationstring  Bearer
${access_token}
Yes

The access token generated for authentication should be sent in place of ${access_token}.
 

Request Path Parameters                 

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

Request Query Parameters                                                                     

Parameter NameTypeRequiredDescription
tzstringNo

Timezone-based data. This feature is dependent on the timezone aggregation feature. The data for specific timezone is only provided if it is configured in the system. Supported timezones include:

  • PST
  • JST
  • AEST
  • GMT
  • ACST
  • AWST
currencystringNo

The type of currency to be used for this publisher. By default, user account's currency is used.

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

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
 
Note: The sort parameter can be used only with measurements included in the metrics list.

filtersarray [string]NoFor more information on filters, see "Filters"
dateUnitstringNo

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

  • hour
  • date
  • week
  • month
pageSizeintegerNo

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

Sample Request

curl 'https://analytics.pubmatic.com/api/v1/analytics/data/phoenix/156173?dateUnit=hour&dimensions=hour&filters=&fromDate=2017-01-02T00:00&metrics=requests&pageNumber=&pageSize=&sort=hour&toDate=2017-01-31T23:59'

Response

Sample Response JSON


{
 "columns": [ "date", "adUnitId", "accountId", "clicks", "clientSideImpressions" ],
 "rows": [
["2017-01-25",123,456,32456,13084],["2017-01-26",456,123,45436,13084]],
"displayValue":{
"date":{"2017-01-25":"2017-01-25","2017-01-26":"2017-01-26"},
"adUnitId":{"123":"abc","456":"def"},
"accountId":{"123":"abc","456":"def"}
},
 "currency": "USD",
 "alert": null 
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

HTTP Status Codes

                                                   

StatusDescription
400Invalid input parameter
400PubToken is required
401Invalid token
403Access Denied
404Data not found



Supported Dimensions for UAS Data

Dimension IDData TypeDescription
accountId numericThe account associated with the Order/line item. 
adUnitId numericAn Ad Unit is associated with the Ad tag targeted by a line item.   
advertiserIdnumericName of the advertiser associated with the ad.
channelIdnumericSales channel through which the impression was won (example: PMP, RTB). 
countryIdnumericCountry from which an impression was requested. (Refer to How Countries are Reported in Analytics Reports for more information.)
creativeIdnumericThe type of ad associated with an impression
creativeSizeIdnumericThe size of ad associated with an impression.  
date stringDate (YYYY-MM-DD format) on which an impression was requested.      
dealMetaIdnumericName of the Marketplace deal that won the impression.   
hourstringTime (YYYY-MM-DD'T'HH format) at which an impression was received.
lineItemIdnumericLine items are campaigns that have different targeting. 
lineItemPriorityIdnumericThe priority for a line item.
lineItemTypenumericThe priority settings for a line item.     
makeIdnumericDevice make targeted by a line item.
modelIdnumericDevice model targeted by a line item.    
month stringMonth (YYYY-MM format) at which an impression was received.     
orderIdnumericAn Order is a group of related Line Items.    
regionIdnumericThe geographic area targeted by a line item.
siteIdnumericURL of the site from which an impression was requested. 
targetIdnumericThe combination of targeting parameters applied for particular line item.      
week stringWeek (YYYYWww format) at which an impression was received. 

Supported Metrics for UAS Data

Metrics IDData TypeDescription
clicksnumericNumber of paid impressions clicked by users. 
clientSideImpressionsnumericImpressions registered on the client side.     
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

ecpm numericAverage CPM (cost per thousand) for the impressions.
fillRatenumericPercentage of times an ad is displayed to the visitor. Higher rates are better.
paidImpressionsnumericNumber of impressions won by the demand partner.
requestsnumericThe number of requests associated with a campaign. 
revenuenumericRevenue amount generated by the winning impressions.