kWhデータを読み取るローカルエネルギー履歴API

title: kWhデータを読み取るローカルエネルギー履歴API

abstract: オフライン分析のために、30分単位のkWh履歴をローカルで読み取ります。

language: ja

author: Jessica

はじめに

独自のダッシュボードや自動化、オフライン分析ツールを構築するユーザーにとって、実測のエネルギーデータは安定した間隔で取得できるとより有用です。リアルタイムの電力値が1点だけでは「今」の状況しか分かりませんが、30分単位のkWh履歴があれば、電力の買電（import）と売電（export）が時間とともにどのように変化するかを把握できます。

2026年6月2日に公開されたファームウェア i.91.063TS8.bin 以降、IAMMETER は新しいローカルAPI GET /api/energyhistory をサポートしています。このAPIは、UTCの30分境界付近でサンプリングされたkWh値をローカルキャッシュから返すため、クラウド側の履歴だけに頼らずに直近のエネルギー使用状況を分析できます。

これは特に、太陽光発電の監視、家庭のエネルギー監視、そして買電・売電・相ごとのエネルギーデータを比較したいカスタムのエネルギーマネジメントワークフローで役立ちます。IAMMETER は単なるモニターではありません。このデータを収集する目的は、ユーザーがエネルギー使用を最適化し、太陽光の自家消費率を高め、電気代を削減できるようにすることにあります。

エネルギー履歴APIが提供するもの

新しいエンドポイントは次のとおりです。

GET /api/energyhistory

kWh 単位のエネルギー値が、次のUTC 30分境界付近でサンプリングされて返されます。

00:00
00:30
01:00
01:30
以下同様

ファームウェアは最大 96 件のレコード、つまり30分間隔で 48 時間分の履歴を保持します。レコードはWi-FiモジュールのRAMに保存されるため、デバイスの再起動後は失われます。

一般的なレスポンスには次の項目が含まれます。

utc: モジュールの現在のUTCタイムスタンプ
timeSynced: モジュールが有効なUTC時刻を持っているかどうか
interval: サンプリング間隔。現在は 1800 秒
count: 利用可能な履歴レコード数
order: 現在は newest_first
unit: 現在は kWh
channels: 各値に対応するチャネル名
Datas: 30分単位の履歴レコード

Datas の各項目にはUTCタイムスタンプとkWh値の配列が含まれます。値の並びは channels 配列と同じ順序です。

30分単位のkWh履歴が重要な理由

30分単位のエネルギーデータは、ユーザーにコンパクトでありながら意味のあるエネルギー挙動の見方を与えるため実用的です。すべてのリアルタイム値を保存する代わりに、一定の時間枠ごとに積算された買電・売電の値を分析できます。

たとえば、ユーザーはローカルデータを使って次のことができます。

クラウドのレポートを待たずに、直近の買電・売電エネルギーを確認する。
直近48時間のkWh値をローカルデータベースやCSVファイルにエクスポートする。
太陽光の売電パターンと家庭内消費を比較する。
自動化戦略によって特定の時間帯の電力使用が変化したかどうかを確認する。
直近のエネルギー履歴を表示するローカルダッシュボードを構築する。

より広範な太陽光監視のシナリオについては、IAMMETER 太陽光発電モニタリングソリューションをご覧ください。住宅の電力監視については、IAMMETER 家庭用エネルギー監視ソリューションをご覧ください。

対応するチャネル構成

channels フィールドは、各履歴レコードの値をどのように解釈すべきかをクライアントに伝えます。メーターの構成によって返されるチャネル構成は異なります。

単相

["imp", "exp"]

スプリットフェーズ

["a_imp", "a_exp", "b_imp", "b_exp"]

三相

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"]

三相（ネットメータリング有効時）

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp", "nem_imp", "nem_exp"]

チャネル名はレスポンスで返されるため、カスタムソフトウェアはまず channels 配列を読み、それに従って Datas[].values の各値を対応付ける必要があります。

APIが返す元の値の例

次の2つの例は、空のレスポンスとデータありのレスポンスについて、APIが返す元の値を示しています。

空のレスポンスの例

デバイスの起動後、有効なUTC時刻と有効なメーターフレームが得られるまで、履歴配列は空のことがあります。この場合、APIは count: 0 と空の Datas 配列を返すことがあります。

{
  "utc": 1780023600,
  "timeSynced": 1,
  "interval": 1800,
  "count": 0,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": []
}

このレスポンスは起動後は正常です。ローカルのダッシュボードやスクリプトはこの状態を処理し、新しい30分サンプルを待つ必要があります。

データありのレスポンスの例

次の例は、三相メーターからの2件の30分レコードを示しています。レスポンスは新しい順に並んでいます。

{
  "utc": 1780023700,
  "timeSynced": 1,
  "interval": 1800,
  "count": 2,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": [
    {
      "utc": 1780023600,
      "values": [11.337, 11.201, 11.039, 10.908, 10.975, 10.846]
    },
    {
      "utc": 1780021800,
      "values": [11.330, 11.198, 11.030, 10.900, 10.970, 10.840]
    }
  ]
}

最新のレコードでは、a_imp は 11.337 kWh、a_exp は 11.201 kWh となり、以下同様です。各値の意味は channels 配列で定義されます。

ソフトウェアで戻り値を使う

