気象予報データAPIドキュメント

このAPIでは、すべてのモデルの気象予報データへアクセスできます。時間範囲、座標、取得したい変数を指定して、過去に発行された予報データと最新の予報データを取得できます。

GitHubで公開しているPythonクライアントを使うことも、下の仕様をもとにHTTPリクエストを直接組み立てることもできます。

GribStreamをAIツールに組み込む場合は、まずAIツール向けGribStreamを確認してください。

Timeseriesエンドポイント

同じ座標、気象パラメータ、時間範囲でも、複数の予報値が利用できます。各値は異なるリードタイム（モデル実行時刻から有効時刻までの予報時間）に対応します。

APIは各時刻について、条件に合う中で最も短いリードタイムの予報値を返します。つまり、その時点で利用可能だった最も新しく、通常は最も精度が高い予報を受け取れます。データ分析では、こうした値を「最良予報」または「現在に近い予報系列」と呼ぶことがあります。

POST https://gribstream.com/api/v2/<model>/timeseries

名称変更以前は/historyでした。旧URLも引き続き動作します。

利用可能なモデル

rap - Rapid Refresh (RAP)
gfs - Global Forecast System (GFS)
gdas - Global Data Assimilation System (GDAS)
nbm - National Blend of Models (NBM) (CONUS core)
nbmak - National Blend of Models (NBM) (Alaska core)
nbmhi - National Blend of Models (NBM) (Hawaii core)
nbmpr - National Blend of Models (NBM) (Puerto Rico core)
nbmgu - National Blend of Models (NBM) (Guam core)
nbmoc - National Blend of Models (NBM) (Oceanic core)
nbmqmd - National Blend of Models QMD (CONUS)
nbmpar - National Blend of Models Parallel (CONUS core, NBM v5)
nbmparak - National Blend of Models Parallel (Alaska core, NBM v5)
nbmparhi - National Blend of Models Parallel (Hawaii core, NBM v5)
nbmparpr - National Blend of Models Parallel (Puerto Rico core, NBM v5)
nbmpargu - National Blend of Models Parallel (Guam core, NBM v5)
nbmparoc - National Blend of Models Parallel (Oceanic core, NBM v5)
nbmparqmd - National Blend of Models Parallel QMD (CONUS, NBM v5)
aigfssfc - AI Global Forecast System Surface (AIGFS Surface)
aigfspres - AI Global Forecast System Pressure Levels (AIGFS Pressure)
aigefssfc - AI Global Ensemble Forecast System Surface (AIGEFS Surface)
aigefspres - AI Global Ensemble Forecast System Pressure Levels (AIGEFS Pressure)
dafsgtg - Domestic Aviation Forecast System Graphical Turbulence Guidance (CONUS)
dafsificonus - Domestic Aviation Forecast System In-Flight Icing (CONUS)
dafsifiak - Domestic Aviation Forecast System In-Flight Icing (Alaska)
cwawrf15 - Taiwan CWA WRF 15 km Regional Forecast
ccpa1hndgd25 - Climatologically Calibrated Precipitation Analysis (1-hour CONUS)
spctstm1hr - SPC HREF Thunderstorm Probability (1 hour)
spctstm4hr - SPC HREF Thunderstorm Probability (4 hour)
spcltg4hr - SPC HREF Lightning-density Probability (4 hour)
spchail4hr - SPC HREF Calibrated Hail Probability (4 hour)
spctor4hr - SPC HREF Calibrated Tornado Probability (4 hour)
spcwind4hr - SPC HREF Calibrated Severe Wind Probability (4 hour)
uvi - NOAA Ultraviolet Index Forecast
fourcastnetgfs - FourCastNet Global Forecast System (FourCastNetGFS)
urma - Unrestricted Mesoscale Analysis (URMA)
rtma - Real-Time Mesoscale Analysis API (RTMA)
hrrr - High-Resolution Rapid Refresh (HRRR)
rrfsprslev - Rapid Refresh Forecast System pressure levels (RRFS)
rrfs2dfld - Rapid Refresh Forecast System 2D fields (RRFS)
refsprslev - Rapid Refresh Forecast System Ensemble (RRFS Ens)
graphcast - GraphCast Global Forecast System (GFS GraphCast)
gefsatmosmean - Global Ensemble Forecast System (GEFS Atmos Mean)
gefsatmos - Global Ensemble Forecast System (GEFS Atmos)
gefschem - Global Ensemble Forecast System (GEFS Chem)
gefswaveprob - Global Ensemble Forecast System (GEFS Wave Prob)
cfsflxf - Climate Forecast System (CFS Radiative Fluxes)
cfspgbf - Climate Forecast System (CFS Pressure)
cfsipvf - Climate Forecast System (CFS Isentropic)
cfsocnf - Climate Forecast System (CFS Ocean)
cdas - Climate Data Assimilation System (CDAS1)
ifsoper - Integrated Forecasting System - Operational (IFS Oper)
ifswave - Integrated Forecasting System - Wave (IFS Wave)
ifsenfo - Integrated Forecasting System - Ensemble Forecast (IFS Enfo)
ifswaef - Integrated Forecasting System - Wave Ensemble Forecast (IFS Waef)
aifsoper - Artificial Intelligence Forecasting System (AIFS)
aifsenfo - Artificial Intelligence Forecasting System Ensemble (AIFS Ensemble)

