Reporting API Guide

Overview

Welcome to the Freestar Reporting API Guide, where comprehensive documentation guides you through leveraging Freestar's API to systematically pull reporting data.

Guide

• Generating API Tokens
• Running Reports
  • Running Queries
  • Formatting Your Query
    • Filters
    • Dimensions and Measures
    • Time Dimensions
    • Ordering
    • Pagination
    • Total Count
  • Retrieving meta information

Generating API Tokens

There are two ways you can generate API tokens for authentication:

1. Generate an API token by logging into publisher.freestar.io and navigate to Site Configuration > API Tokens
2. Request a token via an API Request using the instructions provided below

Example using curl:

  curl --location --request POST 'https://api.pub.network/api/v1/authorization/public/pubauth' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "your email",
"password": "your password"
}'

Endpoint: POST  https://api.pub.network/api/v1/authorization/public/pubauth

Headers: Content-Type: application/json

Request Body:

{
  "email": "your email",
  "password": "your password"
}

Response:

{
  "access_token": "0NiUW1kNUphN2JWRm9DM1RHUjV6V3kzQzRodjUyZmNNM...",
  "expires_in": 2591997,
  "scope": "openid profile",
  "token_type": "Bearer"
}

Running Reports

• Running Queries
• Formatting Your Query
• Retrieving meta information

Running Queries

The API endpoint is the following: https://analytics.pub.network/cubejs-api/v1/load

This API endpoint supports both POST requests with a JSON body containing the query, and GET requests with an encoded URL parameter containing the query.

2Ensure you include the following header using the token generated above:
Authorization: Bearer {token}

Example Request

GET (using curl):

curl -X GET https://analytics.pub.network/cubejs-api/v1/load?query=%7B%20%22total%22%3A%20true%2C%20%22measures%22%3A%20%5B%20%22NdrWebCombinedWithNetworks.net_revenue%22%2C%20%22NdrWebCombinedWithNetworks.impressions%22%20%5D%2C%20%22dimensions%22%3A%20%5B%20%22NdrWebCombinedWithNetworks.record_date%22%2C%20%22NdrWebCombinedWithNetworks.country_code%22%20%5D%2C%20%22timeDimensions%22%3A%20%5B%20%7B%20%22dimension%22%3A%20%22NdrWebCombinedWithNetworks.record_date%22%2C%20%22dateRange%22%3A%20%22Last%207%20days%22%20%7D%20%5D%20%7D%20 \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

Equivalent POST request:

{
  "query": {
    "total": true,
    "measures": [
      "NdrWebCombinedWithNetworks.net_revenue",
      "NdrWebCombinedWithNetworks.impressions"
    ],
    "dimensions": [
      "NdrWebCombinedWithNetworks.record_date",
      "NdrWebCombinedWithNetworks.country_code"
    ],
    "timeDimensions": [
      {
        "dimension": "NdrWebCombinedWithNetworks.record_date",
        "dateRange": "Last 7 days"
      }
    ]
  }
}

Both GET and POST requests will return results in the same format.

If a query takes longer than 5 seconds to execute, the API will return the following:

{
  "error": "Continue wait",
  "stage": {
    "stage": "Executing query",
    "timeElapsed": 13240
  }
}

timeElapsed is the number of milliseconds elapsed since the start of the query. You can re-run the same query until results are returned.

Example response

The example query above returns a response like to the following:

