Integrating TV Graphics
How to feed live data into TV graphics systems
An introduction to the topic is available atTV & Streaming Graphics
The platform provides dynamic data which can be fed into TV Graphics to populate real-time visualisations.
This data is available via two core methods:
Control API - this is the recommended method for security, speed and flexibility
Public feeds - these feeds are served via a CDN and data can be exposed for convenience. However this is a slower and less secure method.
You may also choose to create custom feeds that you make using either of these two methods to generate your own formats. For example, using a Lambda to generate your own endpoint.
This document covers the Control API method.
Note that we often refer to "votes", where this data can relate to any form of user selection such as a prediction, rating or other.
Prerequisites
In order to use Control API to access voting data you will need the following information:
Project ID
Event ID
Bearer token
These instructions assume that you have a Studio user account with at least “Viewer” level access. Log in to Studio and navigate to the Project and Event that you plan to use for voting. Please contact Monterosa at support@monterosa.co.uk if you need an account creating for this purpose.
Bearer token
See details of how to generate a bearer token for your account here: Control API - Generating a bearer token
Project ID and Event ID
To obtain the Project and Event ID, navigate to the relevant Event in your project, and navigate to Event Settings > Event > Event ID and copy these values.
Voting data feeds in the Control API
Within the Control API, a vote is an Element with content_type: vote
. The list of all elements within the vote Event can be obtained by using the REST API call described here - Get Elements
The request can be performed using a CURL command like the following:
The result of that GET request will be a JSON object containing all elements metadata and the aggregated vote results. The most relevant fields of which are:
data
- Includes all the elements data, on each element, we’ll find:attributes.content_type
will specify the type of element you retrieved. Make sure it’s value equalsvote
.state
will specify the state the element is in. The following page documents which values it can take and their meaning: Element Resourceattributes.question
will contain the JSON data for the question we are asking our usersoptions[X].fields["key"].values.all
specifies the textual representation of the option a user votes for. Note thatX
will be the index used to aggregate its stats in the stats section of the JSON.
included
- Will contain an array with the stats for each of the elements with matching indexes to that of the data array. This data is only included if you provide the?include=stats
URL query parameter.attributes.aggregated.voters
will include the total count of votersattributes.aggregated.votes
will include the total count of votesattributes.results[X].votes
will include the total count of votes a specific answer option received. E.g. how many votes a candidate on a reality tv show got.attributes.results_are_final
will indicate if the voting has concluded
Mapping data obtained from Monterosa / Interaction Cloud to external voting data
Once you have obtained the data you need, and parsed through it to obtain the relevant data, you may need to match the vote statistics to other vote sources to produce a final tally of votes.
Our suggested approach is to match the text used in the question options to the alternatives a vote can have.
The JSON structure can be navigated using a code similar to the following Javascript snippet:
As a result of the snippet above, you’ll receive a JSON response similar to the following (some data is trimmed down for brevity):
Stopping the requests when the Element has closed
We recommend to use the boolean in attributes.results_are_final
in the included
stats of the JSON obtained to identify if the Element has been closed. If its value is true
, then you should stop performing requests to the API so as to avoid wasting resources. If the value is false
, continue requesting data by respecting the rate limits as described in the next section.
Rate limits
Please note that the Control API V2 has rate limits that are described here
Although we allow for multiple requests per second, we recommend a latency that matches your expectations on data freshness which will usually be multiple seconds between requests (e.g. every minute).
Further information
Please contact Monterosa’s support team if you require any further information regarding the implementation of voting integration by sending an email to support@monterosa.co.uk
Was this helpful?