Skip to content

Statistics Synchronization API

Jump to bottom
KueiHua edited this page Jul 13, 2020 · 19 revisions

The Statistics Sync REST APIs provide data synchronization of media statistics from StraaS to your site.

Table of Contents

Definitions

Term Description
hit_count Number of times the media (Live or VOD) hit
hit_uu Number of distinct users who ever loaded the media (Live or VOD) hit
play_count Number of times the media (Live or VOD) played
play_uu Number of distinct users who ever played the media (Live or VOD)
play_duration Total play time of the media (Live or VOD) in seconds
broadcasting hour The duration that some broadcasters have created live streaming for how much time

Concept

Straas writes change records with monotonic increasing index when new statistics are generated. In each synchronization round, you calls sync API to retrieve changes larger than your last seen index with ascending order repeatedly until no more changes.

For example, assume your last seen index is 5 (i.e. statistics with index 0 ~ 4 already persisted in your database), you could sync data in following steps:

  1. Call sync API with index 5, Straas returns changes with index 16, 27 and 38
  2. Call sync API again with 38 (last seen), Straas returns changes with index 49, 70
  3. Call sync API again with 70 (last seen), Straas returns no more changes
  4. Sleep for a while (30 ~ 60 seconds are recommended) then repeat step 1

Note that each media_type uses different index, please store last seen index of different media_type separately. Note that returned index are in ascending order but NOT continuous number.

Authentication

These APIs are authenticated through an application token. Knowing how to create and get an application token please refer application token document.

APIs

Sync Live/VOD view count, view time and unique users

This API provides data synchronization of daily statistics of both Live and VOD.

Endpoint

GET https://app.straas.net/api/v1/app/sync/statistic

Request Headers

Field Required Description
Authorization O Bearer <application_token>
  • for more details about application token, refer to the document

Request Parameters

Field Required Description
media_type O must be "media"
update_index O the last seen index, use 0 for the first time
page_size X Number of results to return per page (100 ~ 3000), default is 1000
  • note that, you could only retrieve data within 10 days

Response

Field Type Description
next_index string update_index for next sync API requests
data array media statistics data. deduplication
[data.index] string id of the record
[data.time] string timestamp at the beginning of the day in RFC3339
[data.account] string user account
[data.media] string live ID or VOD ID
[data.mode] string media mode, "vod" or "live"
[data.hit_count] integer Number of times the media (Live or VOD) embedded page loaded
[data.hit_uu] integer Number of distinct users who ever loaded the media (Live or VOD) embedded page
[data.play_count] integer Number of times the media (Live or VOD) played
[data.play_uu] integer Number of distinct users who ever played the media (Live or VOD)
[data.play_duration] integer Total play time of the media (LIve or VOD) in seconds
  • deduplication
    • in order to get latest record from DB, we deduplicate those records by key (account, media, mode, time)
    • in this way, the response size would not be the same as input page_size

Remark

Item Description
Data point interval 1 Day
Update interval 15 minutes

Status

200

Example

curl -X GET \
  -H "Authorization: Bearer <application_token>" \
  "https://app.straas.net/api/v1/app/sync/statistic?media_type=media&update_index=3421&page_size=500"

Response:
{
  "next_index": "5678",
  "data": [
    {
      "index": "4000",
      "time": "2016-03-03T16:00:00.000Z",
      "account": "myaccount",
      "media": "dfojiDkfjlasdf9",
      "mode": "live",
      "hit_count": 210,
      "hit_uu": 110,
      "play_count": 130,
      "play_uu": 100,
      "play_duration": 560000
    },
    {
      "index": "4100",
      "time": "2016-03-03T16:00:00.000Z",
      "account": "myaccount",
      "media": "88iikkksdlfwD",
      "mode": "vod",
      "hit_count": 200,
      "hit_uu": 100,
      "play_count": "120",
      "play_uu": 90,
      "play_duration": 330000
    }
  ]
}

