Analytics API reference

Last Updated: June 12, 2019

This Analytics API reference details the structure of the query request body and query response body. Be sure you have your API credentials and understand how to create a report query.

TIP

View some examples of report queries. These examples demonstrate both basic and advanced queries that can be run against the Analytics API.

Route

https://api.jwplayer.com/v2/sites/{property key}/analytics/queries?format=csv&source=default

URL parameters

Parameter Type Description
{property key} String Unique property identifier
format String File type of the response query output

Possible values include:

json (Default)
csv
source String Data set against which to run the request query

Possible values include:

default: This option includes all JW Player data, excluding OTT data.
floatleft: This option only includes OTT data.


The following dimensions and metrics are available for OTT data:

DIMENSIONS

country_code
eastern_date
media_id,
platform_id
playlist_id
playlist_type
tag
upload_date
video_duration

METRICS

ad_impressions
ads_per_viewer
completes
complete_rate
plays
plays_per_viewer
time_watched
time_watched_per_viewer
unique_viewers



Query body structure

{
  "start_date": "2017-06-01",
  "end_date": "2017-06-02",
  "dimensions": ["country_code"],
  "metrics": [{
    "operation": "sum",
    "field": "plays"
  }],
  "filter": [{
    "field": "device_id",
    "operator": "=",
    "value": ["Desktop"]
  }],
  "page": 0,
  "page_length": 2,
  "sort": [{
    "field": "plays",
    "order": "DESCENDING"
  }]
}
Property Type Description
dimensions Array Dimensions to include in the report query response, listed by dimension_id
end_date String Last date of a query date range in YYYY-MM-DD format
filter Object Defines how to restrict the data returned in the response

See: filter object
include_metadata* Boolean Indicates that eligible dimensions are enriched with additional metadata

Depending on the dimension, enriched metadata appears either in the includes or metadata.name object of the query response.
metrics Array Metrics to include in the report query response, listed by metric_id.

See: metrics object
page Number Index of the page of results

The value of the first page of results is 0. The number of total pages is inversely related to the page_length.
page_length Number (JSON only) Total number of records returned on each page of results

If not set, the default value is 10. This value must be ≤ 100.
relative_timeframe String Preconfigured time range for a report query

Possible values include:

7 Days
30 Days
90 Days
Last Quarter
Month To Date
Today
Yesterday
sort Object Defines the field by which to sort the data and the order of the sort

See: sort object
start_date String First date of a query date range in YYYY-MM-DD format

* This property requires a JW Player Enterprise or Developer license.

filter

Property Type Description
field String Dimension dimension_id by which to restrict the returned data set

When filtering JWP Data, all dimension_id variables can be used.

When filtering OTT Data, only the following dimension_id variables can be used:
country_code
eastern_date
media_id
platform_id
playlist_id
playlist_type
tag
upload_date
video_duration
operator String Filter-matching behavior

Possible values include:
=: Use this operator when the value is an ID.
!=: Use this operator when the value is an ID.

LIKE: Use this operator when the value is metadata information.
!LIKE
: Use this operator when the value is metadata information.
value String Value of a specific dimension_id by which to restrict the returned data set

* This property requires a JW Player Enterprise or Developer license.

metrics

Property Type Description
field String Metrics to include in the report query response, listed by metric_id
operation String Calculation applied to selected metric

Possible values include:

max
min
sum

sort

Property Type Description
field String Metric or dimension by which the response query is organized

The metric or dimension must be on of the metrics and dimensions included in the report query body.
order String Manner in which response query is organized

Possible values include:

ASCENDING
DESCENDING



Query response structure

{
  "data": {
    "rows": [
      [
        "column1value",
        "column2value",
      ]
    ]
  },
  "metadata": {
    "column_headers": {
      "dimensions": [
        {
          "field": "dimension_id",
          "type": "datatype"
        }
      ],
      "metrics": [
        {
          "field": "plays",
          "units": "dataype"
        }
      ]
    }
  },
  "page": "page number",
  "page_length": "page length",
  "type": "query_results",
  "includes": {
    "object_id": {
      "metadata varies"
    },
    "type": "type of object_id"
  }
}
Property Type Description
data Object See: data object
includes Object See: includes object
metadata Object See: metadata object
page Number Index of the page of results
page_length Number (JSON only) Total number of records returned on each page of results
type String Category of report query

This will always return query_results.

data

Property Type Description
rows Array Values for each metadata.column_headers property listed as an array of nested arrays

includes

Property Type Description
(ad_schedule_id - unique ID of the returned type) Object When include_metadata: 1 and dimensions: ["ad_schedule_id"] are part of the API query, an object of identifier-to-name pairings

The object includes:

name: User-generated name of the ad schedule
(media_id - unique ID of the returned type) Object When include_metadata: 1 and dimensions: ["media_id"] are part of the API query, an object of identifier-to-name pairings

The object includes:

duration_bucket: Categorization of video duration
tags: Metadata tags associated with the media item
title: Name of the media item
upload_date: Date when the media item was uploaded in YYYY-MM-DD format
(playlist_id - unique ID of the returned type) Object When include_metadata: 1 and dimensions: ["playlist_id"] are part of the API query, an object of identifier-to-name pairings

The object includes:

title: Name of the media item
type: Type of playlist
(player_id - unique ID of the returned type) Object When include_metadata: 1 and dimensions: ["player_id"] are part of the API query, an object of identifier-to-name pairings

The object includes:

name: User-generated name of the player
type String Dimension to which the unique ID belongs

Possible values include:

ad_schedule_id
media_id
player_id
playlist_id

metadata

Property Type Description
column_headers Object Category of column data

Possible values include:

dimensions
metrics

See: metadata.column_headers object
end_date String Last date of a query date range in YYYY-MM-DD format
name Object See: metadata.name object
start_date String First date of a query date range in YYYY-MM-DD format

metadata.name

Property Type Description
city Object When include_metadata: 1 and dimensions: ["city"] are part of the API query, an object of identifier-to-name pairings

For example:

"city": {"Brussels BRU BE": "Brussels - Brussels Capital (Belgium)"}
country_code Object When include_metadata: 1 and dimensions: ["country_code"] are part of the API query, an object of identifier-to-name pairings

For example:

"country_code": {"HU": "Hungary", "NL": "Netherlands"}
device_id Object When include_metadata: 1 and dimensions: ["device_id"] are part of the API query, an object of identifier-to-name pairings

For example:

"device_id": {"Desktop": "Desktop", "Phone": "Phone"}
platform_id Object When include_metadata: 1 and dimensions: ["platform_id"] are part of the API query, an object of identifier-to-name pairings

For example:

"platform_id": {"web": "Web"}

metadata.column_headers

Property Type Description
dimensions Array Set of objects for each dimension included in the report query

Each object includes:

field: The dimension_id value.
unit: Format of the data that is returned
metrics Array Set of objects for each metric included in the report query

Each object includes:

field: The metric_id value
unit: Format of the data that is returned

Analytics API reference


Last Updated: June 12, 2019

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.