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

Timeseriesエンドポイント

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

APIは各時刻について、条件に合う中で最も短いリードタイムの予報値を返します。つまり、リクエストのフィルタで許可される最も新しいモデル実行からの値を受け取ります。これは通常、分析や運用で最も使いやすい予報です。データ分析では、こうした値を「最良予報」または「現在に近い予報系列」と呼ぶことがあります。

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

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

利用可能なモデルとデータセット

モデルカタログで、対応データセットの最新一覧、APIで使用する正確なコード、パラメータ、レベル、対象領域を確認できます。上記のパスにある<model>にはデータセットコードを指定してください。

リクエストヘッダー

ヘッダー	値	説明
`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`の少なくとも一方が必要です。
`includeMetadata`	`string[]`	timeseriesとrunsの任意配列です。native_coordinateでnative_latとnative_lon、index_updated_atでindex_updated_atを追加でき、両方も指定できます。気象変数の追加クレジットはかかりません。	いいえ
`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で指定する必要があります。

座標オブジェクト

フィールド	型	説明	必須
`native_lat`, `native_lon`	latとlonはリクエストした位置を保持します。native_latとnative_lonは選択されたセルの中心を示し、その位置の各行に繰り返し返されます。ネイティブ経度はグリッドの表記規則に従います。例えば286°と−74°は同じ経度です。
`index_updated_at`	インデックス行の最終更新時刻（UTC ISO 8601）。index_updated_atをリクエストした場合に含まれます。
`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は4つの形式をサポートしています:

Accept: text/csv - レスポンスは予報データを含むCSVファイルです。
Accept: application/json - レスポンスは単一のJSON配列で、各要素はJSONオブジェクトです。
Accept: application/ndjson - レスポンスは改行区切りJSON（NDJSON）で、1行に1つのJSONオブジェクトが入ります。
Accept: application/vnd.apache.parquet - レスポンスは型付きのZSTD圧縮Parquetファイルです。application/x-parquetとapplication/parquetもaliasとして使用できます。

Parquetはバイナリ形式です。ターミナルに表示せず、ファイルに保存してください。動的な列は型とnull許容性を維持し、時刻列にはタイムゾーン情報を持たない秒精度のUTC値が格納されます。

大きな結果では、?delivery=url&format=csv、json、ndjson、またはparquetを追加し、Accept: application/jsonを送信します。リクエスト本文は変わらず、APIはファイルのメタデータと有効期間の短い署名付きダウンロードURLを返します。これらのパラメータを省略すると、すべての形式で通常のインラインレスポンスが維持されます。

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`	有効時刻。予報が対象とする時刻です。
`native_lat`, `native_lon`	latとlonはリクエストした位置を保持します。native_latとnative_lonは選択されたセルの中心を示し、その位置の各行に繰り返し返されます。ネイティブ経度はグリッドの表記規則に従います。例えば286°と−74°は同じ経度です。
`index_updated_at`	インデックス行の最終更新時刻（UTC ISO 8601）。index_updated_atをリクエストした場合に含まれます。
`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以前に生成されたモデル実行だけを対象にします。ただし、選択されたデータがその実時刻にGribStreamで既に利用可能だったことを示すものではありません。指定しない場合は、最新の利用可能な予報データが使われます。

認証

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も引き続き動作します。

利用可能なモデルとデータセット

モデルカタログで、対応データセットの最新一覧、APIで使用する正確なコード、パラメータ、レベル、対象領域を確認できます。上記のパスにある<model>にはデータセットコードを指定してください。

リクエストヘッダー

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

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

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

