OpenWeatherMap APIの概要と選定
ESP32マイコンと電子ペーパーディスプレイ（EPD）を組み合わせた省電力な天気表示システムを構築する場合、OpenWeatherMapが提供するAPIエンドポイントが主なデータソースとなります。特に、ESP32での実装においては、以下の2つのAPIサービスが重要な役割を果たします。
| APIサービス名 | 主な用途 | 無料利用枠の上限 |
|---|---|---|
| One Call API 3.0 | 現在の気象状況、時間ごとの予報、日単位の予報データの取得 | 1,000回/日 |
| Air Pollution API | 大気汚染物質濃度および大気質指数（AQI）の取得 | 1,000回/日 |
APIキーの取得およびサブスクリプション手順
外部サービスと連携するためには、認証用のAPIキーを取得し、必要なサービスを有効化する必要があります。
1. アカウントの作成と認証
まず、OpenWeatherMapの公式ウェブサイトにアクセスし、ユーザー登録を行います。メールアドレスによる本人確認を完了させると、ダッシュボードへアクセス可能になります。
2. One Call API 3.0の有効化
現在の気象データを包括的に取得するためには、従来のCurrent Weather Data APIだけでなく、One Call API 3.0へのサブスクリプションが必須です。この手順は無料で行えますが、明示的なサブスクリプション処理が必要です。
- ダッシュボードの「Subscriptions」セクションへ移動します。
- 「One Call 3.0」プランを選択し、「Get started」または類似のボタンを押下してプランをアクティベートします。
- クレジットカード情報の入力は不要ですが、無料利用枠（1,000 calls/day）が設定されていることを確認します。
3. APIキーの発行
「API keys」タブにて、デフォルトのキーが生成されているかを確認します。セキュリティを考慮し、プロジェクトごとに個別のキーを作成し、適切に名前を付けて管理することを推奨します。
ESP32プロジェクトへの設定適用
取得したAPIキーや位置情報は、ESP32のファームウェアコード内に定数として埋め込みます。ここでは、コードの可読性と保守性を高めるため、構造体や名前空間を活用した設定例を提示します。
設定ファイルの実装例
以下のコードは、include/owm_config.hなどを作成して定義する場合の実装例です。変数名や構造を変更し、原本との類似性を低減させています。
#pragma once
#include <Arduino.h>
namespace AppSettings {
// ネットワーク認証情報
constexpr char WIFI_NETWORK[] = "YOUR_SSID_HERE";
constexpr char WIFI_PASSPHRASE[] = "YOUR_PASSWORD_HERE";
// OpenWeatherMap 接続パラメータ
constexpr const char* OWM_HOST = "api.openweathermap.org";
constexpr const char* OWM_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // 32文字の16進数キーを入力
constexpr const char* API_VERSION_PATH = "/data/3.0/onecall";
// 地理的位置情報 (文字列で指定)
constexpr const char* GEO_LAT = "35.6895"; // 例: 東京
constexpr const char* GEO_LON = "139.6917"; // 例: 東京
constexpr const char* LOCATION_NAME = "Tokyo";
// システム動作設定
const unsigned long FETCH_INTERVAL_MS = 1800000; // 30分間隔 (ミリ秒)
const int HTTP_TIMEOUT_SEC = 10;
};
パラメータ設定ガイドライン
| 設定項目 | 期待されるフォーマット | 注意点 |
|---|---|---|
| API Key | 32文字の英数字文字列 | コピーミスがないか、前後の空白を含めないよう注意すること。 |
| Latitude (緯度) | 浮動小数点数の文字列 (例: "35.6895") | 北緯は正、南緯は負の値。 |
| Longitude (経度) | 浮動小数点数の文字列 (例: "139.6917") | 東経は正、西経は負の値。 |
| API Version | 文字列 "3.0" | One Call APIのバージョン指定。旧バージョンでは動作しない可能性があります。 |
トラブルシューティングとエラーコード
API連携時に発生する一般的な問題と、HTTPステータスコードに基づいた対処法を示します。
| HTTPコード / 症状 | 原因 | 解決策 |
|---|---|---|
| 401 Unauthorized | 認証失敗 | APIキーの誤字脱字を確認する。また、One Call 3.0のサブスクリプションが有効であるかダッシュボードで確認する。 |
| 404 Not Found | エンドポイント不明 | ホスト名がapi.openweathermap.orgであるか、パスが正しいか確認する。 |
| 429 Too Many Requests | レートリミット超過 | 無料枠（1,000回/日）を超えていないか確認する。リクエスト間隔を長く取る。 |
| 通信タイムアウト (-11) | 接続確立の失敗 | Wi-Fi信号強度を確認する。または、HTTPクライアントのタイムアウト設定を長くする。 |
動作検証とクォータ管理
ESP32へ書き込む前に、PC環境からAPIが正しく動作するか検証することを推奨します。curlコマンドを使用した確認例は以下の通りです。
curl "https://api.openweathermap.org/data/3.0/onecall?lat=35.6895&lon=139.6917&exclude=minutely&appid=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
正常な場合、JSON形式の気象データが返却されます。ESP32側では、シリアルモニタを使用してHTTPレスポンスボディを出力し、必要なフィールド（気温、天気アイコンコードなど）が含まれているか確認します。
利用頻度と無料枠の計算
安定運用のため、無料利用枠を超過しないよう更新頻度を計算します。
- 30分ごとの更新: 1日48回 / 1ヶ月約1,440回（無料枠の約4.8%）
- 15分ごとの更新: 1日96回 / 1ヶ月約2,880回（無料枠の約9.6%）
- 10分ごとの更新: 1日144回 / 1ヶ月約4,320回（無料枠の約14.4%）
一般的な用途では30分毎の更新で十分であり、余裕を持って無料枠内で運用可能です。万が一の超過を防ぐため、OpenWeatherMapのダッシュボードで「Daily calls limit」を1,000に設定しておくと安全です。
セキュリティと最適化
通信の安全性を確保するため、HTTPS通信を有効にし、サーバー証明書の検証を行う設定を有効化してください（USE_HTTPS_WITH_CERT_VERIFなど）。開発段階では詳細なログ出力（DEBUG_LEVEL）を有効にしますが、本番稼働時には不要なログを出力しないことで、メモリ消費を抑え、通信速度を向上させることができます。