This short guide will help you build the API call, and explain the basics for collecting reporting data from HB Analytics.
The Pull API in HB Analytics enables users to export their data to external systems or for various other purposes.
Preparations:
We recommend going through these steps before creating API requests:
1. You can either use an existing Admin User in the system or you can create a new Admin User to be utilised as a dedicated API user. We recommend creating a new Admin User. This means that you can avoid having to make changes to your API requests, if you would need to delete the user whose account has been used in the requests.
2. Create the new Admin user in Administrators, if you decide to follow our recommendation to use a separate Admin user for the API requests.
3. Make sure you have the right URL. All clients have their own unique Domain URL. Please ask your Technical Account Manager for the correct domain to call.
The script example:
This example showcases the functions with some explanations. Please see further sections of this article for more details:
// WARNING: including all available dimensions like below will most likely *not* work with live-data
// with millions of ad-requests (an error will be returned).
const runReport = async (startTs, endTs) => {
const HOST = 'YOUR_URL_ASK_YOUR_TECHNICAL_ACCOUNT_MANAGER'; // Change to real host!
const CREDENTIALS = {
email: 'user@example.com', // Change to real user-name (email)
password: 'mypassword', // Change to real user's password
};
let token; // Our auth-token, to be obtained below
// Fetch data from API, response will be an object with the result in .result
const fetchData = (path, body) => fetch(`${HOST}${path}`, {
headers: {
"accept": "*/*",
"content-type": "application/json",
"authorization": token,
},
body: JSON.stringify(body),
method: 'POST',
mode: 'cors',
}).then(r => r.json()).then((d) => d.result);
// Step 1: Fetch an authentication token
({ token } = await fetchData('/users/login', CREDENTIALS));
const groupBy = [
'date', // Timeperiod
'publisherId', // Publisher
'siteId', // Site
'bidder', // Bidder
'sourceId', // Source
'placementId', // Placement
'bidRange', // Bid range
'size', // Creative Size
'mediaType', // Media Type
'__sys_Prebid Configuration', // Prebid Configuration
'__sys_Browser name', // Browser name
'__sys_Browser version', // Browser version
'__sys_Hostname', // Hostname
'__sys_Operating system', // Operating system
'__sys_Platform', // Platform
'__sys_URL', // URL
];
const sums = [
'revenue', // Revenue
'pageViews', // Auctions (Notice: *auctions* and not "page-views")
'adserverIn', // Ad unit requests
'renderSuccess', // Impressions
'bidWon', // Winning bids
'bids', // Bid requests
'bidVolume', // Total bid revenue
'unloadBeforeResponse', // Cancelled bids
'timedOut', // Timed out bids
'noBid', // No bid responses
'bidResponse', // Bid responses
'renderFailed', // Failed renderings
'responseMs', // Total response milliseconds, Avg. response ms = responseMs / (bidResponse + noBid)
'renderMs', // Total render milliseconds, Avg. render ms = renderMs / bidWon
];
// Step 2: Run the report. The result will be an array with metrics and dimensions.
// For each dimension there will be two fields:
// - [dim-name] - Relevant Yield internal id
// - [dim-name]_label - Human friendly name
// Exception: for date there will not be any date_label. Instead it will just be date which is the milliseconds
// since 1970-01-01 (UTC), similar to: new Date().getTime()
return fetchData('/reports', {
customCommand: 'reportHb',
reportFormat: 'array', // Result will be a JSON-array (default is a nested object)
startTs, // Start millisecond for report
endTs, // End millisecond for report, 0 means "until now"
groupBy, // Dimensions
sums, // Metrics
timeRangeMs: 600 * 1000, // Group data per 10 minutes (600 seconds)
splitByAuctionRunner: false, // Set to true to split bidders by calls done Client-/Server-side on Web
});
};
// Run report between midnight (UTC) and now + log result
const runReportForToday = async () => {
const reportArray = await runReport(new Date().setUTCHours(0,0,0,0), new Date().getTime());
console.info('The result:', reportArray);
};
1. Setting up the Credentials and the Domain you need to access:
const runReport = async (startTs, endTs) => {
const HOST = 'YOUR_URL_ASK_YOUR_TECHNICAL_ACCOUNT_MANAGER'; // Change to real host!
const CREDENTIALS = {
email: 'user@example.com', // Change to real user-name (email)
password: 'mypassword', // Change to real user's password
};
2. Options on how to group your output:
const groupBy = [
'date', // Timeperiod
'publisherId', // Publisher
'siteId', // Site
'bidder', // Bidder
'sourceId', // Source
'placementId', // Placement
'bidRange', // Bid range
'size', // Creative Size
'mediaType', // Media Type
'__sys_Prebid Configuration', // Prebid Configuration
'__sys_Browser name', // Browser name
'__sys_Browser version', // Browser version
'__sys_Hostname', // Hostname
'__sys_Operating system', // Operating system
'__sys_Platform', // Platform
'__sys_URL', // URL
];
3. Selecting the Metrics you would like to report on:
const sums = [
'revenue', // Revenue
'pageViews', // Auctions (Notice: *auctions* and not "page-views")
'adserverIn', // Ad unit requests
'renderSuccess', // Impressions
'bidWon', // Winning bids
'bids', // Bid requests
'bidVolume', // Total bid revenue
'unloadBeforeResponse', // Cancelled bids
'timedOut', // Timed out bids
'noBid', // No bid responses
'isApproximation', // Is approximation
'bidResponse', // Bid responses
'renderFailed', // Failed renderings
'uniqueBidRevenue', // Unique HB bid revenue
'incrementalBidRevenue', // Incremental HB bid revenue
'lostToAdserverRevenue', // Lost revenue to adserver
'isAdserverBid', // Adserver bids
'responseMs', // Total response milliseconds, Avg. response ms = responseMs / (bidResponse + noBid)
'renderMs', // Total render milliseconds, Avg. render ms = renderMs / bidWon
];
4. Running the report:
// Step 2: Run the report. The result will be an array with metrics and dimensions.
// For each dimension there will be two fields:
// - [dim-name] - Relevant Yield internal id
// - [dim-name]_label - Human friendly name
// Exception: for date there will not be any date_label. Instead it will just be date which is the milliseconds
// since 1970-01-01 (UTC), similar to: new Date().getTime()
return fetchData('/reports', {
customCommand: 'reportHb',
reportFormat: 'array', // Result will be a JSON-array (default is a nested object)
startTs, // Start millisecond for report
endTs, // End millisecond for report, 0 means "until now"
groupBy, // Dimensions
sums, // Metrics
timeRangeMs: 600 * 1000, // Group data per 10 minutes (600 seconds)
splitByAuctionRunner: false, // Set to true to split bidders by calls done Client-/Server-side on Web
});
};
// Run report between midnight (UTC) and now + log result
const runReportForToday = async () => {
const reportArray = await runReport(new Date().setUTCHours(0,0,0,0), new Date().getTime());
console.info('The result:', reportArray);