API 連携をはじめる

YuCon API を使うと、入退場カウンターなどの計測機器や施設の自社システムから、混雑度を自動で更新できます。管理画面から手動で更新する代わりに、機器が計測した値を定期送信する運用に切り替えられます。

施設の代表混雑度と、サブ設備 (男湯 / 女湯 / サウナなど) 単位の両方を更新できます
更新はリアルタイム配信・混雑履歴・混雑予測にそのまま反映されます
認証は API トークン 1 つだけ。署名や OAuth などの複雑な実装は不要です

機械可読な API 仕様 (OpenAPI 3.1) は openapi.yaml で公開しています。コード生成ツールにそのまま読み込めます。

1. API トークンを発行する

管理画面にログインし、対象施設の設定を開きます
「外部連携 (API)」セクションで「API トークンを発行」を押します
機器名 / 用途 に、更新履歴で識別できる名前を入力します (例: 入口カウンター)
対象サブ設備 を選びます
- 代表のみ: 施設の代表混雑度だけを更新する機器はこちら
- すべてのサブ設備: サブ設備単位で更新する機器はこちら
発行時に再認証 (パスキーまたはパスワード) が求められます

発行されたトークン (yucon_api_ で始まる文字列) はこのとき一度だけ表示されます。機器に設定し、安全な場所に保管してください。

2. 疎通を確認する

発行画面に表示される curl コマンドで、トークンが機能するか確認できます。

curl "https://api.yucon.info/v1/facilities/施設ID" \
  -H "Authorization: Bearer 発行したトークン"

成功すると、施設の現在状態が返ります。

{
  "success": true,
  "data": {
    "facilityId": "...",
    "name": "サンプル温泉",
    "congestionScale": 3,
    "currentLevel": 2,
    "openState": "open",
    "token": { "label": "入口カウンター", "permissions": ["update_congestion"], "subScope": "primary" },
    "subFacilities": [
      { "subFacilityId": "...", "name": "大浴場", "congestionScale": 3, "currentLevel": 2, "isPrimary": true }
    ]
  }
}

機器の起動時にこのエンドポイントを呼ぶと、混雑度の段階数 (congestionScale) やサブ設備の ID を機器側に固定で書き込まずに済みます。

3. 混雑度を送信する

curl -X PUT "https://api.yucon.info/v1/facilities/施設ID/congestion" \
  -H "Authorization: Bearer 発行したトークン" \
  -H "Content-Type: application/json" \
  -d '{"level": 2}'

level は 1 (空いている) 〜段階数 (混雑) の整数です。送信間隔は 60 秒以上を推奨します。

各エンドポイントの詳細は API リファレンス、機器実装の指針は実装ガイドを参照してください。