パラメータ	型	説明	必須
`forecastedFrom`	`string` (ISO 8601)	最も早いモデル実行時刻。	はい。`(forecastedFrom, forecastedUntil)`または`timesList`のどちらかが必要です。
`forecastedUntil`	`string` (ISO 8601)	最も遅いモデル実行時刻。	はい。`(forecastedFrom, forecastedUntil)`または`timesList`のどちらかが必要です。
`timesList`	`array` of string (ISO 8601)	モデル実行時刻の明示的なリスト。各値は`forecasted_at`に対応します。	はい。`(forecastedFrom, forecastedUntil)`または`timesList`のどちらかが必要です。
`minLeadTime`	`string` (duration)	最小リードタイム（境界を含む）。`"45m"`や`"18h"`のような期間文字列です。`minHorizon`/`maxHorizon`より優先されます。	いいえ
`maxLeadTime`	`string` (duration)	最大リードタイム（境界を含む）。`"45m"`や`"18h"`のような期間文字列です。`minHorizon`/`maxHorizon`より優先されます。	いいえ
`minHorizon`	`integer`	非推奨（`minLeadTime`を使ってください）。時間単位の最小リードタイム（境界を含む）。	いいえ
`maxHorizon`	`integer`	非推奨（`maxLeadTime`を使ってください）。時間単位の最大リードタイム（境界を含む）。	いいえ
`coordinates`	`array` of `coordinate`	地理座標のリスト。	はい。`coordinates`または`grid`の少なくとも一方が必要です。
`grid`	`grid` object	規則的な長方形領域です。 GribStreamは指定された境界内のすべての点を、指定した空間`step`で返します。 `coordinates`と一緒に使うこともできます。	はい。`coordinates`または`grid`の少なくとも一方が必要です。
`includeMetadata`	`string[]`	timeseriesとrunsの任意配列です。native_coordinateでnative_latとnative_lon、index_updated_atでindex_updated_atを追加でき、両方も指定できます。気象変数の追加クレジットはかかりません。	いいえ
`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だけを返します。	いいえ（アンサンブルデータセットのみ）

注: 対象のモデル実行時刻は、範囲(forecastedFrom, forecastedUntil)またはtimesListで指定する必要があります。

座標オブジェクト

フィールド	型	説明	必須
`native_lat`, `native_lon`	latとlonはリクエストした位置を保持します。native_latとnative_lonは選択されたセルの中心を示し、その位置の各行に繰り返し返されます。ネイティブ経度はグリッドの表記規則に従います。例えば286°と−74°は同じ経度です。
`index_updated_at`	インデックス行の最終更新時刻（UTC ISO 8601）。index_updated_atをリクエストした場合に含まれます。
`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/runs
Content-Type: application/json
Accept-Encoding: gzip
Authorization: Bearer <token>
リクエスト本文:
{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T00: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は4つの形式をサポートしています:

Accept: text/csv - レスポンスは予報データを含むCSVファイルです。
Accept: application/json - レスポンスは単一のJSON配列で、各要素はオブジェクトです。
Accept: application/ndjson - レスポンスは改行区切りJSON（NDJSON）で、1行に1つのJSONオブジェクトが入ります。
Accept: application/vnd.apache.parquet - レスポンスは型付きのZSTD圧縮Parquetファイルです。application/x-parquetとapplication/parquetもaliasとして使用できます。

Parquetはバイナリ形式です。ターミナルに表示せず、ファイルに保存してください。動的な列は型とnull許容性を維持し、時刻列にはタイムゾーン情報を持たない秒精度のUTC値が格納されます。

大きな結果では、?delivery=url&format=csv、json、ndjson、またはparquetを追加し、Accept: application/jsonを送信します。リクエスト本文は変わらず、APIはファイルのメタデータと有効期間の短い署名付きダウンロードURLを返します。これらのパラメータを省略すると、すべての形式で通常のインラインレスポンスが維持されます。

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

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

CSVレスポンス例

forecasted_at,forecasted_time,lat,lon,name,uwind,vwind,wind_direction,wind_magnitude
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-10T00:00:00Z,2024-09-11T02:00:00Z,40.7306,-73.9352,New York City,2.3471,-5.2970,336,5.7937
2024-09-10T00:00:00Z,2024-09-10T03:00:00Z,40.7306,-73.9352,New York City,7.2268,1.7030,256,7.4247
2024-09-10T00:00:00Z,2024-09-11T06:00:00Z,40.7306,-73.9352,New York City,-2.9925,-5.0025,30,5.8292
2024-09-10T00:00:00Z,2024-09-11T07:00:00Z,40.7306,-73.9352,New York City,-2.9643,-4.9196,31,5.7437
2024-09-10T00:00:00Z,2024-09-10T12:00:00Z,40.7306,-73.9352,New York City,4.7834,-4.3696,312,6.4787
2024-09-10T00:00:00Z,2024-09-10T10:00:00Z,40.7306,-73.9352,New York City,7.2718,0.5647,265,7.2937
2024-09-10T00:00:00Z,2024-09-11T10:00:00Z,40.7306,-73.9352,New York City,-2.9361,-4.5728,32,5.4343
2024-09-10T00:00:00Z,2024-09-11T05:00:00Z,40.7306,-73.9352,New York City,-3.1221,-5.8816,27,6.6589
2024-09-10T00:00:00Z,2024-09-10T06:00:00Z,40.7306,-73.9352,New York City,6.6521,1.6799,255,6.8610
2024-09-10T00:00:00Z,2024-09-11T00:00:00Z,40.7306,-73.9352,New York City,3.2101,-3.3758,316,4.6584
2024-09-10T00:00:00Z,2024-09-10T11:00:00Z,40.7306,-73.9352,New York City,6.9390,-2.4367,289,7.3544
...

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

[{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.078826904296875,"vwind":2.4223251342773438,"wind_direction":251,"wind_magnitude":7.481807896300802}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T07:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.181903839111328,"vwind":2.596050262451172,"wind_direction":247,"wind_magnitude":6.704879718622265}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-11T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":-2.627544403076172,"vwind":-5.187816619873047,"wind_direction":26,"wind_magnitude":5.815275648803582}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T08:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.091346740722656,"vwind":2.6632766723632812,"wind_direction":249,"wind_magnitude":7.5749746686515245}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.889509201049805,"vwind":2.7773094177246094,"wind_direction":248,"wind_magnitude":7.428242364996697}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.226800918579102,"vwind":1.7029743194580078,"wind_direction":256,"wind_magnitude":7.424740604863526}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T10:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.271799087524414,"vwind":0.5646705627441406,"wind_direction":265,"wind_magnitude":7.2936900683913555}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T12:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.783409118652344,"vwind":-4.369564056396484,"wind_direction":312,"wind_magnitude":6.4787416092446914}
,{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T05:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.676166534423828,"vwind":2.414224624633789,"wind_direction":252,"wind_magnitude":8.046863563053401}
,{"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}
...
]

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

{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T03:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":7.226800918579102,"vwind":1.7029743194580078,"wind_direction":256,"wind_magnitude":7.424740604863526}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T17:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.3053665161132812,"vwind":-3.231029510498047,"wind_direction":324,"wind_magnitude":3.969164455061737}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T19:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.7580318450927734,"vwind":-2.8487396240234375,"wind_direction":328,"wind_magnitude":3.3475354238366912}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T16:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.373655319213867,"vwind":-3.552021026611328,"wind_direction":326,"wind_magnitude":4.272129790622153}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T20:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.9354515075683594,"vwind":-2.271472930908203,"wind_direction":319,"wind_magnitude":2.9842187945922025}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T02:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":8.008834838867188,"vwind":1.1038799285888672,"wind_direction":262,"wind_magnitude":8.084552329782657}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T12:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":4.783409118652344,"vwind":-4.369564056396484,"wind_direction":312,"wind_magnitude":6.4787416092446914}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T04:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":6.889509201049805,"vwind":2.7773094177246094,"wind_direction":248,"wind_magnitude":7.428242364996697}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T13:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":2.683929443359375,"vwind":-4.015068054199219,"wind_direction":326,"wind_magnitude":4.829518478770162}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T18:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.8502693176269531,"vwind":-3.0554637908935547,"wind_direction":328,"wind_magnitude":3.5720240096076235}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-11T09:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":-2.627544403076172,"vwind":-5.187816619873047,"wind_direction":26,"wind_magnitude":5.815275648803582}
{"forecasted_at":"2024-09-10T00:00:00Z","forecasted_time":"2024-09-10T14:00:00Z","lat":40.7306,"lon":-73.9352,"name":"New York City","uwind":1.9734878540039062,"vwind":-4.105434417724609,"wind_direction":334,"wind_magnitude":4.555134034047598}
...

