トラフィックモードのデータはどれくらいリアルタイムですか？

Jiani Zeng

更新 2026年10月14日 07:24

概要

トラフィックモードには 2 つのライブチャネルがあります。通過ごとに送信される入退室イベントと、1 分単位の分解能で提供される在室人数です。この記事では、それぞれのデータがどの程度最新か、どこで読み取れるか、表示される値にどの補正がすでに適用されているかを説明します。

この記事の対象はトラフィックモードです。お使いのスペースにどちらが該当するか判断できるよう、下の表にはプレゼンスモードの測定項目も記載していますが、プレゼンスモードについては「プレゼンスモードの在室データの生成と集計の仕組み」で説明しています。

トラフィックベースの在室人数にドリフトが生じる理由と、キャリブレーションによる補正の仕組みについては、「トラフィックベースの在室人数のロジックと仕様」をご覧ください。

1. スペースで提供される測定項目の確認

Butlr のセンサーは 2 つのモードで動作し、モードによって数値の意味とデータの鮮度の両方が決まります。読み進める前に、下の表でお使いの測定項目をご確認ください。

トラフィックモードの在室人数はドアでのカウントを累積したものであるため、補正が行われます。プレゼンスモードの在室人数は直接カウントされるため、補正は不要です。そのため、この記事の以降の内容は表の最初の 3 行にのみ当てはまります。

測定項目	値の意味	適用される補正	データの鮮度	Reporting API	Webhook
`traffic`	ドアでの個々の入室・退室	なし	Webhook でリアルタイム	対応	`TRAFFIC`
`traffic_floor_occupancy` `traffic_room_occupancy`	入室数から退室数を引いた値（営業日を通じて累積）	継続的な補正、および 1 日の終了時の補正	ライブ（1 分単位の分解能）	対応	なし
`traffic_room_occupancy` + PIR （Room レベルのみ）	上記と同じ（Room レベル）	継続的な補正、1 日の終了時の補正、および日中の PIR リセット	ライブ（1 分単位の分解能）。PIR リセットは空室確認の待機時間の経過後に反映（§4）	対応	なし
`floor_occupancy` `room_occupancy` `zone_occupancy`	累積ではなく、スペース内の人数を直接カウントした値	なし	Webhook でリアルタイム	対応	`FLOOR_OCCUPANCY`

2. 「ライブ」の意味

トラフィックモードには 2 つのライブチャネルがあり、それぞれ最新性の意味が異なります。

在室人数は 1 分単位の分解能でライブ提供されます。読み取れる最新の値は、直前に終了した 1 分間の値です。バッチ処理の待ち時間や 1 日の終わりまでの待機はなく、センサーから報告値までの間に追加の処理遅延もありません。

入退室イベントは通過ごとにライブ提供されます。TRAFFIC Webhook は、入室や退室が発生するたびに、集計ウィンドウを一切挟まずに 1 件ずつ送信します。1 分を待たずにシグナルを受け取る必要がある場合は、このチャネルをご利用ください。同じイベントは、Reporting API で measurement traffic を指定して過去分を取得することもできます。

在室人数の再計算ではなく、人の流れの把握に通過イベントを使用

Webhook で送信されるのは入室と退室のイベントで、在室人数は含まれません。また、生の通過イベントと報告される人数の間には補正が入るため、受信側で通過イベントを合算しても、API が報告する在室人数は再現できません。通過イベントは、方向別の人の流れ、ドア単位の通行量、イベントごとのトリガーに使用し、在室人数は Reporting API から読み取ってください（§3）。

ネットワーク環境

API の外側にある変動要因が 1 つあります。センサーはサイトのネットワーク経由でデータを送信するため、接続が弱い場合や混雑している場合は、どちらのチャネルでも値が届くまでに時間がかかることがあります。その場合の遅延は、レポーティングのパイプラインではなく、現地のネットワーク接続に起因するものです。

3. API からのライブ在室人数の読み取り

在室人数は 1 回のリクエストで直接取得できます。受信側で何かを累積する必要はありません（§2）。

POST https://api.butlr.io/api/v3/reporting
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
  "group_by": { "order": ["time"] },
  "window": {
    "every": "1m",
    "function": "median",
    "timezone": "<YOUR_TIMEZONE>"
  },
  "options": { "format": "json" },
  "filter": {
    "start": "-10m",
    "measurements": ["traffic_floor_occupancy"],
    "spaces": { "eq": ["<SPACE_ID>"] },
    "calibrated": "true",
    "value": { "gte": 0 }
  }
}

