SolarComm Enterprise API 仕様書

最終更新：2026-07-30 ／ APIバージョン v1

宇宙天気（太陽フレア・地磁気嵐）による通信障害・測位精度低下のリスク判定を、貴社のシステム（AGV・PLC・ドローン運航管理・測量計画など）から取得できるREST APIです。Enterpriseプランのご契約者がご利用いただけます。

1. エンドポイント

GET https://solarcomm.aquaflow3s.workers.dev/v1/risk

認証はX-Api-Keyヘッダーで行います。APIキーはSolarCommの「プラン・レポート」画面から発行できます。

接続確認

curl -H "X-Api-Key: sc_live_xxxxxxxx" \
  https://solarcomm.aquaflow3s.workers.dev/v1/risk

2. リクエスト

項目	内容
メソッド	GET
認証ヘッダー	`X-Api-Key: sc_live_...`（必須）
パラメータ	なし
推奨呼び出し間隔	5分以上（元データのNOAA SWPCが5分間隔で更新されるため、それより短い間隔では同じ値が返ります）

3. レスポンス

{
  "risk": 21,
  "safety": 79,
  "level": "safe",
  "dataOk": true,
  "model": "rule-based-explainable-v1",
  "factors": [
    { "key": "kp",      "label": "地磁気指数 Kp",        "value": "2.33", "score": 2,  "max": 40, "ok": true,
      "reason": "静穏。地磁気起因の障害リスクは低い（アルゴリズム判定）" },
    { "key": "wind",    "label": "太陽風速度",           "value": "411 km/s", "score": 2, "max": 25, "ok": true,
      "reason": "平常レベル（約300-450 km/s）" },
    { "key": "xray",    "label": "X線フラックス（フレア級）", "value": "B9.7", "score": 1, "max": 25, "ok": true,
      "reason": "静穏" },
    { "key": "density", "label": "太陽風密度",           "value": "1.1 /cm3", "score": 1, "max": 10, "ok": true,
      "reason": "平常レベル" }
  ],
  "regions": [
    { "id": "hokkaido", "name": "北海道", "gpsError": 2.1, "level": "safe" },
    { "id": "kansai",   "name": "関西",   "gpsError": 1.5, "level": "safe" }
  ],
  "alerts": [
    { "level": "safe", "text": "現在、通信・測位に影響する顕著な太陽活動はありません" }
  ],
  "spaceWeather": {
    "kp": { "time": "2026-07-30T09:00:00", "value": 2.33 },
    "kpHistory": [ { "time": "...", "value": 1.67 } ],
    "wind": { "time": "...", "speed": 411.2, "density": 1.1, "source": "SOLAR1" },
    "xray": { "time": "...", "flux": 9.7e-7, "flareClass": "B9.7" },
    "fetchedAt": "2026-07-30T13:32:43.000Z"
  },
  "cmeEtaHours": 68.4
}

主要フィールド

フィールド	型	説明
`risk`	number	通信障害リスク指数 0〜100（大きいほど危険）
`safety`	number	通信安全スコア（100 − risk）
`level`	string	`safe`（risk 0-34）／`warning`（35-59）／`danger`（60-100）
`dataOk`	boolean	観測データが揃っているか。`false`のときは一部データが取得できておらず、既定値で暫定計算した値です。判断に使わないでください。
`factors[]`	array	因子ごとの値・獲得点・上限点・根拠文。各因子の`ok`が`false`ならその因子は取得失敗
`regions[]`	array	10地域別のGPS水平測位誤差の推定値（メートル）と`level`。`gpsError`が`null`のときは算出不能
`alerts[]`	array	日本語の警告文（現場掲示・通知への転記用）
`spaceWeather.kpHistory[]`	array	Kp指数の直近72時間（3時間刻み・最大24点）
`spaceWeather.wind.source`	string	太陽風の観測衛星名（`ACE`／`DSCOVR`／`SOLAR1`等）
`cmeEtaHours`	number｜null	地球方向CMEの到達予測（時間後）。等速直進による簡易推定
`model`	string	判定モデルの識別子。改訂時に変わります

実装上の重要な注意

dataOk === false のときは自動制御の判断に使わないでください。 観測データの欠測・提供元の仕様変更時にこの状態になります。貴社側では「前回の正常値を保持する」または「安全側に倒す」処理を推奨します。
gpsError は単独測位を想定した推定値です。RTK等の補正測位では通常これより小さくなりますが、Kp7以上の強い磁気嵐では基準局側の補正品質も劣化します。
数値はすべてアルゴリズムによる推定であり、障害の発生・不発生を保証するものではありません。詳細は免責事項をご確認ください。
時刻はUTCです。日本時間は+9時間してください。
factorsの配列順・要素数は将来変更される可能性があります。keyで参照してください（添字で参照しないでください）。

