ULIZA Video Analytics (Cloud) API 仕様書 (v2.2.1)

本書はULIZA Video Analytics (Cloud)が提供するAPI仕様について記述しています。ULIZA Video Analytics (Cloud)の管理画面の操作方法についてはULIZA Video Analytics (Cloud)ユーザーガイドを参照してください。

レスポンスの時間が長く、408 Request Timeoutが返却された場合は、データの取得期間および取得件数を小さくするか、時間をおいてからAPIを実行してください。

なお、本書に掲載しているコードサンプル(Request samples)は、具体的な実装例を示すことで開発者を支援することを目的としていますが、掲載しているコードがすべての環境において正常に動作することを保証するものではありませんまた、コードサンプル内で使用している関数やライブラリの安全性に関して、弊社は何ら責任を負うものではありません。

注意

本書に記述している API を利用するには、対応するオプション(「ULIZA FLEX II - マルチ WebAPI オプション」など)のご契約が必要となります。詳細については お問い合わせ ください。

CHANGELOG

バージョン 改版日 改版内容
v2.0.0 2022/06/27 初版
v2.1.0 2022/10/04 a. リアルタイムアクティブユーザー数取得API、およびアクティブユーザー数取得APIgroup_perパラメータにおいてcontent_nameの指定に対応
b. filtersパラメータのitemcontent_nameを追加
c. コンテンツ名別視聴データ取得API、およびコンテンツ名・ユーザーID別視聴データ取得APIを追加
d. 視聴履歴取得APIのレスポンスにcontent_name(コンテンツ名)を追加
v2.2.0 2022/12/01 a. アクティブユーザー数取得APIを追加し、既存のアクティブユーザー数取得APIは非サポートのAPIに変更
v2.2.1 2023/5/01 a. 時間帯別視聴データ取得APIgranularityパラメータにおいてweeklyの指定に対応
b. 視聴データ取得APIdimensionsパラメータにおいてweekの指定に対応

Authentication

特に断りのない限り、本書に記載されている全てのAPIに対するリクエストのAuthorizationヘッダに下記の形式で有効なAPI認証キーを含める必要があります。API認証キーの取得方法についてはULIZAプロダクトアカウントユーザーガイドを参照してください。リクエストに有効なAPI認証キーが含まれていない場合は、401 Unauthorizedが返却されます。

Authorization: Bearer <api-credential>

APILimits

特に断りのない限り、本書に記載されている全てのAPIに対して、ULIZAプロダクトアカウントごとに、下記のサービス利用制限が設けられます。制限を超えてAPIを実行した場合は、429 Too Many Requestsが返却されます。

サービス利用制限 制限値
1分あたりのWebAPI実行可能数 3
1ヶ月あたりのWebAPI実行可能数 50,000
同時WebAPI実行可能数 1

Realtime

リアルタイムデータ取得系APIについて以下に記述します。

リアルタイムアクティブユーザー数取得API

リアルタイムアクティブユーザー数を取得します。

query Parameters
start
string <yyyy-mm-dd hh:mm:ss>
Default: "現在から15分前の日時(日本時間)"

データを取得する期間の開始日を日本時間で指定します。1回のリクエストで取得できるデータの取得期間は最大で15分までです。

end
string <yyyy-mm-dd hh:mm:ss>
Default: "現在の日時(日本時間)"

データを取得する期間の終了日を日本時間で指定します。1回のリクエストで取得できるデータの取得期間は最大で15分までです。

sort
string
Default: "date_time|desc"

ソートする第1キーおよび方向(昇順ascまたは降順desc)を|で連結した文字列を指定します。使用可能なキー名は以下の通りです。

  • date_time:日時
group_per
string
Default: null

日時に加えて、結果を集計する際のグループを指定します。使用可能なグループ名は以下の通りです。例えば、content_titleを指定すると、日時、コンテンツタイトルごとのデータが取得できます。

  • content_name:コンテンツ名
  • content_title:コンテンツタイトル

Responses

Response Schema: application/json
Array of objects

アクティブユーザー数データ

truncated
boolean

返却されたデータが全件ではない(以降の行が存在する)か否か

Request samples

curl \
-H 'Authorization: Bearer <your-token>' \
'https://analytics-api.p.uliza.jp/v2/realtime/user-counts?start=2022-06-27 13:00:00&end=2022-06-27 13:05:00'

Response samples

Content type
application/json
{
  • "data":
    [
    ],
  • "truncated": true
}

UserCounts

視聴データ取得系APIについて以下に記述します。

アクティブユーザー数取得API【 deprecated in v2.2.0 】

非サポートのAPIです。現在使用されている場合、代替の アクティブユーザー数取得API を使用して下さい。

query Parameters
start
string <yyyy-mm-dd hh:mm:ss>
Default: "現在から6時間前の日時(日本時間)"

データを取得する期間の開始日を日本時間で指定します。1回のリクエストで取得できるデータの取得期間は最大で13か月までです。

end
string <yyyy-mm-dd hh:mm:ss>
Default: "現在の日時(日本時間)"

データを取得する期間の終了日を日本時間で指定します。1回のリクエストで取得できるデータの取得期間は最大で13か月までです。

limit
integer [ 1 .. 50000 ]
Default: 100

1回のリクエストで取得するデータの行数を指定します。

offset
integer >= 0
Default: 0

リクエスト時の指定によりソートされた結果の取得開始位置を指定します。

sort
string
Default: "date_time|asc"

ソートする第1キーおよび方向(昇順ascまたは降順desc)を|で連結した文字列を指定します。使用可能なキー名は以下の通りです。

  • date_time:日時
group_per
string
Default: null

日時に加えて、結果を集計する際のグループを指定します。使用可能なグループ名は以下の通りです。例えば、content_titleを指定すると、日時、コンテンツタイトルごとのデータが取得できます。

  • content_name:コンテンツ名
  • content_title:コンテンツタイトル

Responses

Response Schema: application/json
Array of objects

アクティブユーザー数データ

truncated
boolean

返却されたデータが全件ではない(以降の行が存在する)か否か

Request samples

curl \
-H 'Authorization: Bearer <your-token>' \
'https://analytics-api.p.uliza.jp/v2/user-counts/data?start=2022-06-27 00:00:00&end=2022-06-27 23:59:59'

Response samples

Content type
application/json
{
  • "data":
    [
    ],
  • "truncated": true
}

ActiveUsers

視聴データ取得系APIについて以下に記述します。

アクティブユーザー数取得API

アクティブユーザー数を取得します。

query Parameters
start
string <yyyy-mm-dd hh:mm:ss>
Default: "本日から30日前の00時00分00秒(日本時間)"

データを取得する期間の開始日を日本時間で指定します。1回のリクエストで取得できるデータの取得期間は最大で13か月までです。

end
string <yyyy-mm-dd hh:mm:ss>
Default: "現在の日時(日本時間)"

データを取得する期間の終了日を日本時間で指定します。1回のリクエストで取得できるデータの取得期間は最大で13か月までです。

limit
integer [ 1 .. 50000 ]
Default: 100

1回のリクエストで取得するデータの行数を指定します。