Announcing our brand new Developer Guides and API documentation in beta! Click here to see the new docs.

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.

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 parameter

Parameter Type Description
{property key} String (Required) 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, and video_duration



METRICS -

ad_impressions, ads_per_viewer, completes, complete_rate, plays, plays_per_viewer, time_watched, time_watched_per_viewer, and 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 value 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

    uploade_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



Use this form to provide your feedback.