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 :
SmartSight Metrics and Dimensions APIs
Metrics
Dimensions
SmartSight Smartquery APIs
Content Paths
Subscriber Insight
SmartSight Error APIs
Error Heatmap
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:
Username - Your SmartSight username
Password - Your SmartSight password
Contact your MediaMelon representative in case you're not aware of the above mentioned prerequisites
Fetch Auth Token POST
Updated SmartSight token for authentication based off Keycloak integration.
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 DELETErequests to the MediaMelon APIs. This token needs to be included in every request as :
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 :
KPIs Dashboard
Video Experience Dashboard/s
Ad Experience Dashboard/s
Content Insights
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.
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 :
Content Paths
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.
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 :
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.
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 :
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.