{
  "query": {
    "total": true,
    "measures": [
      "NdrWebCombinedWithNetworks.net_revenue",
      "NdrWebCombinedWithNetworks.impressions"
    ],
    "dimensions": [
      "NdrWebCombinedWithNetworks.record_date",
      "NdrWebCombinedWithNetworks.country_code"
    ],
    "timeDimensions": [
      {
        "dimension": "NdrWebCombinedWithNetworks.record_date",
        "dateRange": [
          "2000-01-01T00:00:00.000",
          "2030-01-01T23:59:59.999"
        ]
      }
    ],
    "timezone": "UTC",
    "order": [],
    "filters": []
  },
  "data": [
    {
      "NdrWebCombinedWithNetworks.record_date": "1970-01-01T00:00:00.000",
      "NdrWebCombinedWithNetworks.country_code": "US",
      "NdrWebCombinedWithNetworks.net_revenue": 123.45,
      "NdrWebCombinedWithNetworks.impressions": 123
    },
    { ... }
  ],
  "lastRefreshTime": "1970-01-01T00:00:00.000Z",
  "annotation": {
    "measures": {
      "NdrWebCombinedWithNetworks.net_revenue": {
        "title": "Web Combined With Networks Net Revenue",
        "shortTitle": "Net Revenue",
        "type": "number",
        "format": "currency",
        "drillMembers": [],
        "drillMembersGrouped": {
          "measures": [],
          "dimensions": []
        }
      },
      "NdrWebCombinedWithNetworks.impressions": {
        "title": "Web Combined With Networks Impressions",
        "shortTitle": "Impressions",
        "type": "number",
        "drillMembers": [],
        "drillMembersGrouped": {
          "measures": [],
          "dimensions": []
        }
      }
    },
    "dimensions": {
      "NdrWebCombinedWithNetworks.record_date": {
        "title": "Web Combined With Networks Record Date",
        "shortTitle": "Record Date",
        "type": "time"
      },
      "NdrWebCombinedWithNetworks.country_code": {
        "title": "Web Combined With Networks Country Code",
        "shortTitle": "Country Code",
        "type": "string"
      }
    },
    "segments": {},
    "timeDimensions": {}
  },
  "dataSource": "default",
  "dbType": "bigquery",
  "extDbType": "cubestore",
  "external": false,
  "slowQuery": false,
  "total": 123
}

Formatting Your Query

• Filters
• Dimensions and Measures
• Time Dimensions
• Ordering
• Pagination
• Total Count

To get a list of cubes and their queryable dimensions and measures, see the Retrieving meta information section.

Filters

Filters can be used on dimensions to filter the returned data. Measures can also be filtered, but note that dimensions get filtered on the raw data while measures get filtered after the measure has been calculated.

Filter operators depend on the type of dimension or measure. The following filter operators are available:

Operator	Data Types	Description
equals	string, number, time	Checks for an exact match. Supports multiple values. e.g. ["US", "CA"]
notEquals	string, number, time	Checks for the opposite of equals. Supports multiple values. e.g. ["US", "CA"]
contains	string	Checks for string values containing the specified value(s). Case insensitive. Supports multiple values. For example, ["us", "ca"] would match dimension values "must" and "Cat".
notContains	string	Checks for the opposite of contains. Supports multiple values.
startsWith	string	Checks for string values that start with the specified value(s). Case insensitive. Supports multiple values.
endsWith	string	Checks for string values that end with the specified value(s). Case insensitive. Supports multiple values.
gt	number	Checks for values greater than the value specified.
gte	number	Checks for values greater than or equal to the value specified.
lt	number	Checks for values less than the value specified.
lte	number	Checks for values less than or equal to the value specified.
set	string, number, time	Checks whether the value is not null. You don’t need to pass in values for this operator.
notSet	string, number, time	Checks whether a value is null. You don’t need to pass in values for this operator.
inDateRange	time	Checks that a time dimension value is within the specified date range. If the specified value is a single date, it will filter for data on this date. Two values will be used as a start and end date, inclusive.
notInDateRange	time	Checks for the opposite of inDateRange. The values format is the same.
beforeDate	time	Checks that a time dimension value is before the specified date.
afterDate	time	Checks that a time dimension value is after the specified date.

📘Filtering on ad units is done using their ID, not their name.

The values property is always an array of 1 or more values, depending on the operator. This property should not be set when the operator is set or notSet.

Example query

{
  "query": {
    "total": true,
    "measures": [
      "NdrWebCombinedWithNetworks.net_revenue",
      "NdrWebCombinedWithNetworks.impressions"
    ],
    "dimensions": [
      "NdrWebCombinedWithNetworks.record_date",
      "NdrWebCombinedWithNetworks.country_code"
    ],
    "timeDimensions": [
      {
        "dimension": "NdrWebCombinedWithNetworks.record_date",
        "dateRange": "Last 7 days"
      }
    ],
    "filters": [
      {
        "member": "NdrWebCombinedWithNetworks.country_code",
        "operator": "equals",
        "values": ["US"]
      },
      {
        "member": "NdrWebCombinedWithNetworks.impressions",
        "operator": "lt",
        "values": ["100000"]
      },
      {
        "member": "NdrWebCombinedWithNetworks.record_date",
        "operator": "inDateRange",
        "values": ["2020-01-01", "2030-01-01"]
      },
      {
        "member": "NdrWebCombinedWithNetworks.country_code",
        "operator": "set"
      }
    ]
  }
}

