API Overview

Welcome to MediaMelon's SmartSight Analytics API developer documentation. This guide outlines how to access the these APIs and use them to access real-time and historical data.

The MediaMelon SmartSight Analytics APIs provide programmatic access to all the data which is currently visualized in the Smartsight web portal. You can use these RESTful API endpoints to build custom dashboards, extract data for warehouse purposes, or ingest data into third-party tools. MediaMelon APIs can be easily integrated into your applications and provide HTTP response codes to indicate API errors. The APIs are secured via OAuth2 authentication.

There are 4 sets of MediaMelon APIs as mentioned down here :

1. SmartSight Metrics and Dimensions APIs

   • Metrics

   • Dimensions

2. SmartSight Smartquery APIs

   • Content Paths

   • Subscriber Insight

3. SmartSight Error APIs

   • Error Heatmap

4. SmartSight Alert APIs

   • Alerts

Prerequisites

To fetch data from the backend, Smarthsight Analytics API authenticates users via an OAuth Token. To obtain this token, you need these prerequisites:

1. Username - Your SmartSight username

2. Password - Your SmartSight password

Contact your MediaMelon representative in case you're not aware of the above mentioned prerequisites

Fetch OAuth Token POST

Retrieve an OAuth access token for authentication.

curl 'https://smartsight2.mediamelon.com/generateOAuthToken'
-x POST --header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'grant_type=password'
--data-urlencode 'username=<username>'
--data-urlencode 'password=<password>'

Required request body parameters

grant_type string

A body parameter in form of a string with "password" as value

username string

A body parameter in form of a string with Smartsight Username value

password string

A body parameter in form of a string with Smartsight Password value

Response

POST 201

{
    "access_token": "6ABBCCCD-EEE1-FFF2-GGG3-HIJKLMNOP456",
    "token_type": "bearer",
    "refresh_token": "ZZZZ999-YYY8-WWW7-VVV6-UTSRqPOn5432",
    "expires_in": 18000,
    "scope": "read write"
}

The access_token "6ABBCCCD-EEE1-FFF2-GGG3-HIJKLMNOP456" is shown here for representation. Once you run this POSTrequest, make note of the access_token which needs to be used for making other subsequent POST, GET, PUT, PATCH, and DELETE requests to the MediaMelon APIs. This token needs to be included in every request as :

--header 'Authorization: Bearer 6ABBCCCD-EEE1-FFF2-GGG3-HIJKLMNOP456'

SmartSight Metrics and Dimensions API

This endpoint with combinations of path/query/body parameters will help you fetch the data in any combination (metrics and dimensions). Following dashboards use this API endpoint to fetch required data and present it on the platform :

1. KPIs Dashboard

2. Video Experience Dashboard/s

3. Ad Experience Dashboard/s

4. Content Insights

5. Content Analysis

Endpoint :

GET /mm-apis/qbrData/vod/{customerId}

This FastAPI endpoint fetches data for a given customer based on various query parameters.

• Path Parameters:

  • customerId (int, required): The customer ID for which the data is requested.

• Query Parameters:

  • planlevel (int, required): The plan level of the customer.

  • metrics (str, required): The metrics to retrieve (e.g., viewercount, latency).

  • period (str, required): The time range for the query (in 'start=timestamp,end=timestamp' format).

  • token_info (dict, optional): Token information for authentication, validated using validate_token.

  • limit (int, default=1000): Limit the number of results.

  • offset (int, default=0): Offset for paginated results.

  • aggby (str, optional): Aggregation level for the data.

  • agg (str, optional): Aggregation function to use (e.g., sum, avg).

  • orderby (str, optional): Column to order the results by.

  • order (str, default='desc'): The order direction (ascending or descending).

  • count (int, optional): Total count of records.

  • filter (str, optional): Filters to apply on the query.

  • dimension (str, default='all'): The data dimension to query (e.g., microscope, subscriber, ad, geo).

  • granularity (str, default='auto'): The granularity of the data (e.g., minute, hour, day).

• Functionality:

  • Validates the customer ID with the token.

  • Parses the period parameter to get the start and end times.

  • Adjusts the granularity based on the time difference in the query.

  • Determines the appropriate table view based on the given dimension and filters.

  • Constructs a ClickHouse SQL query based on the provided parameters.

  • Executes the query asynchronously with a 200-second timeout.

  • Processes the query result, converting the data into a list of dictionaries.

  • Returns the total count, page count, total records, and response data.