リクエストヘッダー

ヘッダー	値	説明
`Content-Type`	`application/json`	デフォルト値であり、唯一有効な値です。
`Accept`	いずれかを指定: `text/csv` `application/json` `application/ndjson`	レスポンス形式を選択します。デフォルトは`text/csv`です。
`Accept-Encoding`	`gzip`	任意ですが、レスポンスの圧縮のため推奨です。
`Authorization`	`Bearer <token>`	<token>を自分の認証トークンに置き換えてください。

リクエスト本文のパラメータ

リクエスト本文は、次の構造を持つJSONオブジェクトにします:

パラメータ	型	説明	必須
`fromTime`	`string` (ISO 8601)	予報期間の開始時刻。	はい。`(fromTime, untilTime)`または`timesList`のどちらかが必要です。
`untilTime`	`string` (ISO 8601)	予報期間の終了時刻。	はい。`(fromTime, untilTime)`または`timesList`のどちらかが必要です。
`timesList`	`array` of string (ISO 8601)	返したい有効時刻の明示的なリスト。各値は`forecasted_time`に対応します。	はい。`(fromTime, untilTime)`または`timesList`のどちらかが必要です。
`asOf`	`string` (ISO 8601)	基準時刻。この時刻以前に生成されたモデル実行だけを対象にします。	いいえ
`minLeadTime`	`string` (duration)	最小リードタイム（境界を含む）。`"45m"`や`"18h"`のような期間文字列です。`minHorizon`/`maxHorizon`より優先されます。	いいえ
`maxLeadTime`	`string` (duration)	最大リードタイム（境界を含む）。`"45m"`や`"18h"`のような期間文字列です。`minHorizon`/`maxHorizon`より優先されます。	いいえ
`minHorizon`	`integer`	非推奨（`minLeadTime`を使ってください）。時間単位の最小リードタイム（境界を含む）。	いいえ
`maxHorizon`	`integer`	非推奨（`maxLeadTime`を使ってください）。時間単位の最大リードタイム（境界を含む）。	いいえ
`coordinates`	`array` of `coordinate`	地理座標のリスト。`grid`を指定する場合は任意で、両方を同時に送ることもできます。	はい。`coordinates`または`grid`の少なくとも一方が必要です。
`grid`	`grid` object	規則的な長方形領域です。 GribStreamは指定された境界内のすべての点を、指定した空間`step`で返します。 `coordinates`と一緒に使うこともできます。	はい。`coordinates`または`grid`の少なくとも一方が必要です。
`variables`	`array` of `variable`	取得する気象変数のリスト。	はい
`expressions`	`array` of `expression`	リクエストで指定した変数からGribStream側で計算される列。各項目は、指定した`alias`を列名として独立した列で返されます。詳しくは計算式のドキュメントを参照してください。	いいえ
`filter`	`filter` object	すべての`expressions`を評価した後に適用されるtrue/false条件です。単一の`expression`文字列を含める必要があります。計算式の結果が`false`になる行はレスポンスから除外されます。	いいえ
`members`	`array` of integer	アンサンブルデータセット（`gefsatmos`、`ifsenfo`、`ifswaef`など）では、レスポンスに含めるアンサンブルメンバーを選択します。例: `"members": [2,3,4]`。デフォルトは`[0]`で、通常は制御メンバーであるメンバー0だけを返します。	いいえ（アンサンブルデータセットのみ）

