--- title: "SwitchBot APIとは？できること・使い方とハブが必要な仕組み【v1.1対応】" url: "https://www.issoh.co.jp/tech/details/3342/" published: 2024-08-19 updated: 2026-09-26 categories: ["API"] publisher: "株式会社一創" --- # SwitchBot APIとは？できること・使い方とハブが必要な仕組み【v1.1対応】 SwitchBot APIは、SwitchBotアプリに登録した機器をHTTPで操作・取得するための公式クラウドAPIです。現行版はv1.1で、エンドポイントは `https://api.switch-bot.com/v1.1`、認証はアプリで発行するトークンとシークレットから作る署名で行います。この記事では、APIでできることの範囲、ボットやカーテンなどBluetooth機器を外から動かせる仕組みとハブの要否、トークンの取得からPythonでの呼び出しまでを、公式ドキュメントの記述に沿って整理します。 ## まとめ：SwitchBot API v1.1の要点 - できるのは「デバイス一覧の取得」「状態の取得」「コマンド送信」「手動シーンの実行」「Webhookでのイベント受信」の5種類。 - 認証はトークン＋13桁のミリ秒タイムスタンプ＋nonce（UUID）をシークレットでHMAC-SHA256し、Base64にした値を `sign` ヘッダーで送る。旧v1.0の「トークンだけ」の方式は新製品に対応しない。 - ボット・カーテン・ロック・温湿度計などBluetooth機器はハブ経由でクラウドにつながる。Wi-Fi内蔵機器はハブ不要で、APIの `hubDeviceId` が `000000000000` になる。 - 呼び出し上限は1日10,000回で、超えると「Unauthorized」が返る。個人利用は申請不要だが、商用利用や大規模な呼び出しは事前連絡が必要。 - センサー値を頻繁に見たいならポーリングよりWebhook。ネットを経由したくないならBLEの公開仕様やHome Assistantでローカル制御する。 以下、仕組み→準備→コード→運用上の制限の順に説明します。 ## SwitchBot APIでできること：5つの機能とエンドポイント [公式README（OpenWonderLabs/SwitchBotAPI）](https://github.com/OpenWonderLabs/SwitchBotAPI)が定義している機能は次の5系統です。パスはすべて `https://api.switch-bot.com` からの相対です。 | 機能 | メソッドとパス | 用途の例 | | -------- | ---------------------------------------------------- | ------------- | | デバイス一覧 | GET /v1.1/devices | deviceIdの確認 | | 状態取得 | GET /v1.1/devices/{deviceId}/status | 室温・湿度・電池残量 | | コマンド送信 | POST /v1.1/devices/{deviceId}/commands | ボットON、エアコン26度 | | シーン一覧・実行 | GET /v1.1/scenes、POST /v1.1/scenes/{sceneId}/execute | 「外出」シーンの起動 | | Webhook | POST /v1.1/webhook/setupWebhook ほか | 開閉・温度変化の通知 | デバイス一覧は、実機の `deviceList` と、ハブに登録した赤外線リモコンの `infraredRemoteList` の2本で返ります。赤外線リモコンにもコマンドを送れるため、SwitchBot製でないエアコンやテレビも操作対象になります。エアコンなら `setAll` コマンドに `26,1,3,on`（温度・モード・風量・電源）を渡す形式です。アプリで作った「カスタムボタン」は `commandType` を `customize` にし、ボタン名をそのまま `command` に入れて押せます。 シーンはAPIから作成・編集できず、アプリで作った**手動シーンの一覧取得と実行だけ**ができます。複数機器をまとめて動かす処理はアプリ側でシーンにしておき、APIからは `sceneId` を叩くだけにすると、呼び出し回数も1回で済みます。 ## SwitchBotの遠隔操作の仕組みとハブが必要な機器 ### Bluetooth機器が外出先から動く経路 ボット、カーテン、ロック、温湿度計、開閉センサーなどは、本体がBluetooth（BLE）しか持っていません。スマホが近くにあればアプリから直接動かせますが、家の外からは届きません。そこでハブ（Hub Mini、Hub 2、Hub 3など）がBLEで機器とつながり、2.4GHzのWi-Fi経由でSwitchBotのクラウドと通信します。外出先のアプリやAPIの命令は「クラウド→ハブ→BLE→機器」の順に届きます。 BLE機器をクラウドAPIから扱うには、同じアカウントにハブを追加し、そのBluetooth通信範囲内に機器を置きます。公式サポートの「[ハブ製品の役割](https://support.switch-bot.com/hc/ja/articles/7257579858455)」によると、アプリV9.0以降は自動的にネットワーク化され、クラウドサービスを手動で有効にする必要はありません。各ハブにつながっている機器の通信状況は「プロフィール→ハブを管理」で確認でき、「プロフィール→サードパーティーサービス」はAlexaなどとの連携を設定する画面です。ハブを置いたのに操作できないときは、デバイス一覧の `enableCloudService` が `true` かを最初に確認してください。 ### ハブ不要のWi-Fi機器とhubDeviceIdでの見分け方 プラグミニ、カラー電球、テープライト、加湿器など、Wi-Fiを内蔵した機器は自分でクラウドに接続するため、ハブが無くてもAPIで操作できます。手元の機器がどちらかは、デバイス一覧の `hubDeviceId` で判別できます。デバイス別ドキュメントは、この値が「機器自体がハブの場合、またはWi-Fi接続の場合は `000000000000`」になると定義しています。全桁が0の値を除き、ハブのIDが入っていれば、そのハブを経由する機器として判別できます。 ハブ経由の機器では、ハブの電源やWi-Fiが落ちるとコマンドがエラーコード171（hub device is offline）で失敗します。機器本体の電池切れやBLEの圏外は161（device offline）です。障害時にどちらを疑うかがコードで分かれるため、ログにはstatusCodeを残しておくと切り分けが早くなります。 ### 赤外線家電の操作に必要なハブ 赤外線リモコンの仮想デバイスを作れるのは、READMEによるとHub Plus、Hub Mini、Hub 2、Hub 3、シーリングライトです。ただし、公式サポートはシーリングライトに赤外線リモコン登録機能がないと明記しており、READMEと記述が食い違います。赤外線家電の操作用には、登録機能を備えたHub Mini、Hub 2、Hub 3などを選んでください。2025年11月発売のAIハブ（W8002100）も、同じサポート記事で赤外線リモコンの登録機能が無いと案内されているため、エアコンやテレビをAPIで操作したい場合は赤外線対応ハブを併用します。AIハブをAIエージェントから操作する構成は「[SwitchBot AIハブ×OpenClawとは？チャット操作型スマートホームの全体像と料金・設定](/tech/details/11134/)」で扱っています。 ## トークンとシークレットの取得手順 SwitchBotサポートの「[トークンの取得方法](https://support.switch-bot.com/hc/ja/articles/12822710195351)」（アプリV6.24以降が対象）では、次の手順が案内されています。 1. SwitchBotアプリを起動し、プロフィール→設定→基本データ→アプリバージョンまで進む。 2. アプリバージョンの表示を5〜15回連続でタップすると「開発者向けオプション」が現れる。 3. 「開発者向けオプション」を開くと、トークンとクライアントシークレットが表示される。 メニュー名はアプリの版で変わっており、READMEの英語手順では「Profile > Preferences > About」、タップ回数は10回と書かれています。表示されない場合は、アプリを最新にしてから回数を変えて試してください。 トークンを作り直したいときは、アプリからログアウトして再ログインします。サポート記事は「再度ログインすると、トークンが自動的に更新され、有効期限は約1時間となります」と記載しています。再ログイン後はプログラム側の値を新しいトークンとシークレットに差し替えてください。 トークンとシークレットが漏れると、アカウント内のAPI対応機器に対し、ロックの解錠などの対応コマンドを第三者が実行できるおそれがあります。ソースコードに直書きせず環境変数やシークレット管理に置き、漏えいを疑ったら再ログインで作り直すのが最低限の対策です。 ## Pythonでの使い方：署名生成からデバイス操作まで ### v1.1の署名の作り方 v1.1では、すべてのリクエストに次の4つのヘッダーが必要です。 | ヘッダー | 中身 | | ------------- | ----------------- | | Authorization | アプリで取得したトークン | | t | 13桁のミリ秒タイムスタンプ | | nonce | リクエストごとのランダムなUUID | | sign | 署名（下記の手順で生成） | 署名は「トークン＋t＋nonce」をこの順に連結した文字列を、シークレットを鍵にHMAC-SHA256で計算し、Base64にしたものです。v1.0向けのトークンだけで認証するコードをv1.1のエンドポイントへ流用する場合は、署名・タイムスタンプ・nonceを含む認証処理への変更が必要です。 公式READMEには表記の食い違いが1つあります。手順の説明は「署名を大文字に変換する」としていますが、同じページのサンプルコードのうち大文字化しているのはPHPとGoだけで、Python・JavaScriptは大文字化していません。以下のコードはPython版の公式サンプルと同じく大文字化しない形にしています。 ### デバイス一覧・状態取得・操作のPythonコード 標準ライブラリだけを使う最小構成です。Python 3.9での確認範囲は、ダミー認証情報によるHTTP 401応答の受信と署名計算の照合までで、有効な認証情報による一覧取得・状態取得・実機操作は未検証です。 ``` import base64 import hashlib import hmac import json import os import time import urllib.error import urllib.request import uuid TOKEN = os.environ["SWITCHBOT_TOKEN"] SECRET = os.environ["SWITCHBOT_SECRET"] BASE = "https://api.switch-bot.com/v1.1" def headers(): t = str(int(time.time() * 1000)) # 13桁のミリ秒 nonce = str(uuid.uuid4()) string_to_sign = TOKEN + t + nonce sign = base64.b64encode( hmac.new(SECRET.encode(), string_to_sign.encode(), hashlib.sha256).digest() ).decode() return { "Authorization": TOKEN, "sign": sign, "t": t, "nonce": nonce, "Content-Type": "application/json; charset=utf8", } def call(method, path, body=None): data = json.dumps(body).encode() if body is not None else None req = urllib.request.Request(BASE + path, data=data, headers=headers(), method=method) try: with urllib.request.urlopen(req, timeout=10) as res: return json.load(res) except urllib.error.HTTPError as e: return {"http_status": e.code, "body": e.read().decode()} if __name__ == "__main__": devices = call("GET", "/devices") print(json.dumps(devices, ensure_ascii=False, indent=2)) # 例: 温湿度計の状態取得 / ボットをオン # print(call("GET", "/devices//status")) # print(call("POST", "/devices//commands", # {"command": "turnOn", "parameter": "default", "commandType": "command"})) ``` 環境変数 `SWITCHBOT_TOKEN` と `SWITCHBOT_SECRET` を設定して実行すると、デバイス一覧がJSONで表示されます。温湿度計（deviceTypeがMeter）の状態取得では `temperature`（摂氏）、`humidity`、`battery` が返り、電池残量は10・20・60・100の4段階で返り、実際の残量を1％刻みで示す値ではありません。ほかの機種やWebhookの値は、機種別仕様を確認してください。 ボットのコマンドは `turnOn`・`turnOff`・`press` の3つです。アプリでボットを「押すモード」にしている場合は `press` を送ります。 ### 401とエラーコードの切り分け 応答のHTTPステータスが200でも、本文の `statusCode` が100以外なら失敗です。READMEが定義する主なコードは次のとおりです。 | コード | 意味 | 確認する点 | | ---------------- | ------------------------ | ------------- | | 401 Unauthorized | 認証失敗 | 署名・t・上限超過 | | 151 | device type error | コマンドと機種の組み合わせ | | 152 | device not found | deviceIdの誤り | | 160 | command is not supported | 機種別docsのコマンド名 | | 161 | device offline | 機器の電池・BLE圏内 | | 171 | hub device is offline | ハブの電源・Wi-Fi | | 190 | 内部エラー・形式不正 | parameterの書式 | 401は署名の誤りだけでなく、1日の上限超過でも返ります。コードを変えていないのに夕方から401が出始めたら、署名ではなく呼び出し回数を疑ってください。署名が原因の場合は、`t` が秒単位（10桁）になっていないか、連結順が「トークン＋t＋nonce」になっているかを先に確認します。 ## Webhookでセンサーやロックの変化を受け取る設定 Webhookを使うと、対応機器のイベントが発生したときにSwitchBot側から指定URLへJSONがPOSTされます。次の例は、前節のcall関数を定義したファイルに追加し、URLを自分の受信先に置き換えて実行します。これは通知先の登録コードであり、JSONを受信するサーバー処理は別途必要です。 ``` print(call("POST", "/webhook/setupWebhook", { "action": "setupWebhook", "url": "https://example.com/switchbot-webhook", "deviceList": "ALL", })) ``` `deviceList` は現在 `"ALL"` しか指定できず、登録した全機器のイベントが1つのURLに届きます。受信側では `context.deviceType`（ボットなら `WoHand`、カーテンなら `WoCurtain`）と `deviceMac` で振り分けます。イベントは `eventType` が `changeReport` の形式で、ボットなら電源状態とモード、カーテンなら位置を表す `slidePosition`（0が全開、100が全閉）が入ります。 設定の確認は `/v1.1/webhook/queryWebhook`、変更は `updateWebhook`、削除は `deleteWebhook` です。READMEの対応表ではロック、キーパッド、カーテン、温湿度計、Hub 2・Hub 3など多くの機器がWebhookに対応していますが、ブラインドポールのように非対応の機種もあります。使う前に対応表の「Webhook」列を確認してください。受信URLはインターネットから到達できる必要があるため、自宅サーバーで受けるならトンネルやリバースプロキシを用意します。 ## 1日1万回の上限と商用利用の制限 READMEは呼び出し回数を1日10,000回に制限しています。定期取得（ポーリング）で使うと、この上限には意外と早く届きます。 - 1分ごとに状態を取ると、1台で1日1,440回。7台で10,080回となり上限を超える。 - 5分ごとなら1台288回。34台までは収まる。 温湿度のグラフ化のように変化を追うだけなら、ポーリングの間隔を5分以上にするか、Webhookに切り替えるのが現実的です。ボタン操作のように人がきっかけの呼び出しなら、上限を気にする必要はほとんどありません。 もう1つの制約が用途です。READMEは、このAPIを個人利用に限り、商用利用と大規模な利用を禁止しています。日本向けの注記では、個人のプロジェクトや学習研究は追加申請なしで使える一方、商業製品・サービスへの組み込みや数千回以上の大規模な呼び出しは事前連絡のうえ別途のEnterprise APIを使うよう案内しています。**入居者向けサービスや店舗の複数拠点管理など、他人の機器をまとめて扱うシステムを個人向けAPIで作るべきではありません。**規約違反になるうえ、1アカウント1日1万回の上限で運用が止まります。 個人向けAPIのREADMEには利用料金の記載がありません。料金条件を確定する必要がある場合は、SwitchBotに確認してください。SwitchBotが2026年4月に始めた月額制のAIエージェントプランはAPIとは別サービスで、料金と自前APIキー方式との違いは「[SwitchBot AIエージェントプランの料金・導入手順｜自前APIキー方式との違い](/tech/details/11989/)」で比較しています。 ## クラウドを通さないローカル制御の選択肢 SwitchBot APIはクラウド経由なので、インターネット回線やSwitchBotのサーバーが止まると使えません。応答速度や障害時の動作を重視するなら、次のローカル制御も検討できます。 - **BLEの公開仕様**：OpenWonderLabs/SwitchBotAPI-BLEが、ボット、温湿度計、カーテン、ロック、プラグミニなどのBLE通信仕様を公開している。Raspberry PiなどBluetoothを持つ端末から、ハブもクラウドも使わずに直接制御できる。 - **Home Assistant**：公式統合が2つあり、「SwitchBot Bluetooth」はPySwitchbot（2.9.0）でローカルに通信し、「SwitchBot Cloud」はクラウドAPIを使う。両方を併用し、BLEが届く機器はローカルで扱う構成が組める。 BLEは電波の届く範囲でしか通信できないため、部屋の離れた機器までローカルで扱うにはBluetooth端末を複数置く必要があります。外出先からの操作が主目的なら、クラウドAPIとハブの組み合わせのほうが手間は少なく済みます。ラズパイでの自作構成は「[ラズパイでスマートホームを自作する方法｜構成の選び方とPi 5世代のGPIO変更点](/tech/details/1926/)」、ノーコードでAPIをつなぐなら「[Node-RED（ノードレッド）とは？できること・使い方・商用利用の可否と料金をわかりやすく解説](/tech/details/4815/)」も参考になります。 ## よくある質問 ### SwitchBot APIの制限は？ 1日10,000回までで、超えると「Unauthorized」が返ります。また個人利用が前提で、商用利用や大規模な呼び出しはSwitchBotへの事前連絡が必要です。 ### SwitchBot APIは有料ですか？ 個人向けAPIのREADMEには利用料金の記載がありません。追加費用の有無を確定する必要がある場合は、SwitchBotに確認してください。月額制のAIエージェントプランはAPIとは別のサービスです。 ### ハブが無くてもSwitchBot APIは使えますか？ プラグミニやカラー電球などWi-Fi内蔵機器は使えます。ボット・カーテン・ロック・温湿度計などBluetoothのみの機器と、赤外線家電の操作にはハブが必要です。 ### v1.0のAPIはまだ使えますか？ 公式ブログは2022年9月27日のv1.1公開時に、v1.0は引き続き使えるが新製品への対応を停止すると告知しています。ロックやキーパッドなど新しい機器を扱うならv1.1で実装してください。 ### SwitchBotはPython以外の言語でも操作できますか？ HTTPで呼べる言語なら操作できます。公式READMEにはPython、JavaScript、C#、Java、PHP、Swift、Goの署名生成サンプルが載っています。 ## 関連記事 - [SwitchBot AIエージェントプランの料金・導入手順｜自前APIキー方式との違い](/tech/details/11989/) - [SwitchBot AIハブ×OpenClawとは？チャット操作型スマートホームの全体像と料金・設定](/tech/details/11134/) - [ラズパイでスマートホームを自作する方法｜構成の選び方とPi 5世代のGPIO変更点](/tech/details/1926/) - [Node-RED（ノードレッド）とは？できること・使い方・商用利用の可否と料金をわかりやすく解説](/tech/details/4815/) --- 出典: [SwitchBot APIとは？できること・使い方とハブが必要な仕組み【v1.1対応】]()（株式会社一創）