🤖

SwitchBot APIでデバイスの情報を取得する方法

に公開
IoT
API
SwitchBot
tech

はじめに

SwitchBotシリーズのデバイスは、公式APIを通じてプログラムから操作したり、状態（温度・湿度など）を取得したりできます。

この記事では、SwitchBot APIを利用するための準備と、curlコマンドを使ってデバイス一覧や各デバイスの状態を取得する方法を記録します。

Step 1: APIキー（トークンとシークレット）の取得

APIを利用するには、認証に必要な「トークン」と「シークレット」を取得する必要があります。

  1. 開発者向けオプションを有効化する

    • スマートフォンのSwitchBotアプリを開き、「プロフィール」→「設定」画面に移動します。
    • 「アプリのバージョン」という項目を10回連続でタップします。
    • 成功すると「開発者向けオプション」というメニューが出現します。（まるでゲームの隠しコマンドのようです）

  2. APIキーを取得する

    • 「開発者向けオプション」メニューに入ると、「トークン」と「クライアントシークレット」が表示されます。これらがAPIの認証キーになります。

[!IMPORTANT]
トークンとシークレットは絶対に公開しないこと
これらの情報は、APIを通じてご自身のデバイスを操作できてしまうパスワードのようなものです。ブログやGitHubなどで誤って公開しないよう、厳重に管理してください。

Step 2: デバイス一覧を取得する

まず、アカウントに登録されているすべてのデバイス情報を取得してみましょう。

ターミナルで以下のcurlコマンドを実行します。<YOUR_TOKEN> の部分を、先ほど取得したご自身のトークンに置き換えてください。

curl --request GET 'https://api.switch-bot.com/v1.1/devices' \
  --header 'Authorization: <YOUR_TOKEN>'

成功すると、以下のようなJSON形式でデバイスの一覧が返ってきます。この中から、次に状態を取得したいデバイスの deviceId を見つけて控えておきます。

{
  "statusCode": 100,
  "body": {
    "deviceList": [
      {
        "deviceId": "D66D086FC8AB",
        "deviceName": "温湿度計プラス AB",
        "deviceType": "MeterPlus",
        "enableCloudService": true,
        "hubDeviceId": "FD087CB12D22"
      },
      {
        "deviceId": "FD087CB12D22",
        "deviceName": "ハブミニ 22",
        "deviceType": "Hub Mini",
        "hubDeviceId": "000000000000"
      }
    ],
    "infraredRemoteList": [
      {
        "deviceId": "VIRTUAL_DEVICE_ID_1",
        "deviceName": "テレビ",
        "remoteType": "TV",
        "hubDeviceId": "FD087CB12D22"
      },
      {
        "deviceId": "VIRTUAL_DEVICE_ID_2",
        "deviceName": "ライト",
        "remoteType": "DIY Light",
        "hubDeviceId": "FD087CB12D22"
      }
    ]
  },
  "message": "success"
}

Step 3: 特定のデバイスの状態を取得する

次に、特定のデバイス（ここでは温湿度計）の状態を取得します。

Step 2で控えた deviceId を使って、以下のコマンドを実行します。<YOUR_TOKEN> と <YOUR_DEVICE_ID> をご自身のものに置き換えてください。

curl --request GET 'https://api.switch-bot.com/v1.1/devices/<YOUR_DEVICE_ID>/status' \
  --header 'Authorization: <YOUR_TOKEN>' | jq .

jqコマンドについて
末尾の | jq . は、APIから返されたJSONデータを整形して見やすくするためのコマンドです。jqは別途インストールが必要なツールですが、APIの動作確認に非常に便利です。
インストールしていない場合は | jq . を付けずに実行してください。

成功すると、指定したデバイスの状態が返ってきます。

{
  "statusCode": 100,
  "body": {
    "deviceId": "D66D086FC8AB",
    "deviceType": "MeterPlus",
    "hubDeviceId": "FD087CB12D22",
    "humidity": 59,
    "temperature": 15.5,
    "version": "1.4",
    "battery": 95
  },
  "message": "success"
}

temperature（温度）と humidity（湿度）が取得できていることがわかります。

APIの利用制限

SwitchBot APIには、無料での利用に以下の制限があります。

  • 1日あたりのAPI呼び出し回数: 10,000回

個人が少し利用する分には十分な回数ですが、頻繁にデータを取得するプログラムを作成する際は、この制限を超えないように注意しましょう。

参考

GitHubで編集を提案

Discussion