The CMS API is a way for a third party (typically a CMS) to notify VidiReports of currently playing content so that this may be correlated with the audience in VidiCenter’s data. It consists of two HTTP API points, one to notify a content start and one to notify a content stop. Additionally, the content stop API point may return information about the audience during the content lifetime; this is called verification data.
Note
This API supercedes the legacy APC API used by VidiReports 6.x.
In addition to this, there is another API point that allows a client to get a forecast of the expected audience (in terms of impressions) at some point and duration in the near future. This is called the predictive data.
The base URI for the API is
http[s]://<vidireports host>:<vidireports port>/v1
The host is typically localhost or 127.0.0.1 for local usage. The default port is 9080 for HTTP and 9443 for HTTPS. In the case of HTTPS, note that the embedded certificate is self-signed.
Parameters are sent by the client as GET parameters, URL-encoded as per RFC 3986. Responses are sent by VidiReports as JSON objects, using an UTF-8 encoding.
All strings values must be limited to 1024 bytes after UTF-8 encoding.
Note
Although this API itself is always available, verification and predictive data are only available if they’re explicitely enabled for your installation. Please contact Quividi if you want it enabled.
Note
This API is available since VidiReports 7.1
Content start
Content start requests must be sent in real-time exactly when the content starts playing since the associated timestamps will be the instants in which the requests are received. The URI is
http[s]://<vidireports host>:<vidireports port>/v1/start
The following parameter is mandatory:
- content_id
The content identifier. String. (Here and everywhere else in the API, strings are limited to 1024 bytes after UTF-8 encoding)
The following parameter is mandatory only if there are multiple instances of VIdiReports running on the same host:
- instance_name
The name of the VidiReports instance that is the target for this call. If there is only one VidiReports instance, this parameter may be omitted. String.
Optional parameters:
- frame_id
The term “frame” denotes an area on the display for which there is an independent content schedule; it is used in the same sense as in the Broadsign player specification. Ultimately, a piece of content is uniquely identified by the (content_id, frame_id) pair; you may therefore have the same content_id associated to different frame_id’s at any given time.
- app_name
The client application name. String.
- campaign_id
The campaign identifier. String.
- autostop (since VidiReports 7.8.0.0)
If this is “true”, all currently playing contents will be stopped before the specified one is started. The audience statistics for those will not be returned.
Any other paremeters will be ignored.
Note
The behavior of the legacy APC API (VR V6 and earlier) with respect to the content length was to automatically stop the clip after a user-specified duration. In the current API, an explicit stop request must be issued, and the content stop request returns a significant response payload.
Error cases
No VidiReports instance with the specified name
No VidiReports instance name supplied on a multi-instance configuration
Content ID missing
Content already started
Invalid parameter (string too long)
Unexpected error (see reason)
Content stop
Content stop requests must be sent in real-time when the content stops. The URI is
http[s]://<vidireports host>:<vidireports port>/v1/stop
A content stop request will usually return a JSON payload containing audience information for the stopped content. See below for details.
Request parameters:
- content_id
See above; it must match the ID of a previously-issued start request.
- frame_id
See above. If the start request included a frame_id, the same frame_id must be specified in the corresponding stop request.
- instance_name
See above. Optional if there is only a single VidiReports instance, mandatory otherwise.
All other parameters will be ignored.
Note
If the content_id and frame_id parameters are both omitted, all currently playing content for the named instance will be stopped. If only frame_id is specified, all content playing on the specified frame will be stopped. In these cases, the returned payload will NOT contain any audience data. This is intended for bookkeeping, for instance on startup of the API client.
Error cases
No instance with the specified name
No instance name supplied on a multi-instance configuration
Invalid parameter (string too long)
No such content playing
Unexpected error (see reason)
Prediction requests
Prediction requests are not tied to a particular content but only to the audience statistics observed by VidiReports up to the request instant and return an audience forecast for a time window in the future.
There’s a single API point:
http[s]://<vidireports host>:<vidireports port>/v1/pre
Mandatory request parameters:
- instance_name
See above.
- expected_play_time
The start timestamp for the forecast window in milliseconds since the Unix Epoch (UTC). This cannot be more than 300 seconds in the future.
- expected_duration
The span of the forecast time window in milliseconds. Minimum value is 1000. Maximum value is 300000.
All other arguments will be ignored.
Error cases
No instance with the specified name
No instance name supplied on a multi-instance configuration
Invalid parameter (string too long)
Missing parameter
Time window start too far
Time window start in the past
Time window end too far (to be agreed upon)
Invalid numeric parameter
Unexpected error (see reason)
VidiReports response
All requests return a JSON payload, UTF-8 encoded. They have the following structure:
Error response (object)
status (string): “ko”
reason (string): human-readable error message
Response to verification start request (object)
status (string): “ok”
timestamp (integer): This is the timestamp of the moment the request was handled by VidiReports, in milliseconds since the Unix Epoch (UTC).
utc_offset (integer): Offset from local time to UTC, in seconds, on the computer VidiReports runs on.
Response to verification stop request (object)
status (string): “ok”
timestamp (integer): Same as for verification start requests
utc_offset (integer): Same as for verification start request
duration (integer): Associated content duration in milliseconds
audience_clip (object)
total (integer): The total number of impressions during the content
gender (object): Impressions, split by gender; this has the following keys
male (integer)
female (integer)
unknown (integer)
age (list of objects): Audience count, split over age brackets.
min (integer): Age bracket lower threshold, in years
max (integer): Age bracket higher threshold, in years
count (object): Watcher count, dispatched by gender
male (integer)
female (integer)
unknown (integer)
Response to prediction request (object)
Same format as for verification stop requests, with the following differences:
audience_clip is named audience_pre instead
An additional metric key, current value is “3AI-F0”
An additional duration key, which contains the measured clip duration in milliseconds.