GribStream

よくある質問

アカウント、利用枠、制限

API利用枠は正確にはどのように計算されますか?

クレジットは、指定した時間数だけでなく、APIが実際に返したデータ量に対して課金されます。

Credits = returned_valid_times * parameters * ceil(coordinates / 500)

returned_valid_timesは、各地点について実際に返された有効時刻です。アンサンブル予報のクエリでは、各アンサンブルメンバーが独立した時系列として扱われます。

  • 1時間未満の時間解像度を持つデータセットは、返された有効時刻に対して課金されます。
  • 予報時間がまばらなデータセットは、実際に返された時刻だけが対象です。
  • キャッシュヒットは通常クレジットの10%で課金されます。
大きなバックフィル（backfill）のために一時的に利用枠を増やせますか?

はい。大きなバックフィルが必要な場合、短い時間枠でより多くのデータを取得できるよう、一時的な利用枠または処理量の調整を設定できます。

まずinfo@gribstream.comまで、データセット、変数、時間範囲、座標数、完了したい時期を送ってください。共有容量に影響を出さずに負荷を見積もれます。

429 Too Many RequestsとRetry-Afterは何を意味しますか?

429は通常、利用枠を使い切ったか、一時的な連続リクエスト制限（burst throttling）に当たったことを示します。

  • 利用枠を使い切った場合、Retry-Afterは次の日次UTCリセットまでの秒数です。
  • 一時的な連続リクエスト制限の場合、多くは短い待機時間です。

Retry-Afterを尊重し、ランダムな待ち時間を加えた指数バックオフ（exponential backoff with jitter）を使い、短い間隔で再試行を繰り返さないでください。

401/429が続いた後、IPが一時的にブロックされたのはなぜですか?

拒否されたリクエストをクライアントが高頻度で再試行し続けると起きます。共有容量を守るため、GribStreamは送信元IPを一時的にブロックすることがあります。

401は認証を直すまで再試行せず、429ではRetry-Afterを守り、再試行回数に上限を設けてください。

日次利用枠はいつリセットされますか?

日次利用枠は00:00 UTCにリセットされます。正確なカウントダウンはトークンダッシュボードで確認できます。

クエリの意味とセレクタ

GribStream APIの/timeseriesと/runsの違いは何ですか?

どちらも同じ予報データを問い合わせますが、答える質問が異なります。

/timeseriesは、各有効時刻について、指定した絞り込み条件の中で最短のリードタイムを持つ最良の値を返します。プロダクト用の曲線、ダッシュボード、特徴量作成、モデル実行時刻ベースのバックテストに向いています。

/runsは、条件に合うモデル実行と予報時間の値をすべて返します。予報サイクルの比較、モデル実行間のずれ、研究用途に向いています。

fromTime/untilTimeとtimesListはどう使い分けますか?

密で連続した時間窓にはfromTime/untilTimeを使います。必要な時刻がすでに分かっていて、まばらに抽出したい場合はtimesListを使います。

実務上、timesListは指定した時刻だけを返すため、余分な取得とクレジット消費を減らしやすいです。

asOfは何をしますか? いつ使うべきですか?

asOfは/timeseries向けのモデル実行時刻による基準時刻です。forecasted_atがその時刻以前の行だけが候補になります。

これはモデル実行時刻の視点での基準であり、GribStreamがデータをインデックスした時刻やAPIで公開した時刻ではありません。

後のモデルサイクルを混ぜずに、モデル実行時刻ベースでバックテストしたいときに使います。asOfを省略すると、GribStreamは利用可能な最新のモデル実行を使います。/runsではasOfを使いません。

asOfはAPIで実際に見えていた時刻を正確に再現しますか?

いいえ。asOfはモデル実行時刻を使います。モデル実行がGribStreamで最初に利用可能になった実際の時刻ではありません。

たとえばGFSの12Zモデル実行は、forecasted_atが12:00Zなので、asOf: "12:30Z"で候補になることがあります。実際には12:30Z時点でAPIにまだ見えていなかった場合でも同じです。