Dimensions and Measures

Below, you can find all the queryable metrics and dimensions organized by table.

NdrApp

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
payment_relationship	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
ad_unit	string	All Roles
country_code	string	All Roles
device_type	string	All Roles
device_os	string	All Roles
browser	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
environment	string	All Roles
inventory_type	string	All Roles
inventory_format	string	All Roles
auction_type	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles

 

NdrVideo

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
payment_relationship	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
ad_unit	string	All Roles
country_code	string	All Roles
device_type	string	All Roles
device_os	string	All Roles
browser	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
environment	string	All Roles
inventory_type	string	All Roles
inventory_format	string	All Roles
auction_type	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles

NdrPrebid

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
size	number	All Roles
country_code	string	All Roles
jurisdiction	string	All Roles
device_type	string	All Roles
device_os	string	All Roles
browser	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
payment_relationship	string	All roles

Measures	Type	Role
net_cpm	number	All Roles
impressions	number	All Roles
net_revenue	number	All Roles

NdrPagehits

Dimensions	Type	Role
record_date	time	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles

Measures	Type	Role
net_cpm	number	All Roles
impressions	number	All Roles
net_revenue	number	All Roles
pageviews	number	All Roles
sessions	number	All Roles
pageviews_per_session	number	All Roles
session_rpm	number	All Roles
impressions_per_pageview	number	All Roles

 

NdrBlockedAds

Dimensions	Type	Role
record_date	time	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
partner	string	All Roles

Measures	Type	Role
net_revenue	number	All Roles

NdrCombinedRevenue

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
payment_relationship	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
environment	string	All Roles
inventory_type	string	All Roles
inventory_format	string	All Roles
device_type	string	All Roles

Measures	Type	Role
net_cpm	number	All Roles
impressions	number	All Roles
net_revenue	number	All Roles

NdrAmp

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
payment_relationship	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
environment	string	All Roles
inventory_type	string	All Roles
inventory_format	string	All Roles
ad_unit	string	All Roles
country_code	string	All Roles
device_type	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles

NdrUrl

Dimensions	Type	Role
record_date	string	All Roles
deal_type	string	All Roles
utm_content	string	All Roles
size	string	All Roles
device_type	string	All Roles
device_os	string	All Roles
browser	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
month	string	All Roles
network	string	All Roles
ad_unit	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
clean_url	string	All Roles
country_code	string	All Roles
country_name	string	All Roles
utm_campaign	string	All Roles
utm_medium	string	All Roles
utm_source	string	All Roles
utm_term	string	All Roles
referrer	string	All Roles
referrer_category	string	All Roles
inventory_format	string	All Roles
inventory_type	string	All Roles
environment	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles

NdrViewability

Dimensions	Type	Role
record_date	string	All Roles
month	string	All Roles
ad_unit	string	All Roles
placement_name	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
device_type	string	All Roles
country_code	string	All Roles
country_name	string	All Roles
environment	string	All Roles

Measures	Type	Role
impressions	number	All Roles
eligible_impressions	number	All Roles
measurable_impressions	number	All Roles
viewable_impressions	number	All Roles
viewable_rate	number	All Roles

NdrAdBlockRecovery

Dimensions	Type	Role
record_date	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
country_code	string	All Roles
country_name	string	All Roles
device_type	string	All Roles
device_os	string	All Roles

Measures	Type	Role
detected_pageviews	number	All Roles
detected_users	number	All Roles
recovered_pageviews	number	All Roles
recovered_users	number	All Roles
estimated_recovered_revenue	number	All Roles
estimated_recovered_impressions	number	All Roles
pageviews_recovered_percentage	number	All Roles

NdrCombinedRealtime

Dimensions	Type	Role
record_date	string	All Roles
month	string	All Roles
hour	string	All Roles
date_hour	string	All Roles
deal_type	string	All Roles
url	string	All Roles
referrer	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles

NdrOther

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
payment_relationship	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
ad_unit	string	All Roles
country_code	string	All Roles
device_type	string	All Roles
device_os	string	All Roles
browser	string	All Roles
demand_partner	string	All Roles
integration_partner	string	All Roles
integration_platform	string	All Roles
environment	string	All Roles
inventory_type	string	All Roles
inventory_format	string	All Roles
auction_type	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles

NdrWebCombinedWithNetworks