4. 利用上限

種別	上限	超過時
月間コール数	30,000回（毎月1日 0:00 JST にリセット）	HTTP 429 `quota_exceeded`
短期バースト	20回/分	HTTP 429 `rate_limited`（`Retry-After: 60`）
同時有効キー数	2本（無停止ローテーション用）	HTTP 409 `too_many_keys`

5分間隔のポーリングで月約8,600回、10分間隔で約4,300回です。月間上限30,000回は5分間隔運用の約3.5倍の余裕があります。1分間隔など短い周期での運用をご検討の場合は、あらかじめご相談ください。

残数の確認（レスポンスヘッダー）

ヘッダー	内容
`X-RateLimit-Limit`	月間上限（30000）
`X-RateLimit-Remaining`	今月の残り回数
`X-RateLimit-Reset`	リセット時刻（ISO 8601・UTC）

SolarCommの「プラン・レポート」画面でも、今月の利用回数と上限をご確認いただけます。

5. エラーコード

HTTP	`error`	意味・対処
401	`unauthorized`	`X-Api-Key`ヘッダーがありません
403	`invalid_api_key`	キーが無効または失効済み。画面から再発行してください
402	`plan_required`	Enterpriseプランのご契約が必要です（解約・降格後はこの応答になります）
429	`rate_limited`	1分あたりの上限超過。`Retry-After`秒後に再試行してください
429	`quota_exceeded`	月間上限超過。翌月1日にリセットされます
500	`server_error`	サーバー側の一時的な問題。時間をおいて再試行してください

エラー応答には日本語のmessageフィールドが付きます。ログに記録しておくと原因の特定が容易です。

6. APIキーの管理

キーはSolarCommの「プラン・レポート」画面から発行します。
全文が表示されるのは発行直後の1回だけです。当社サーバーには暗号化ハッシュのみを保存しており、再表示はできません。安全な場所に保管してください。
紛失した場合は新しいキーを発行し、古いキーを失効してください。
無停止での切り替え：同時に2本まで有効にできます。新しいキーを発行 → 貴社システムの設定を差し替え → 動作確認後に古いキーを失効、の順で行えば停止時間はありません。
キーは第三者に共有せず、貴社システム内で管理してください。ソースコードへの直接記述は避け、環境変数等をご利用ください。

7. 想定される連携例

用途	実装イメージ
AGV・無人搬送車の速度制御	`level === "danger"` または該当地域の`gpsError`が閾値超過で自動走行速度を制限、または有人モードへ切替
ドローン運航のプリフライト判定	`danger`なら目視外飛行を見合わせ、目視内運用へ切替または当日延期
RTK測量の作業計画	朝の判定で再測リスクの高い日を回避
現場掲示・アンドン表示	`level`と`alerts[].text`を電光掲示板・サイネージへ転記
社内通知	閾値超過時に貴社のSlack／Teams／メールへ転送
事後の原因究明	`factors`を作業日報・設備ログに毎回記録しておくと、後日「原因不明の測位エラー」を宇宙天気起因と切り分けられます

8. データ出典

データ	出典
地磁気指数 Kp／太陽風／X線フラックス	NOAA SWPC（米国海洋大気庁宇宙天気予測センター）
太陽フレア／CME	NASA DONKI
太陽画像	NASA SDO

いずれも公的機関が提供する無料データです。提供元は予告のうえ形式・エンドポイントを変更することがあり、その際は当社が追随対応します（切替中はdataOkがfalseになる場合があります）。

9. 変更履歴・互換性の方針

日付	内容
2026-07-30	v1 公開。`/v1/risk`・月間上限30,000回・レート制限ヘッダー・キー自己発行に対応

フィールドの追加は予告なく行う場合があります（既存フィールドの削除・意味変更は行いません）。
互換性を壊す変更が必要な場合は/v2/として新設し、v1は移行期間を設けて併存させます。
factorsはkeyで参照してください（配列順は保証しません）。

10. お問い合わせ

連携方法のご相談、上限の変更、機能のご要望は下記へお願いします。プッシュ通知（Webhook）や任意座標での判定、数日先の予報などのご要望も承っています。

事業者	グリーンアップル株式会社
連絡先	info@greenapplekk.com