レスポンス項目:

フィールド	説明
`forecasted_at`	モデル実行時刻。予報が生成または発行された時刻です。
`forecasted_time`	有効時刻。予報が対象とする時刻です。
`native_lat`, `native_lon`	latとlonはリクエストした位置を保持します。native_latとnative_lonは選択されたセルの中心を示し、その位置の各行に繰り返し返されます。ネイティブ経度はグリッドの表記規則に従います。例えば286°と−74°は同じ経度です。
`index_updated_at`	インデックス行の最終更新時刻（UTC ISO 8601）。index_updated_atをリクエストした場合に含まれます。
`lat`	座標の緯度。
`lon`	座標の経度。
`name`	リクエスト内の座標セットに指定した名前。
`uwind` `vwind` `wind_direction` `wind_magnitude`	変数または派生計算式ごとに1列。変数のデフォルト列名は`[name]\|[level]\|[info]`です。

利用上の注意

すべての時刻はISO 8601形式（例: "2022-08-10T00:00:00Z"）で指定してください。
リードタイムを絞り込むには、minLeadTime/maxLeadTime（推奨）または非推奨のminHorizon/maxHorizon（時間単位）を使います。
少なくとも1つの地点（coordinatesまたはgrid、またはその両方）と、1つの変数を指定する必要があります。