• Returns:

  • A JSON response containing:

    • totalcount: The total number of records in the response.

    • pagecount: The total number of pages.

    • totalrecords: The total number of records in the query.

    • response: A list of dictionaries, each representing a row of data.

For further information on how to fetch this data programmatically using API endpoints along with path/query/body parameters, refer to Video Experience and Ad Experience guides.

SmartSight Smartquery API

This endpoint with combinations of path/query/body parameters will help you fetch content insights, engagement behavior data. Following dashboards use this API endpoint to fetch required data and present it on the platform :

1. Content Paths

2. Subscriber Insight

Endpoint :

GET /mm-apis/smartQuery/{customerId}

Executes a Smart Query with various filtering, period, and aggregation options.

• Path Parameters:

  • customerId (int, required): The customer ID for which the data is requested.

• Query Parameters:

  • planlevel (int, required): The plan level of the customer.

  • queryname (str, required): The query to execute.

  • period (str, required): The time range for the query (in 'start=timestamp,end=timestamp' format).

  • filter (str, optional): Filters to apply on the query.

  • limit (int, default=1000): Limit the number of results.

  • offset (int, default=0): Offset for paginated results.

  • granularity (str, default='auto'): The granularity of the data (e.g., minute, hour, day).

  • querycache (str, default='True'): Whether to use query caching.

  • queryId (str, optional): uuid, to track the query.

• Returns:

  • A JSON object containing:

    • totalcount: Total number of records in the response.

    • pagecount: Total number of pages.

    • totalrecords: Total number of records found.

    • response: A list of results based on the query.

For further information on how to fetch data programmatically using above API endpoint along with path/query/body parameters, refer to Smartquery Insights guide.

SmartSight Error API

This endpoint with combinations of path/query/body parameters will help you fetch errors and error heatmaps data. Following dashboard use this API endpoint to fetch required data and present it on the platform :

1. Error Heatmap

Endpoint :

GET /mm-apis/error/{customerId}

• Path Parameters:

  • customerId (int, required): The customer ID for which the data is requested.

• Query Parameters:

  • planlevel (int, required): The plan level of the customer.

  • metrics (str, required)): The metrics to retrieve (e.g., viewercount, latency).

  • period (str, required)): The time range for the query (in 'start=timestamp,end=timestamp' format).

  • limit (int, default=1000): Limit the number of results.

  • offset (int, default=0): Offset for paginated results.

  • aggby (str, optional): Aggregation level for the data.

  • agg (str, optional): Aggregation function to use (e.g., sum, avg).

  • orderby (str, optional): Column to order the results by.

  • order (str, default='desc'): The order direction (ascending or descending).

  • count (int, optional): Total count of records.

  • filter (str, optional): Filters to apply on the query.

  • dimension (str, default='all'): The data dimension to query (e.g., microscope, subscriber, ad, geo).

  • granularity (str, default='auto'): The granularity of the data (e.g., minute, hour, day).

  • queryId (str, optional): uuid, to track the query.

• Returns:

  • A JSON object containing:

    • totalcount: Total number of records in the response.

    • pagecount: Total number of pages.

    • totalrecords: Total number of records found.

    • response: A list of results based on the query.

For further information on how to fetch data programmatically using above API endpoint along with path/query/body parameters, refer to Errors guide.

SmartSight Alert API

This endpoint with combinations of path/query/body parameters will help you fetch alerts data. Following dashboard use this API endpoint to fetch required data and present it on the platform :

1. Alerts

Endpoint :

GET /mm-apis/getAIAlerts/{customerId}

• Path Parameters:

  • customerId (int, required): The customer ID for which the data is requested.

• Query Parameters:

  • planlevel (int, required): The plan level of the customer.

  • period (str, required)): The time range for the query (in 'start=timestamp,end=timestamp' format).

  • limit (int, default=1000): Limit the number of results.

  • offset (int, default=0): Offset for paginated results.

  • orderby (str, optional): Column to order the results by.

  • order (str, default='desc'): The order direction (ascending or descending).

• Returns

  • An array of JSON objects containing:

    • response: A list of results based on the query.

For further information on how to fetch data programmatically using above API endpoint along with path/query/body parameters, refer to guide.