Revma Reports API
- Achilleas Poulios (Unlicensed)
- Panos Koundouros (Unlicensed)
Reports API
Version 1.2
Purpose of this document
The purpose of this document is to provide a quickstart for the various steps a user must take in order to be able to access an account’s/station’s “Analytics” remotely through the provided APIs.
Process Flow
All requests get authenticated using a special header of X-Auth-token. This token can be generated using user credentials, but there is also the option that RCS can create a token for your that never expires.
Revma APIs
Overview
Revma APIs allows you to call methods that respond in JSON format. The REST API is the underlying interface for all of our official apps and our SDKs. It’s the most direct way to access the API. This reference document is designed for those interested in developing platforms not supported by the SDKs or for those interested in exploring the API features in detail.
Base URL
To access Revma APIs you should always use the following base url:
portal-url = https://www.revma.com |
Response Codes
The API is using the standard HTTP Status Codes
Status | Description |
200 | OK |
400 | Malformed Request |
401 | Not Authorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
500 | Internal Server Error |
501 | Not Implemented |
503 | Service Unavailable |
Authorization Flow
This info is only present for reference purposes. The whole “Authorization Flow” part of this document can be skipped. Since the X-Auth-App-Secret is only available to the Revma Engineers. Please contact RCS technologies Greece for the token generation.
Portal API
Example request: POST /api/auth/token/ HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript X-Auth-App-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx { "username":"xxxxxx", "password":"xxxxxx" } Example response: HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "token": "xxxxxxxxxxxxxxxxxxxxx", "client": "xxxxxxxxxxxxxxxxxxxx", "expires": "2019-01-11 11:54:08.507563", "rights": "user", "created": "2019-01-09 09:54:08.524186" } |
Request Headers | Description |
X-Auth-App-Secret (required) | Application secret |
Request Parameters | Description |
username (required) | The username of an existing user that has access to the account you want to manage. |
password (required) | The user’ s password |
Response Parameters | Description |
token | The User Token created for communication with the Portal API |
client | The user’s key |
rights | The user’ s rights |
created | User token’ s creation date |
expires | User token’ s expiration date |
Account Stats
Account Hour stats
Example request: GET /api/accounts/<account_key>/stats/day?date=2019-02-10&&include_vast=true&include_outputs=false HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "date": "2019-02-10", “hour_stats”: [ { "hour": 0, "stats": { "uniques": 139, "disconnected": 169, "thirdQuartile": 115, "midpoint": 116, "connections": 229, "start": 118, "connected": 164, "impressions": 118, "firstQuartile": 118, "kilobytes": 5.738795017976184, "requests": 1398, "listening_time": 212278, "complete": 115, "streams": [ { "thirdQuartile": 0, "uniques": 1, "name": "Rj-test ", "stream": "we1u30n1hfquv", "sessions": 1, "disconnections": 1, "midpoint": 0, "firstQuartile": 0, "connections": 1, "start": 0, "traffic": 0.00046094227582216263, "duration": 30, "impressions": 0, "requests": 0, "complete": 0 }, … ], }, }, …. ] } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
account_key (required) | The account key to display stats |
date (required) | in the format YYYY-MM-DD |
Include_outputs | Whether to include relays [true/false] |
include_vast | Whether to include vast [true/false] |
Account Period stats
Example request: GET /api/accounts/<account_key>/stats/period?from_date=2019-02-03&to_date=2019-02-09&include_vast=true&include_outputs=true HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "start": "2019-02-03", "end": "2019-02-09", "period_stats": [ { "stats": { "streams": [ { "thirdQuartile": 0, "uniques": 1, "name": "RJ Test", "stream": "w7ed5k3guquv", "sessions": 6, "disconnections": 6, "midpoint": 0, "firstQuartile": 0, "connections": 6, "start": 0, "traffic": 0.0027672136202454567, "duration": 181, "impressions": 0, "requests": 0, "complete": 0 },... ], "uniques": 4913, "disconnected": 13319, "thirdQuartile": 9101, "midpoint": 9209, "connections": 13426, "start": 9348, "connected": 13326, "impressions": 9348, "firstQuartile": 9325, "kilobytes": 611.1920091476768, "requests": 16041, "listening_time": 23873529, "complete": 9098 }, "day": "2019-02-03" },... ] } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
account_key (required) | The account key to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
Include_outputs | Whether to include relays [true/false] |
include_vast | Whether to include vast [true/false] |
Account Regional stats
Example request: GET /api/accounts/<account_key>/stats/regional?&from_date=2019-03-18&to_date=2019-03-21&include_vast=true&include_outputs=false HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "start": "2019-02-10", "country_stats": [ "country_name": "Canada", "cities": [ { "city": "Toronto", "stats": { "thirdQuartile": 5, "uniques": 1, "complete": 5, "midpoint": 5, "start": 5, "connected": 3, "impressions": 5, "firstQuartile": 5, "kilobytes": 67053392, "requests": 6, "listening_time": 2077 } },... ] "stats": { "thirdQuartile": 595, "uniques": 461, "complete": 595, "midpoint": 606, "start": 614, "connected": 1424, "kilobytes": 110148023179, "firstQuartile": 614, "impressions": 614, "requests": 1156, "listening_time": 4152839 }, "country_code": "CA" },... ], "end": "2019-02-10" } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
account_key (required) | The account key to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
Include_outputs | Whether to include relays [true/false] |
include_vast | Whether to include vast [true/false] |
Account Live stats
Example request: GET /api/accounts/<account_key>/stats/live HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "data": [ { "country_name": "Canada", "count": 5, "cities": [ { "count": 3, "city": "Toronto" }, { "count": 1, "city": "Burnaby" }, { "count": 1, "city": "Laval" } ], "country_code": "CA" },... ] }
|
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
account_key (required) | The account key to display stats |
Account Device stats
Example request: GET /api/accounts/<account_key>/stats/device?from_date=2019-02-10&to_date=2019-02-10 HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "start": "2019-02-10", "device_stats": [ { "device": "Android", "stats": { "cnt": 1523, "avg_duration": 685.4057780695995 } },... ], "end": "2019-02-10" } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
account_key (required) | The account key to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
Station Stats
Station Day Stats
Example request: GET /api/stations/<stream_name>/stats/day_stats?date=2019-02-13&include_vast=true&include_outputs=true HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "hour_stats": [ { "stats": { "streams": [ { "thirdQuartile": 0, "uniques": 1, "name": "RJ Rock", "stream": "6ktreun4crtuv", "sessions": 1, "disconnections": 1, "duration": 30, "midpoint": 0, "connections": 1, "start": 0, "traffic": 0.00046211108565330505, "firstQuartile": 0, "impressions": 0, "requests": 0, "complete": 0 },... ], "thirdQuartile": 0, "uniques": 114, "disconnected": 1911, "midpoint": 0, "kilobytes": 3.4185329621398166, "connections": 231, "start": 0, "impressions": 0, "firstQuartile": 0, "connected": 188, "requests": 0, "listening_time": 151767, "complete": 0 }, "hour": 0 },... ], "date": "2019-02-13" } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream name to display stats |
date (required) | Day to which the Hour stats should appear in the format YYYY-MM-DD |
Include_vast | Whether to include logs from Vast Reports [true/false] |
Include_outputs | Whether to include relays [true/false] |
include_vast | Whether to include vast [true/false] |
Station Period Stats
Example request: GET /api/stations/<strem_name>/stats/period?from_date=2019-02-03&to_date=2019-02-09&include_vast=true&include_outputs=true HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "start": "2019-02-03", "end": "2019-02-09", "period_stats": [ "stats": { "thirdQuartile": 0, "uniques": 2, "disconnected": 7, "midpoint": 0, "kilobytes": 0.003237971104681492, "connections": 7, "start": 0, "impressions": 0, "firstQuartile": 0, "connected": 7, "requests": 0, "listening_time": 205, "complete": 0, "streams": [ { "thirdQuartile": 0, "uniques": 2, "name": "RJ Rock", "stream": "4ktrjumn1cuquv", "sessions": 7, "disconnections": 7, "duration": 205, "midpoint": 0, "connections": 7, "start": 0, "traffic": 0.003237971104681492, "firstQuartile": 0, "impressions": 0, "requests": 0, "complete": 0 },... ], "listening_time": 5218128 }, "day": "2019-02-03" },... ] } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream_name to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
Include_vast | Whether to include logs from Vast Reports [true/false] |
Include_outputs | Whether to include relays [true/false] |
include_vast | Whether to include vast [true/false] |
Station Regional stats
Example request: GET /api/stations/<stream_name>/stats/regional?&from_date=2019-03-20&to_date=2019-03-20&include_vast=true HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "start": "2019-02-10", "country_stats": [ "country_name": "Canada", "cities": [ { "city": "Toronto", "stats": { "thirdQuartile": 0, "uniques": 1, "complete": 0, "midpoint": 0, "start": 0, "connected": 6, "impressions": 0, "firstQuartile": 0, "kilobytes": 3053194, "requests": 0, "listening_time": 180 } },... ] "stats": { "thirdQuartile": 0, "uniques": 1, "complete": 0, "midpoint": 0, "start": 0, "connected": 6, "kilobytes": 3053194, "firstQuartile": 0, "impressions": 0, "requests": 0, "listening_time": 180 }, "country_code": "CA" },... ], "end": "2019-02-10" } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream_name to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
include_vast | Whether to include vast [true/false] |
Station Live stats
Example request: GET /api/stations/<stream_name>/stats/live HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "data": [ { "country_name": "Canada", "count": 5, "cities": [ { "count": 3, "city": "Toronto" },... ], "country_code": "CA" },... ] }
|
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream_name to display stats |
Station Device stats
Example request: GET /api/accounts/<stream_name>/stats/device?from_date=2019-02-10&to_date=2019-02-10 HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "start": "2019-02-10", "device_stats": [ { "device": "Android", "stats": { "cnt": 1523, "avg_duration": 685.4057780695995 } },... ], "end": "2019-02-10" } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream_name to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
Station Tracks
Example request: GET /api/stations/<stream_name>/tracks/?from_date=2019-02-09T22:03:00&to_date=2019-02-10T22:00:00 HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json [ { "album": null, "duration": 3669, "tm": "2019-02-09T22:20:00", "tm_end": "2019-02-09T23:21:00", "artist": "MG Sreekumar", "track": "Thaamara Poovil", "guid": null, "thumb": null },... ] |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream name to display stats |
from_date (required) | format: YYYY-MM-DDTHH:mm:ss |
to_date (required) | format: YYYY-MM-DDTHH:mm:ss |
Station Track Report
Example request: GET /api/stations/<stream_name>/track_report/?from_date=2019-02-01&to_date=2019-02-28 HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript Example response: Http/1.1 200 OK Content-Type: application/json { "0": { "album": null, "play_count": 6, "title": "Enthanee Mounam", "artist": "Karthik & Sharon Joseph" },... } |
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Request Parameters | Description |
stream_name(required) | The stream name to display stats |
from_date (required) | in the format YYYY-MM-DD |
to_date (required) | in the format YYYY-MM-DD |
Station Now Playing information
Example request: GET /api/stations/<stream_name>/now_playing/
HTTP/1.1 Host: <portal-url> Accept: application/json, text/javascript
Example response: Http/1.1 200 OK Content-Type: application/json
{ album: null, sku: "", thumb: "", artist: "Lil Baby / Drake", title: " Yes Indeed", show: { }, buy_urls: "", info_urls: "", duration: "0", guid: null }
|
Request Headers | Description |
x-auth-token (required) | Token provided by RCS Greece |
Important note: Only the Title & Artist are received from the encoders and returned from this API.