Analytics API for Unified Ad Server (UAS) Data

Document created by catherine.racette on Mar 30, 2017Last modified by catherine.racette on Mar 1, 2018
Version 4Show 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. 

Description

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

Request

Sample Request Response         

URI
http://{domainName}/data/phoenix/{entityId}
HTTP Method
GET

Request Headers

                 

Header Name
Type
Value
Required
Description
PubToken
string
Yes
Publisher 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.
Authorization
string 
 Bearer
${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
 

Request Path Parameters                 

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

Request Query Parameters                                                                     

Parameter Name
Type
Required
Description
tz
string
No

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
currency
string
No

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

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.
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
array [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
pageSize
integer
No
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

                                                   

Status
Description
400
Invalid input parameter
400
PubToken is required
401
Invalid token
403
Access Denied
404
Data 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.
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.

Attachments

    Outcomes