認証

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

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

Authorization: Bearer <token>

cURLコマンド例

  curl -X POST 'https://gribstream.com/api/v2/hrrr/runs' \
-H "Content-Type: application/json" \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer [API_TOKEN]" \
-d '{
    "forecastedFrom": "2024-09-10T00:00:00Z",
    "forecastedUntil": "2024-09-10T00: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側でリクエストの処理中にエラーが発生した場合に返されます。

ネイティブグリッド座標

境界を含む矩形内の全ネイティブ緯度・経度ペアを返します。4つの境界はすべて必須で、minLatはmaxLat以下にします。経度は−180..180または0..360に対応し、減少する経度境界は端をまたぎます。ページ分割はありません。返されたlat/lonを気象リクエストのcoordinatesにコピーできます。

GET https://gribstream.com/api/v2/<dataset>/native-coordinates

リクエストヘッダー

ヘッダー	値	説明
`Accept`	`text/csv application/json application/ndjson application/vnd.apache.parquet`	形式を選択します。未指定または未対応の値はCSVになります。
`Accept-Encoding`	`gzip`	任意。圧縮レスポンスを要求します。
`Authorization`	`Bearer <token>`	登録済みAPIトークンが必要です。

クエリパラメータ

パラメータ	型	説明	必須
`minLat`	`number`	南側の緯度境界（境界を含む）。 `-90..90`	はい
`maxLat`	`number`	北側の緯度境界（境界を含む）。 `-90..90`	はい
`minLon`	`number`	西側の経度境界（境界を含む）。 `-180..360`	はい
`maxLon`	`number`	東側の経度境界（境界を含む）。 `-180..360`	はい

リクエスト例

curl --get 'https://gribstream.com/api/v2/gfs/native-coordinates' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Accept: application/json' \
  --data-urlencode 'minLat=40.7' \
  --data-urlencode 'maxLat=40.8' \
  --data-urlencode 'minLon=-74.1' \
  --data-urlencode 'maxLon=-73.9'