Dimensions	Type	Role
record_date	time	All Roles
network	string	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
ad_unit	string	All Roles
country_code	string	All Roles
device_type	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles

NdrWebCombinedWithPageviews

Dimensions	Type	Role
record_date	time	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles
sessions	number	All Roles
pageviews	number	All Roles
page_rpm	number	All Roles
session_rpm	number	All Roles
fill_rate	number	All Roles

NdrWebCombinedWithRequests

Dimensions	Type	Role
record_date	time	All Roles
site_name	string	All Roles
site_domain	string	All Roles
site_type	string	All Roles
device_type	string	All Roles
ad_unit	string	All Roles

Measures	Type	Role
impressions	number	All Roles
net_revenue	number	All Roles
net_cpm	number	All Roles
requests	number	All Roles
pageviews	number	All Roles
fill_rate	number	All Roles

Time Dimensions

Data can be filtered by a date range. There are two ways to specify a date range.

The first is to use one of the following presets: Today, Yesterday, This week, This month, This quarter, This year, Last 7 days, Last 30 days, Last 60 days, Last week, Last month, Last quarter, Last year.

Example query

{
  "query": {
    "total": true,
    "measures": [
      ...
    ],
    "dimensions": [
      ...
    ],
    "timeDimensions": [
      {
        "dimension": "NdrWebCombinedWithNetworks.record_date",
        "dateRange": "Last 7 days"
      }
    ]
  }
}

The second is to specify two dates. These dates are inclusive.

Example query

{
  "query": {
    "total": true,
    "measures": [
      ...
    ],
    "dimensions": [
      ...
    ],
    "timeDimensions": [
      {
        "dimension": "NdrWebCombinedWithNetworks.record_date",
        "dateRange":  ["2020-01-01", "2030-01-01"]
      }
    ]
  }
}

Ordering

By default, results are sorted using the following rules:

The first time dimension with granularity, in ascending order. If there are no time dimensions with a granularity specified...
The first measure, in descending order. If there are no measures specified...
The first dimension, in ascending order.
You can specify the desired order by including an order value in the query object.

Example query

{
  "query": {
    "total": true,
    "measures": [
      ...
    ],
    "dimensions": [
      ...
    ],
    "timeDimensions": [
      { ... }
    ],
    "order": {
      "NdrWebCombinedWithNetworks.record_date": "asc",
      "NdrWebCombinedWithNetworks.country_code": "desc"
    }
  }
}

Pagination

By default, the API will return a maximum of 10,000 records. This limit can be changed up to a maximum of 50,000.

An offset can also be provided for pagination support.

Example query

{
  "query": {
    "total": true,
    "measures": [
      ...
    ],
    "dimensions": [
      ...
    ],
    "timeDimensions": [
      { ... }
    ],
    "limit": 5,
    "offset": 5
  }
}

Total Count

To get the total number of records, set total to true in the query object. A total will be included in the response.

Example query

{
  "query": {
    "total": true,
    "measures": [
      ...
    ],
    "dimensions": [
      ...
    ],
    "timeDimensions": [
      { ... }
    ]
  }
}

Retrieving meta information

Metadata about the cubes and their dimensions and measures can be queried using the following URL: https://analytics.pub.network/cubejs-api/v1/meta

Example query

curl -X GET https://analytics.pub.network/cubejs-api/v1/meta \
-H "Accept: application/json" \
-H "Authorization: Bearer {token}"

Example Response

{
  "cubes": [
    {
      "name": "NdrWebCombinedWithNetworks",
      "title": "Web Combined With Networks",
      "connectedComponent": 1,
      "measures": [
        {
          "name": "NdrWebCombinedWithNetworks.impressions",
          "title": "Web Combined With Networks Impressions",
          "shortTitle": "Impressions",
          "cumulativeTotal": false,
          "cumulative": false,
          "type": "number",
          "aggType": "sum",
          "drillMembers": [],
          "drillMembersGrouped": {
            "measures": [],
            "dimensions": []
          },
          "isVisible": true
        },
        { ... }
      ],
      "dimensions": [
        {
          "name": "NdrWebCombinedWithNetworks.record_date",
          "title": "Web Combined With Networks Record Date",
          "type": "time",
          "shortTitle": "Record Date",
          "suggestFilterValues": true,
          "isVisible": true
        },
        { ... }
      ],
      "segments": []
    },
    { ... }
  ]
}

Questions?

Please submit a request here if you require further assistance.

What's Next 

Data Glossary