Analytics API for Unified Ad Server (UAS) Data

Document created by catherine.racette on Mar 30, 2017Last modified by catherine.racette on Jun 5, 2017
Version 2Show Document
  • View in full screen mode

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

                                                                                                                                                     

Dimension ID
Data Type
Description
accountId
numeric
Id of the Account that serves or delivers the impression.
adUnitId
numeric
Id of the Ad Unit.
advertiserId
numeric
Id of the Advertiser in the PubMatic system.
countryId
numeric
Country in which the impression is served.
creativeId
numeric
Id of the creative displayed on the impression.
creativeSizeId
numeric
Id of the size of the served creative.
lineItemId
numeric
Id of the line item for the primary unit of execution for an order, representing a specific inventory purchase with attributes that specify pricing, goal, priority and targeting requirements.
lineItemPriorityId
numeric
Priority If of a Line Item.
lineItemType
numeric
Type of Line Item.
makeId
numeric
Id of the Maker of the mobile phone.
targetId
numeric
Id of the targeting criteria for a Line Item.
date/hour/week/monthstring

Indicates the date/hour/week/month/ of impression

The value would be in Date ISO 8601 format depicted in the table below.

FieldFormatExample
dateYYYY-MM-DD2014-07-08
hourYYYY-MM-DD'T'HH2014-07-08T22
weekYYYY'W'ww2014W03
monthYYYY-MM2014-07

Only one of these dimensions can be present in single query and the fromDate and toDate should be in the same format.

 

If none of these dimensions are present then the date format would be assumed as of date and the data would be aggregated by date.

 

 

Supported Metrics

                                                                                                                                                     

Parameter
Data Type
Description
paidImpressions
numeric
Non-defaulted number of impressions.
ecpm
numeric
Average winning price per thousand paid impressions.
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
clientSideImpressions
numeric
Impressions registered on client side.
requests
numeric
Number of requests associated with a campaign.
revenue
numeric
Revenue earned by publisher for paid impressions.

Attachments

    Outcomes