レスポンスに含まれる最新のキーを読み取ります。その値が現在の在室人数です。

相対時間の指定に対応しており、呼び出した時点を基準に解決されるため、上記のリクエストはそのままでライブの値を返します。時刻の計算やタイムゾーンの処理は不要で、ポーリングのたびに再計算するものもありません。stop を省略すると、ウィンドウは現在時刻までとなります。

フロアには traffic_floor_occupancy、Room には traffic_room_occupancy を使用します。入室数と退室数を取得するには、Reporting API で measurement traffic を指定するか、TRAFFIC Webhook イベントを使用します。

4. 読み取った値に適用済みの補正

トラフィックから算出される在室人数には、2 段階の補正があります。ライブの値に適用済みなのは、このうち 1 段階目だけです。

継続的な補正：今読み取った値を含め、すべての値に適用されます。在室人数は 0 を下限とするため負の値になることはなく、人単位の整数に丸められます。基準点を必要とせず、リアルタイムで実行されます。

既知のアンカー時点での補正：アンカーとは、実際の人数がわかっている時点のことです。営業日の開始時と終了時は、すべてのスペースにとってのアンカーです。1 日の終了時の補正では、蓄積した誤差をその日の推移全体にさかのぼって補正します。スペースが空になるまで基準点が存在しないため、それより早く実行することはできません。

PIR Zeroing は、PIR センサーを備えた Room レベルのスペースに日中のアンカーを追加し、部屋が空になった時点で人数を 0 にリセットします。人が一時的に静止しているだけではなく本当に空であることを確認するため、空室確認の待機時間が設けられています。この待機時間はスペースごとに設定できます。推奨のデフォルト値は 300 秒（5 分）で、リセットは部屋が実際に空になってからその時間が経過した後に反映されます。影響を受けるのはリセットのみで、在室人数のデータは常に 1 分単位の分解能で提供されます。

プレゼンスモードの在室人数は直接測定されるため、補正の段階は一切ありません。

5. プラットフォームでの確認場所

Live / Today には、IN / OUT と混雑度が表示されます。推定在室人数（Estimated Occupancy）は、このビューの Options にある Show estimated occupancy トグルをオンにすると表示されます。

Historical（昨日以前）には、IN / OUT の傾向と、2 段階の補正がすべて適用された後の在室人数が表示されます。

このトグルが切り替えるのは表示のみです。ライブの在室人数は、プラットフォームの設定にかかわらず API から提供されます。

6. 「Estimated Occupancy」は予測値ではなく実際の人数

これは、スペース内にいる現在の実際の人数です。予測値でも、過去の平均値でも、混雑度のスコアでもありません。

「Estimated」（推定）という言葉は、値の確からしさではなく算出方法を表しています。トラフィックセンサーは入口で方向を区別してカウントするため、在室人数は営業日を通じて累積した入室数から退室数を引いた値になります。累積であるため、カウントされなかった通過はその後も持ち越されます。これを補正するのがキャリブレーションです。補正がどこまで及ぶか、どの程度の残差が想定されるかについては、「トラフィックベースの在室人数のロジックと仕様」をご覧ください。

重要なポイント

トラフィックから算出される在室人数は 1 分単位の分解能でライブ提供され、読み取れる最新の値は直前に終了した 1 分間の値です。
入退室イベントは TRAFFIC Webhook で通過ごとにライブ送信され、集計ウィンドウはありません。
在室人数は Reporting API から直接提供されます。通過イベントは人の流れの把握に使い、人数の再計算には使いません。
ライブのトラフィック値には継続的な補正が適用済みです。アンカーによる補正は日の区切りで反映され、PIR を備えたスペースでは日中にも反映されます。
PIR の空室確認の待機時間のデフォルト値は 300 秒で、スペースごとに設定できます。
「Estimated Occupancy」は予測ではなく、実際の人数です。
プレゼンスモードで運用しているスペースでは、在室人数は直接測定され、Webhook でリアルタイムに送信されます。詳しくは「プレゼンスモードの在室データの生成と集計の仕組み」をご覧ください。