API Overview

This guide outlines how to access the MediaMelon SmartSight Analytics API.

The MediaMelon SmartSight Analytics API provides RESTful endpoints to retrieve data from the SmartSight backend. Using these APIs, you can fetch and process data according to your requirements. The APIs are secured via OAuth2 authentication.

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>'

Request query parameters

grant_type string

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

username string

A mandatory query parameter in form of a string with Smartsight Username value

password string

A mandatory query 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"
}

Get number of plays GET

Returns number of plays happened within the specified timeframe

curl 'https://smartsight2.mediamelon.com/mm-apis/qbrData/vod/<customer-id>?planlevel=<level>&period=start=1729104657,end=1730244657&metrics=viewercount'
-x GET --header 'Authorization: Bearer 6ABBCCCD-EEE1-FFF2-GGG3-HIJKLMNOP456'

If you run this request yourself it will not work, you should replace the bearer token (6ABBCCCD-EEE1-FFF2-GGG3-HIJKLMNOP456) in this example with your own OAuth access token you get by running Fetch OAuth Token

Request path parameters

customer-idstring

A path parameter in form of a string. This is the unique identifier and you will be able to find this Id on https://smartsight2.mediamelon.com/control-panel/user-profile

Request query parameters

planlevel string

A mandatory query parameter in form of a string. This is the plan identifier number associated with CustomerID and you will be able to find this plan level using https://smartsight.mediamelon.com/planLevelByCustId/<customer-id>

period string

A mandatory query parameter in comma-separated string format. It needs to in the format of start date and end date (eg: start=1729104657,end=1730244657) in epoch time. For reference, use this Epoch Time converter

metrics string

A mandatory query parameter in string format. The request can also be made with comma-separated format to retrieve combinations of metrics. (e.g. viewercount, playdur, bufferingratio, latency, subscriberid, errors, viewercount, subscribertag, ipaddress, timestamp, starttime, endtime, etc.)

Optional request query parameters

limit string

An optional query parameter in string format to return maximum number of records (e.g., 10)

dimension string

An optional query parameter in string format to return the target level for data (eg: microscope)

filter string

An optional query parameter in string format to return data with filter criteria (e.g., subscriberid={subscriber-id})

orderas string

An optional query parameter in string format to return data in order (e.g., DESCOR ASEC)

offset string

An optional query parameter in string format to return data with starting index (e.g., 1)

agg string

An optional query parameter in string format to return data by enabling or disabling aggregation (values: 1 or 2)

aggby string

An optional query parameter in string format to return aggregated data with aggregation by (eg.: subscriberid={subscriber-id})

orderby string

An optional query parameter in string format to return data with order by (eg.: viewercount)

Response

GET 200

{
    "totalcount": 1,
    "pagecount": 1,
    "totalrecords": 1,
    "response": [
        {
            "viewercount": 5029111,
            "totalpages": 1
        }
    ]
}