Sync Live/VOD Hit Count

This API provides data synchronization hit count of Live and VOD. Please note that hit count is accumulated data, NOT daily statistics.

Endpoint

GET https://app.straas.net/api/v1/app/sync/statistic

Request Headers

Field Required Description
Authorization O Bearer <application_token>
  • for more details about application token, refer to the document

Request Parameters

Field Required Description
media_type O must be "hit_count"
update_index O the last seen index, use 0 for the first time
page_size X Number of results to return per page (100 ~ 3000), default is 1000
  • note that, you could only retrieve data within 10 days

Response

Field Type Description
next_index string update_index for next sync API requests
data array media statistics data. deduplication
[data.index] string id of the record
[data.account] string user account
[data.media] string live ID or VOD ID
[data.mode] string media mode, "vod" or "live"
[data.value] integer number of page views
  • deduplication
    • in order to get latest record from DB, we deduplicate those records by key (account, media, mode)
    • in this way, the response size would not be the same as input page_size

Remark

Item Description
Data point interval N/A, hit count is accumulated data
Update interval 1 minutes

Status

200

Example

curl -X GET \
  -H "Authorization: Bearer <application_token>" \
  "https://app.straas.net/api/v1/app/sync/statistic?media_type=hit_count&update_index=3421&page_size=500"

Response:
{
  "next_index": "5678",
  "data": [
    {
      "index": "4000",
      "account": "myaccount",
      "media": "dfojiDkfjlasdf9",
      "mode": "live",
      "value": 100
    },
    {
      "index": "4100",
      "account": "myaccount",
      "media": "88iikkksdlfwD",
      "mode": "vod",
      "value": 200
    }
  ]
}

Sync Live concurrent users

This API provides data synchronization concurrent users of Live.

Endpoint

GET https://app.straas.net/api/v1/app/sync/statistic

Request Headers

Field Required Description
Authorization O Bearer <application_token>
  • for more details about application token, refer to the document

Request Parameters

Field Required Description
media_type O must be "ccu"
update_index O the last seen index, use 0 for the first time
page_size X Number of results to return per page (100 ~ 3000), default is 1000
  • note that, you could only retrieve data within 10 days

Response

Field Type Description
next_index string update_index for next sync API requests
data array media statistics data. without deduplication
[data.index] string id of the record
[data.time] string timestamp in RFC3339
[data.account] string user account
[data.media] string live ID or VOD ID
[data.value] integer number of page views

Remark

Item Description
Data point interval 1 minutes
Update interval 1 minutes

Status

200

Example

curl -X GET \
  -H "Authorization: Bearer <application_token>" \
  "https://app.straas.net/api/v1/app/sync/statistic?media_type=ccu&update_index=3421&page_size=500"

Response:
{
  "next_index": "5678",
  "data": [
    {
      "index": "4000",
      "time": "2016-03-03T16:01:00.000Z",
      "account": "myaccount",
      "media": "dfojiDkfjlasdf9",
      "value": 100
    },
    {
      "index": "4100",
      "time": "2016-03-03T16:08:00.000Z",
      "account": "myaccount",
      "media": "88iikkksdlfwD",
      "value": 200
    }
  ]
}

Sync Live Broadcasting Hour

This API provides data synchronization of live broadcasting duration

Endpoint

GET https://app.straas.net/api/v1/app/sync/broadcasting_hour

Request Headers

Field Required Description
Authorization O Bearer <application_token>
  • for more details about application token, refer to the document

Request Parameters

Field Required Description
update_index O the last seen index, use 0 for the first time
page_size X Number of results to return per page (1 ~ 1000), default is 100
  • note that, you could only retrieve data within 2 days

Response

Field Type Description
next_index string update_index for next sync API requests
data array media statistics data
[data.index] string id of the record
[data.account] string user account
[data.media] string live ID
[data.member] string custom defined id, e.g. email or other encoded id
[data.time] string timestamp in RFC3339
[data.duration] integer minute uint, the time that a live streaming has last for