注: 対象時刻は、範囲(fromTime, untilTime)またはtimesListで指定する必要があります。

座標オブジェクト

フィールド	型	説明	必須
`lat`	`float`	座標の緯度。	はい
`lon`	`float`	座標の経度。	はい
`name`	`string`	座標に付ける任意の名前。地点を識別しやすいよう、レスポンスにも返されます。	いいえ

格子オブジェクト

フィールド	型	説明	必須
`minLatitude`	number	南側の境界 (°N)	はい
`maxLatitude`	number	北側の境界 (°N)	はい
`minLongitude`	number	西側の境界 (°E)	はい
`maxLongitude`	number	東側の境界 (°E)	はい
`step`	number	十進度で指定する解像度。	はい

変数オブジェクト

name、level、infoの3つで、正確な気象変数セレクタを構成します。これらの値はカタログまたはモデルページからそのままコピーしてください。表示用のラベルではなく、API識別子です。

各モデルで利用できるパラメータの完全なリストを確認してください。

フィールド	型	説明	必須
`name`	`string`	カタログにある正確な気象パラメータコード（例: 気温なら`"TMP"`）。翻訳しないでください。	はい
`level`	`string`	カタログにある正確な大気レベルまたは地表面レベル（例: `"2 m above ground"`）。	はい
`info`	`string`	同じ`name`と`level`を持つパラメータがモデル内に複数ある場合に使う、カタログ上の正確な区別子。カタログの値が空の場合だけ空にしてください。	いいえ
`alias`	`string`	変数に付ける任意の`alias`。指定すると、この`alias`がレスポンスの列ヘッダーとして使われます。	いいえ

計算式オブジェクト

フィールド	型	説明	必須
`expression`	`string`	計算列を作成します。選択したすべての変数は`alias`で参照できます。詳しくは計算式のドキュメントを参照してください。	はい
`alias`	`string`	この計算結果に対してレスポンスで使われる列名。	はい

絞り込みオブジェクト

フィールド	型	説明	必須
`expression`	string	`expressions`と同じDSLで書くtrue/false式です。リクエスト本文内で先に定義した`alias`を参照できます。	はい

リクエスト例