バックテストでAPI上の実際の利用可能タイミングを近似する必要がある場合は、asOfを設定する前に保守的な余裕時間を差し引くのが標準的な公開ワークフローです。過去の意思決定時刻から、通常の公開遅延とインデックス遅延の見積もりを差し引き、その早めた時刻をasOfとして使います。

この余裕時間は、名目上のモデルサイクルから、提供元が必要な予報時間を公開オブジェクト/blobストレージに公開するまでの通常の遅延に基づけるべきです。提供元やGribStreamでまれに起きる遅延のための余裕も加えてください。GFSなどのNOAAフィードでは、ファイルは予報時間の順にアップロードされます。そのため最初の48時間分だけを使う処理なら、モデル実行全体を待つ処理より小さい補正で足りることがあります。

GribStreamはまだモデルページでデータセット別・予報時間別の遅延目安を公開していません。これは別の反復で扱う予定です。includeMetadata: ["index_updated_at"]を指定すると各結果で使われたインデックス行の最新時刻を確認できますが、安定した初回利用可能時刻の監査ログとして扱うべきではありません。インデックス時刻に基づく実験的なワークフローはリクエストに応じて利用できる場合がありますが、安定した公開API契約の一部ではありません。

行がforecasted_atやforecasted_timeで並んでいないのはなぜですか?

レスポンスは処理量に最適化された順序でストリームされるため、時系列順は保証されません。

決定的な順序が必要な場合は、ダウンロード後にクライアント側で並べ替えてください。/timeseriesではforecasted_time、次にforecasted_atで並べるのが一般的です。/runsでは、処理で使う時刻、モデル実行、リードタイムの項目で並べ替えてください。

変数セレクタ（name, level, info）はどう機能しますか?

変数セレクタは、次のような正確なJSONオブジェクトです。

{ "name": "TMP", "level": "2 m above ground", "info": "" }
  • name: 必須のパラメータコード。例: TMPやUGRD。
  • level: 必須の鉛直または物理レベル。
  • info: 同じ名前のフィールドを区別する任意の値。name + levelが同じフィールドが複数ある場合に必要です。
  • alias: 出力列名を変えるための任意フィールド。選択対象そのものは変わりません。

各モデルページの変数一覧から、正確なセレクタJSONをコピーできます。

格子リクエストがこのデータセットで点を返さないのはなぜですか?

多くの場合、指定した格子が対象領域と交差していません。

  • 境界がモデルのカバー範囲外にある。
  • 緯度/経度の上下限が逆になっている。
  • 境界とstepの組み合わせにより、対象領域内に有効な点が残っていない。

まずモデルページでカバー範囲を確認し、対象領域内の既知の1座標で試してから格子に広げてください。

アンサンブルメンバーはどう機能しますか? デフォルトは何ですか?

アンサンブルデータセットでは、リクエスト本文のmembers配列で返すメンバーを選びます。

  • membersを省略すると、GribStreamは最初の利用可能なメンバーだけを返します。通常は制御メンバーである0です。
  • メンバーを追加すると、行数とクレジットはほぼ線形に増えます。
  • 利用可能なメンバーを調べるには、/api/v2/catalog/datasets/{dataset}を呼び、membersを確認してください。

アンサンブルではないデータセットでは、membersは使いません。

最短リードタイムの時系列が予報サイクル境界で値飛びするのはなぜですか?

/timeseriesでは、各有効時刻について、絞り込み条件の中で最短のリードタイムを持つ値を選びます。予報サイクルの境界付近では、選ばれるモデル実行が変わり、時系列に値飛びが出ることがあります。

  • 曲線全体でモデル実行を固定したい場合は/runsを使ってください。
  • 存在する場合は、minLeadTime: "0h"とmaxLeadTime: "0h"でリードタイム0に限定できます。
  • 1時間未満の時系列を可視化する場合は、連続するリードタイム0の基準点の間を補間する方法もあります。

バックフィルと性能

大きなバックフィル（backfill）を安全かつ安く構成するには?