レスポンス例

既定はCSVです。Acceptにapplication/jsonを指定すると配列、application/ndjson（またはapplication/x-ndjson）でJSON Lines、application/vnd.apache.parquetでParquetになります。全形式ともlatとlonだけを含みます。グリッド仕様は無料のカタログ詳細で取得できます。delivery=urlは気象クエリ専用です。

CSVレスポンス例

lat,lon
40.75,286

JSONレスポンス例

[
  {"lat": 40.75, "lon": 286}
]

JSON Linesレスポンス例

{"lat":40.75,"lon":286}

Parquetレスポンス例

Parquetはバイナリ形式です。ファイルに保存してください。列はlat（DOUBLE）とlon（DOUBLE）のみで、1行につき1座標ペアです。

curl --get 'https://gribstream.com/api/v2/gfs/native-coordinates' \
  -H 'Authorization: Bearer [API_TOKEN]' \
  -H 'Accept: application/vnd.apache.parquet' \
  --data-urlencode 'minLat=40.7' \
  --data-urlencode 'maxLat=40.8' \
  --data-urlencode 'minLon=-74.1' \
  --data-urlencode 'maxLon=-73.9' \
  --output native-coordinates.parquet

レスポンスフィールド

フィールド	説明
`lat, lon`	ネイティブセル中心の緯度・経度。

利用上の注意

ネイティブ経度はグリッドの表記規則に従います。例えば286°と−74°は同じ経度です。

登録済みトークンが必要です。500座標ごとに1クレジット（切り上げ）で、1日付・1気象パラメータと同じ料金です。空の矩形は無料ですが、無料取得枠はありません。残量がない場合は429とRetry-Afterを返します。

クォータでストリームが停止する場合があり、受理されたリクエストごとに最大1追加クレジット（500座標）まで超過できます。HTTP 200の有効なレスポンスを保ち、CSVとJSON Linesは最終行で終了、JSONは配列を閉じ、Parquetはファイルを完成させます。統計や完了フラグは追加しません。

衛星画像には地球の外側を見ているピクセルも含まれます。地理的な位置を持つピクセルだけを返します。グリッド座標はセル中心を示すもので、気象値の有無を示しません。AICON座標の量子化誤差は0.5 m未満です。

エラーコード

ステータス	説明
`400 Bad Request`	矩形境界がない、または不正。ページ分割フィールドは未対応。
`401 Unauthorized`	トークンがない、または不正。
`403 Forbidden`	座標一覧には登録済みトークンが必要。
`404 Not Found`	不明なデータセット。
`429 Too Many Requests`	クォータなし。Retry-Afterに従ってください。
`501 Not Implemented`	ネイティブ形状が未対応。
`503 Service Unavailable`	座標データを一時的に取得できません。

カタログAPIリファレンス · OpenAPI

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

Timeseriesエンドポイント

利用可能なモデルとデータセット

リクエストヘッダー

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

座標オブジェクト

格子オブジェクト

変数オブジェクト

計算式オブジェクト

絞り込みオブジェクト

リクエスト例

レスポンス例

CSVレスポンス例

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

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

利用上の注意

認証

cURLコマンド例

エラー処理

よくあるエラーコード

Runsエンドポイント

利用可能なモデルとデータセット

リクエストヘッダー

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

座標オブジェクト

格子オブジェクト

変数オブジェクト

計算式オブジェクト

絞り込みオブジェクト

リクエスト例

レスポンス例

CSVレスポンス例

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

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

利用上の注意

認証

cURLコマンド例

エラー処理

よくあるエラーコード

ネイティブグリッド座標

リクエストヘッダー

クエリパラメータ

リクエスト例

レスポンス例

CSVレスポンス例

JSONレスポンス例

JSON Linesレスポンス例

Parquetレスポンス例

レスポンスフィールド

利用上の注意

エラーコード

問い合わせ