POST https://gribstream.com/api/v2/hrrr/timeseries
Content-Type: application/json
Accept-Encoding: gzip
Authorization: Bearer <token>
リクエスト本文:
{
    "fromTime": "2024-09-10T00:00:00Z",
    "untilTime": "2024-09-10T10:00:00Z",
    "asOf": "2024-09-10T05:00:00Z",
    "minLeadTime": "1h",
    "maxLeadTime": "48h",
    "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
    "variables": [
        { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
        { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
    ],
    "expressions": [
        { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
        { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
    ]
}

レスポンス例

レスポンス形式はAcceptヘッダーで決まります。APIは3つの形式をサポートしています:

Accept: text/csv - レスポンスは予報データを含むCSVファイルです。
Accept: application/json - レスポンスは単一のJSON配列で、各要素はJSONオブジェクトです。
Accept: application/ndjson - レスポンスは改行区切りJSON（NDJSON）で、1行に1つのJSONオブジェクトが入ります。

Accept-Encoding: gzipヘッダーを含めると、レスポンスはgzip圧縮されます。

注: レスポンスは厳密には順序保証されません。

CSVレスポンス例

forecasted_at,forecasted_time,lat,lon,name,uwind,vwind,wind_direction,wind_magnitude
2024-09-10T02:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.1213,1.7680,256,7.3375
2024-09-10T05:00:00Z,2024-09-10T08:00:00Z,40.7306,-73.9352,New York City,5.2585,-1.1512,282,5.3831
2024-09-10T01:00:00Z,2024-09-10T02:00:00Z,40.7306,-73.9352,New York City,8.1815,1.6363,258,8.3435
2024-09-10T05:00:00Z,2024-09-10T07:00:00Z,40.7306,-73.9352,New York City,6.9156,-1.4414,281,7.0642
2024-09-10T00:00:00Z,2024-09-10T01:00:00Z,40.7306,-73.9352,New York City,8.0572,2.9389,249,8.5765
2024-09-10T03:00:00Z,2024-09-10T04:00:00Z,40.7306,-73.9352,New York City,6.4841,2.5385,248,6.9633
2024-09-10T05:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.8368,0.1001,269,6.8375
2024-09-10T04:00:00Z,2024-09-10T05:00:00Z,40.7306,-73.9352,New York City,6.4087,3.0921,244,7.1157
2024-09-09T23:00:00Z,2024-09-10T00:00:00Z,40.7306,-73.9352,New York City,6.1795,3.9539,237,7.3362
2024-09-10T05:00:00Z,2024-09-10T09:00:00Z,40.7306,-73.9352,New York City,4.7715,-0.5644,276,4.8047

JSONレスポンス例（JSON配列）

[{"forecasted_at":"2024-09-10T02:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.121286392211914,"vwind":1.7680130004882812,"wind_direction":256,"wind_magnitude":7.337478439477567}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T01:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.057228088378906,"vwind":2.938892364501953,"wind_direction":249,"wind_magnitude":8.576480210336284}
,{"forecasted_at":"2024-09-10T01:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.181510925292969,"vwind":1.6362571716308594,"wind_direction":258,"wind_magnitude":8.34352794400556}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T06:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.836750030517578,"vwind":0.10012435913085938,"wind_direction":269,"wind_magnitude":6.837483152964509}
,{"forecasted_at":"2024-09-09T23:00:00Z","forecasted_time":"2024-09-10T00:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.179473876953125,"vwind":3.953920364379883,"wind_direction":237,"wind_magnitude":7.33616954846356}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.915561676025391,"vwind":-1.4414329528808594,"wind_direction":281,"wind_magnitude":7.064185887458082}
,{"forecasted_at":"2024-09-10T03:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.484088897705078,"vwind":2.538473129272461,"wind_direction":248,"wind_magnitude":6.963279016482147}
,{"forecasted_at":"2024-09-10T04:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.408748626708984,"vwind":3.0920562744140625,"wind_direction":244,"wind_magnitude":7.115677828885149}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":5.258523941040039,"vwind":-1.1512451171875,"wind_direction":282,"wind_magnitude":5.383069696589422}
,{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.771465301513672,"vwind":-0.564422607421875,"wind_direction":276,"wind_magnitude":4.804732459078015}
]

NDJSONレスポンス例（行区切り）

{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.915561676025391,"vwind":-1.4414329528808594,"wind_direction":281,"wind_magnitude":7.064185887458082}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":5.258523941040039,"vwind":-1.1512451171875,"wind_direction":282,"wind_magnitude":5.383069696589422}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.771465301513672,"vwind":-0.564422607421875,"wind_direction":276,"wind_magnitude":4.804732459078015}
{"forecasted_at":"2024-09-10T05:00:00Z","forecasted_time":"2024-09-10T06:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.836750030517578,"vwind":0.10012435913085938,"wind_direction":269,"wind_magnitude":6.837483152964509}
{"forecasted_at":"2024-09-10T03:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.484088897705078,"vwind":2.538473129272461,"wind_direction":248,"wind_magnitude":6.963279016482147}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T01:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.057228088378906,"vwind":2.938892364501953,"wind_direction":249,"wind_magnitude":8.576480210336284}
{"forecasted_at":"2024-09-09T23:00:00Z","forecasted_time":"2024-09-10T00:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.179473876953125,"vwind":3.953920364379883,"wind_direction":237,"wind_magnitude":7.33616954846356}
{"forecasted_at":"2024-09-10T01:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.181510925292969,"vwind":1.6362571716308594,"wind_direction":258,"wind_magnitude":8.34352794400556}
{"forecasted_at":"2024-09-10T04:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.408748626708984,"vwind":3.0920562744140625,"wind_direction":244,"wind_magnitude":7.115677828885149}
{"forecasted_at":"2024-09-10T02:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.121286392211914,"vwind":1.7680130004882812,"wind_direction":256,"wind_magnitude":7.337478439477567}

レスポンス項目:

フィールド	説明
`forecasted_at`	モデル実行時刻。予報が生成または発行された時刻です。
`forecasted_time`	有効時刻。予報が対象とする時刻です。
`lat`	座標の緯度。
`lon`	座標の経度。
`name`	リクエスト内の座標セットに指定した名前。
`uwind` `vwind` `wind_direction` `wind_magnitude`	変数または派生計算式（expression）ごとに1列。変数のデフォルト列名は`[name]\|[level]\|[info]`です。

利用上の注意

すべての時刻はISO 8601形式（例: "2022-08-10T00:00:00Z"）で指定してください。
リードタイムを絞り込むには、minLeadTime/maxLeadTime（推奨）または非推奨のminHorizon/maxHorizon（時間単位）を使います。
少なくとも1つの地点（coordinatesまたはgrid、またはその両方）と、1つの変数を指定する必要があります。
asOfパラメータは、過去のある時点から見えていた予報だけを再現するための基準時刻です。APIはasOf以前に生成されたモデル実行だけを対象にするため、バックテストやシミュレーションで後から発行された予報を誤って使うことを防げます。指定しない場合は、最新の利用可能な予報データが使われます。

認証

Authorizationヘッダーに有効な認証トークンを含める必要があります。トークンを取得するには、してください。

トークンは次のようにリクエストヘッダーに含めます:

Authorization: Bearer <token>

cURLコマンド例

curl -X POST 'https://gribstream.com/api/v2/hrrr/timeseries' \
        -H "Content-Type: application/json" \
        -H "Accept-Encoding: gzip" \
        -H "Authorization: Bearer [API_TOKEN]" \
        -d '{
            "fromTime": "2024-09-10T00:00:00Z",
            "untilTime": "2024-09-10T10:00:00Z",
            "asOf": "2024-09-10T05:00:00Z",
            "minLeadTime": "1h",
            "maxLeadTime": "48h",
            "coordinates": [{ "lat": 40.7306, "lon": -73.9352, "name": "New York City" }],
            "variables": [
              { "name": "UGRD", "level": "1000 mb", "alias": "uwind" },
              { "name": "VGRD", "level": "1000 mb", "alias": "vwind" }
            ],
            "expressions": [
              { "expression": "func.Hypot(uwind, vwind)", "alias": "wind_magnitude" },
              { "expression": "int(270 - func.Atan2(vwind, uwind) * 180 / 3.14159) % 360", "alias": "wind_direction" }
            ]
        }' | gunzip | head -20

このコマンドは予報データを取得し、展開後のレスポンスの最初の20行を出力します。

エラー処理

リクエストに問題がある場合、APIは適切なHTTPステータスコードとエラーメッセージを返します。

よくあるエラーコード

ステータスコード	意味	説明
400 Bad Request	リクエストパラメータが無効です。	必須パラメータが不足している、または値が無効な場合に発生します。
401 Unauthorized	認証に失敗しました。	認証トークンがない、または無効な場合に発生します。
429 Too Many Requests	利用枠を超えました。	利用枠を使い切った場合に発生します。レスポンスには、再試行までの待ち時間を示す`Retry-After`ヘッダーが含まれます。
500 Internal Server Error	サーバー側エラーです。	GribStream側でリクエストの処理中にエラーが発生した場合に返されます。

Runsエンドポイント

指定した時間範囲に含まれるすべてのモデル実行を、座標リストと気象パラメータリストに対して取得します。必要に応じてリードタイム範囲で絞り込めます。

POST https://gribstream.com/api/v2/<model>/runs

名称変更以前は/forecastsでした。旧URLも引き続き動作します。