Remark

Item Description
Data point interval 1 minutes
Update interval 1 minutes

Example

curl -X GET \
  -H "Authorization: Bearer <application_token>" \
  "https://app.straas.net/api/v1/app/sync/broadcasting_hour?update_index=3421&page_size=500"

Success Response (http status code 200)

{
  "next_index": "5678",
  "data": [
    {
      "index": "4000",
      "account": "myaccount",
      "media": "dfojiDkfjlasdf9",
      "member": "some_user",
      "time": "2019-04-17T16:00:00.000Z",
      "duration": 1
    },
    {
      "index": "4100",
      "account": "myaccount",
      "media": "dfojiDkfjlasdf9",
      "member": "some_user",
      "time": "2019-04-17T16:01:00.000Z",
      "duration": 1
    }
  ]
}

Error Response

Code Type Description
400 Bad Request missing required parameters
401 Unauthorized invalid app token
500 Internal Server Error

Get Playevent Download URLs

This API provides download urls of playevent logs

  • this feature is not enabled by default, contact us for acquiring permission

Endpoint

GET https://app.straas.net/api/v1/app/data/playevent/download_urls

Request Headers

Field Required Description
Authorization O Bearer <application_token>
  • for more details about application token, refer to the document

Request Parameters

Field Required Description
time O RFC3339 format in day unit(UTC+0), e.g. 2019-08-13T00:00:00Z
  • note that, you could only retrieve data within 180 days
  • the download urls of a day would be generated on next day 1AM(it depends on your required timezone, UTC+0 or UTC+8, it's UTC+0 by default, contact us for changing timezone)
    • e.g. in case UTC+0, the urls of 8/13 is generated on 8/14 01:00(UTC+0), the input time should be 2019-08-13T00:00:00Z
    • e.g. in case UTC+8, the urls of 8/13 is generated on 8/14 01:00(UTC+8), the input time should be 2019-08-12T16:00:00Z
  • the input time would be truncated to day unit time in required timezone
    • e.g. if your account uses UTC+8, an input time 2019-08-13T00:00:00Z would be truncated to day unit time of UTC+8. that is 2019-08-12T16:00:00Z

Response

Field Type Description
time string RFC3339 format in day unit(UTC+0)
download_urls array of string signed url of compressed file
it has one day expired time
it might contain more than two links, based on data size
if there doesn't have any data, it gets an empty array

Remark

Item Description
Update interval 1 day

Example

curl -X GET \
  -H "Authorization: Bearer <application_token>" \
  "https://app.straas.net/api/v1/app/data/playevent/download_urls?time=2019-08-13T00:00:00Z"

Success Response (http status code 200)

{
  "time": "2019-08-13T00:00:00Z",
  "download_urls": [
    "https://some-where/csv-0000.gz",
    "https://some-where/csv-0001.gz"
  ]
}
  • decompress the file, you would get csv file with following fields
Field Description
member_id
latitude geolocation data
longitude geolocation data
mode live or vod
media_id id of live or vod
event init: the player is loaded
start: the player starts to play
view: client watches video from start_time to end_time
end: the video is finished
start_time only has meaningful value in view event, 0 on others
end_time only has meaningful value in view event, 0 on others
ip
user_agent based on the device where member watches video
time_stamp RFC3339 format, UTC+0, the time that event happened at
session_id it would be changed after reloading player on browser or mobile device

Error Response

Code Type Description
400 Bad Request missing or invalid required parameters
401 Unauthorized invalid app token
500 Internal Server Error

Straas API Overview

Authentication

Register a member avatar in Straas

Video uploading

Sell your content

How to play a stream

Common Concept

Broadcasting

Messaging Service

Concept

SDK

Messaging Server-side APIs

Sample Code

API Document

Clone this wiki locally