大きなバックフィルでは、安定した処理量と、返される点あたりの低いオーバーヘッドを優先します。

  • 各リクエストが10から15秒程度で終わるように分割します。
  • その目標時間に収まる範囲で、リクエストあたりの座標数を最大化します。
  • まばらな時刻には、広い時間範囲ではなくtimesListを使います。
  • 変数は絞ります。変数が増えるほどデータ量とクレジットが増えます。
  • 本格実行の前に小さな試験実行を行います。
キャッシュは価格と性能にどう影響しますか?

キャッシュヒットは通常クレジットの10%で課金され、多くの場合はかなり速く返ります。

キャッシュが特に効くのは、繰り返し問い合わせられる最近のデータ、現在値に近い値、短いリードタイムのクエリです。

  • キーには座標が含まれるため、座標を変えるとキャッシュキーも変わることが多いです。
  • 非常に大きな座標リクエストはキャッシュ対象外です。
  • 古い組み合わせや長いリードタイムは、最近かつ短いリードタイムのクエリよりキャッシュされにくいです。
本番環境ではどのHTTPヘッダーを推奨しますか?

推奨する基本セットは次の通りです。

  • Authorization: Bearer <token>
  • Content-Type: application/json
  • Accept: text/csv, application/json, または application/ndjson
  • 大きなレスポンスではAccept-Encoding: gzipを強く推奨します。

クライアント側でgzipを受け取り、展開できることを確認してください。

API内の計算式/絞り込みと後処理はどう使い分けますか?

単位変換、しきい値、イベント判定、直接的な数式など、返すデータ量を早い段階で減らせる処理にはAPIの計算式と絞り込みを使います。

状態を持つロジック、複数データセットの結合、外部データによる拡張、より複雑なパイプラインには後処理を使ってください。

実務上は、まずAPIで絞り込みと派生計算を行い、その後で高度な分析を実行する流れを推奨します。

バックテストとデータ戦略

GribStreamを過去の気象データとバックテストに同じAPIで使えますか?

はい。GribStreamは同じAPIで両方の用途に対応します。

  • /timeseriesとasOfを使うと、モデル実行時刻の基準時刻に基づく最良の予報を再現できます。
  • APIで実際に見えていた時刻を近似する必要がある場合は、asOfを設定する前に、使用する予報時間に対する提供元の通常の公開遅延に基づく保守的な余裕時間を差し引いてください。
  • 予報データセットを入力にし、解析値や観測系データセットを評価対象として使えます。
  • 有効時刻と座標でそろえてください。評価時刻がまばらな場合はtimesListが便利です。
NOAA/ECMWFから生のGRIB2ファイルをダウンロードする場合とGribStreamは何が違いますか?

どちらも有効ですが、重視する点が違います。

  • 生のGRIB2: ファイル単位で最大限に制御できますが、取り込み、インデックス作成、デコード、保存、再試行、可用性を自分で運用します。
  • GribStream API: 必要な変数、場所、時刻、形式だけをリクエストできます。運用負荷が少なく、統合も速くなります。

多くのチームは併用します。プロダクトや分析にはAPIを使い、専門的な研究には生ファイルを使います。

派生指標

風のベクトルを風速と風向に変換するには?

多くのモデルは風をu成分とv成分で表します。風速と気象学的な風向は次の式で計算できます。

speed = math.sqrt(u*u + v*v)
direction = (270 - math.atan2(v, u) * 180 / math.pi) % 360

uは東西方向の成分（zonal）、vは南北方向の成分（meridional）です。2つ目の式は角度を気象学の風向の慣例に合わせます。

GribStreamの計算式では、func.Hypot(uwind, vwind)とfunc.Atan2(vwind, uwind)を使えます。

Kelvinの気温と相対湿度から露点を計算するには?

気温をKelvinからCelsiusに変換し、Magnus-Tetens近似を適用します。

T_C = T - 273.15

a = 17.27
b = 237.7

gamma = (a * T_C) / (b + T_C) + math.log(RH / 100)
dew_point_C = (b * gamma) / (a - gamma)

GribStreamの計算式を使えば、dew_point_Cまたはdew_point_Kを派生列としてレスポンスに含められます。