上記の元の戻り値の例だけで、シンプルなローカル分析ロジックを構築できます。ポイントは、まず channels を読み、その順序を Datas の各項目に適用することです。

`channels` と `values` の対応付け

このAPIを使うソフトウェアを構築する際は、メーター構成が固定でない限り、位置をハードコードしないでください。より安全な方法は、チャネルリストと値の配列を名前付きオブジェクトに変換することです。

const response = await fetch("http://<meter-ip>/api/energyhistory").then((res) => res.json());
const latest = response.Datas[0];

const latestByChannel = Object.fromEntries(
  response.channels.map((name, index) => [name, latest.values[index]])
);

console.log(latest.utc, latestByChannel);

上記の三相レスポンスの例では、latestByChannel は次のようになります。

{
  "a_imp": 11.337,
  "a_exp": 11.201,
  "b_imp": 11.039,
  "b_exp": 10.908,
  "c_imp": 10.975,
  "c_exp": 10.846
}

これにより、データをローカルの分析ツールへ保存、表示、エクスポートしやすくなります。

30分ごとのkWh変化量の計算

返されたkWh値を積算エネルギー値として扱う場合、隣接する2件のレコードの変化量は、同じチャネルについて古い値を新しい値から引くことで計算できます。

上記の三相の例を使うと次のようになります。

a_imp change = 11.337 - 11.330 = 0.007 kWh
a_exp change = 11.201 - 11.198 = 0.003 kWh
b_imp change = 11.039 - 11.030 = 0.009 kWh
b_exp change = 10.908 - 10.900 = 0.008 kWh

この種の計算は、直近の買電／売電レポートの作成、相ごとのエネルギー変化の比較、特定の30分枠でどれだけ買電・売電があったかの確認に役立ちます。

重要なサンプリング動作

エネルギー履歴はWi-Fiモジュールによってローカルで生成されます。連携や分析ツールを構築する際には、このサンプリング動作が重要です。

サンプリングは有効なUARTメーターフレームによって駆動されます。
モジュールは各30分のUTC境界に最も近いサンプルを保存します。
履歴レコードが保存されるには、UTC時刻が有効である必要があります。
timeSynced が 0 の場合、新しい履歴サンプルは記録されません。
起動後は、十分な有効サンプルが取得されるまで Datas が空のことがあります。
現在の保存先はRAMのため、このAPIは長期的な保存ではなく直近のローカル履歴を対象としています。

このため、このAPIはローカルでのポーリング、短期分析、連携テストに適しています。長期的なエネルギーレポートには、IAMMETERクラウドのデータや自前のデータベースなど、永続的なデータソースを引き続き用意してください。

連携のアイデアの例

開発者や上級ユーザーは、/api/energyhistory を直近のkWh履歴のためのシンプルなローカルデータソースとして利用できます。

よくある方法は、定期的にエンドポイントをポーリングし、channels リストを読み、新しい Datas レコードをローカルデータベースに保存するものです。これはローカルダッシュボード、カスタムレポート、オフライン分析スクリプトに利用できます。

もう一つ有用なシナリオは、太陽光の自家消費分析です。30分枠ごとの買電・売電のkWh値を比較することで、家庭内負荷が太陽光の発電をどの時間帯に自家消費し、余剰電力がいつ売電されているかをよりよく理解できます。これは、柔軟な負荷を太陽光発電量の多い時間帯に移すなど、より良い自動化の判断につながります。

ローカル連携を構築する場合は、ローカルAPI、Modbus/TCP、MQTT と IAMMETER Local API Explorer もご覧ください。

エネルギーマネジメントへの位置づけ

エネルギー履歴APIの価値は、単により多くのデータを公開することだけではありません。重要なのは、ユーザーがそのデータで何ができるかです。

30分単位のkWh履歴があれば、直近の買電・売電を分析し、使用パターンを特定し、太陽光や負荷制御の戦略が実際に役立っているかを評価できます。これは、エネルギー監視データを、エネルギー効率を高め電気代を削減する実践的な判断へと変えるというIAMMETERの目標につながります。

IAMMETERを自動化プラットフォームと組み合わせて使うユーザーにとって、ローカルのエネルギー履歴は制御ロジックのテストと検証に便利なデータレイヤーにもなります。たとえば、太陽光の余剰電力を最適化するHome Assistantユーザーは、直近のkWh変化量を自動化の動作と並べて確認できます。関連するユースケースは IAMMETERを使ったHome Assistantの太陽光発電自動化をご覧ください。

よくある質問

このAPIは長期的なエネルギー履歴の代わりになりますか？

いいえ。このAPIは最大96件、つまり30分データで48時間分をRAMに保存します。直近のローカル履歴向けに設計されています。データは再起動後に失われます。

起動後に `Datas` が空なのはなぜですか？

起動後、履歴サンプルを記録するには、モジュールが有効なUTC時刻と有効なメーターフレームを必要とします。十分な有効サンプルが取得されるまでは、APIが空の Datas 配列を返すことがあります。

タイムスタンプはローカル時刻に基づいていますか？

いいえ。サンプリングの枠はUTCの30分境界に合わせられています。

ソフトウェアはvalues配列をどう解釈すべきですか？

常に channels フィールドを先に読んでください。各 Datas[].values 配列の値は、チャネル名と同じ順序で並んでいます。