メインコンテンツまでスキップ

WebSocket v2

リクエスト​

WebSocket wss://{可変}.api.dmdata.jp/v2/websocket

WebSocketを通じて気象庁の発表する電文をリアルタイムに配信します。

WebSocketプロトコル​

WebSocketProtocol dmdata.v2

クエリパラメータ​

パラメータ名必須デフォルト説明
ticketはいString
Socket Start v2により取得したWebSocket接続するためのチケットを指定する

エンドポイント情報​

複数のサーバーを含エンドポイントは死活監視しており、正常なサーバーにランダムに振り分けします。 （※60秒の DNS TTL が存在するため、即座の切り替えを保証するものではありません。）

地理・冗長化を目的として、Socket Start の URL情報 を使用せず下記の エンドポイントを使用することができます。

  • ws.api.dmdata.jp - Tokyo and Osaka
    東京・大阪のレイテンシ分配エンドポイント
    • ws-tokyo.api.dmdata.jp - Tokyo Region
      東京エンドポイント
      • ws001.api.dmdata.jp - AWS apne1-az4
      • ws002.api.dmdata.jp - AWS apne1-az1
    • ws-osaka.api.dmdata.jp - Osaka Region
      大阪エンドポイント
      • ws003.api.dmdata.jp - AWS apne3-az3
      • ws004.api.dmdata.jp - AWS apne3-az1

定期メンテナンス​

WebSocketサーバーは、おおよそ3ヶ月ごとに接続切断を伴うメンテナンス（サーバー再起動）を行っています。（1つずつ作業を行い、2つ以上のサーバーが同時に再起動することはありません。）

そのため、サーバーから切断された場合の処理は実装する必要があります。

サーバーのメンテナンスについての事前予告は1週間程度前をめどにお知らせします。

その他​

XML電文については圧縮して送信します。WebSocketは実装により圧縮/非圧縮で通信します。

WebSocket接続中に契約を終了すると、その区分の情報はそれ以降配信されなくなり、契約を再開しても新しくWebSocketを開始しない限り配信されません。

WebSocketには同時接続上限があり、それを超えての接続はできません（接続上限を拡張する契約を解除した場合、ランダムに有効接続数まで切断されます）。

ticketは使い捨てですので一度使用した場合、エラーでもそのticketはもう一度使用できません。 また、5分経過すると使えなくなります。

正常にClose処理がなされないWebSocket切断が発生するとサーバー側で切断が検知できなくなり、PingTimeoutが発生し切断処理が実行されるまで、接続数を消費します。

そのため、同時接続数に余裕がなくすぐに再接続を行いたい場合は、Socket Close v2を実行するよう実装する必要があります。

レスポンス​

WebSocketは常にJSONを返答します。

type: start​

WebSocketは接続が成功時に Socket Start v2 で作成した内容を送信します。 　

{
    "type": "start",
    "socketId": 1,
    "classifications": [
        "telegram.weather"
    ],
    "types": ["VPWW54"],
    "test": "including",
    "formats": ["xml", "a/n", "binary"],
    "appName": null,
    "time": "2020-01-01T00:00:00.000Z"
}

type: ping​

WebSocketは接続を維持するためにpingを送信します

{
    "type": "ping",
    "pingId": "012345"
}

このデータを受け取った場合、ユーザーは次のように pong をJSONで返答しなければなりません。

{
    "type": "pong",
    "pingId": "012345"
}

※成形はしなくてよい。

返答しない場合、120秒以内に接続が終了します。

type: pong​

WebSocketは接続を維持するためにユーザーが送信したpingに対してpongを送信します。 ※ユーザーが送信するpingIdは64byteまでの文字列、または送信しなくてもよい。

例: 1​

ユーザー>>>

{
    "type": "ping"
}

WebSocket>>>

{
    "type": "pong"
}

例: 2​

ユーザー>>>

{
    "type": "ping",
    "pingId": "aaaaa"
}

WebSocket>>>

{
    "type": "pong",
    "pingId": "aaaaa"
}

type: data​

気象庁が発表した情報を配信する場合は次のように送信します。 バージョンは予告なく変更する場合があります。

{
    "type": "data",
    "version": "2.0",
    "classification": "telegram.weather",
    "id": "123456789abcdef...",
    "passing": [
        {
            "name": "ftp-01",
            "time": "2020-01-01T00:00:00.100Z"
        },
        {
            "name": "ires-01",
            "time": "2020-01-01T00:00:00.105Z"
        },
        {
            "name": "websocket-01",
            "time": "2020-01-01T00:00:00.120Z"
        }
    ],
    "head": {
    	"type": "VPWW54",
    	"author": "JPTD",
    	"time": "2020-01-01T00:00:00.000Z",
    	"test": false,
    	"xml": true
    },
    "xmlReport": {
    	"control": {
    		"title": "気象警報・注意報（Ｈ２７）",
    		"dateTime": "2020-02-27T00:00:00Z",
    		"status": "通常",
    		"editorialOffice": "気象庁本庁",
    		"publishingOffice": "気象庁予報部"
    	},
    	"head": {
    		"title": "東京都気象警報・注意報",
    		"reportDateTime": "2020-02-27T09:00:00+09:00",
    		"targetDateTime": "2020-02-27T09:00:00+09:00",
    		"eventId": null,
    		"serial": null,
    		"infoType": "発表",
    		"infoKind": "気象警報・注意報",
    		"infoKindVersion": "1.2_1",
    		"headline": "注意報を解除します。"
    	}
    },
    "format": "xml",
    "compression": "gzip",
    "encoding": "base64",
    "body": "H4sIAAAAAAAAA..."
}
フィールド出現説明
typeいつもString
データを示す data で固定
versionいつもString
バージョンを示す、作成処理の変更で予告なく変更となる場合がある
idいつもString
配信データを区別するユニーク384bitハッシュ
classificationいつもString
配信区分により変化。取りうる値は eew.forecast, eew.warning, eew.realtime, telegram.earthquake, telegram.volcano, telegram.weather, telegram.scheduled
passingいつもArray<Object>
通過情報
passing[].nameいつもString
通過場所の名前
passing[].timeいつもISO8601Time
通過した時間
headいつもObject
ヘッダ情報
head.typeいつもString
データ種類コード
head.authorいつもString
発表英字官署名
head.target内容による※1String
対象観測地点コード
head.timeいつもString
基点時刻（ISO8601拡張形式）
head.designationいつもString|Null
指定コード
WMO全球通信システム(GTS)で定義されている符号で、遅延報・訂正報に付加する。通常は Null とする ※4
head.testいつもBoolean
訓練、試験等のテスト等電文かどうかを示す。
注意：XML電文以外のテスト配信は常に false になります。本文中を参照するようにしてください。
head.xml内容による※2Boolean
XML電文かどうかを示す
xmlReportformat=xml または
format=json時		Object
XML電文Control,Head情報
formatいつもString|Null
bodyフィールドの表現形式を示す。xml、a/n、binary は気象庁が定めたフォーマット、json は本サービスが独自に定めたフォーマット
compressionいつもString|Null
bodyフィールドの圧縮形式を示す。gzipまたはzip、非圧縮時はnullを格納する
encodingいつもString|Null
bodyフィールドのエンコーディング形式を示す。base64または、utf-8を格納する
bodyいつもString
本文

※1 将来の予約拡張。
※2 形式は format を参照すること。
※3 compression が、gzip, zip時には常に base64 とする。

※4 指定コードは、3桁の英大文字を使い、下の通りとする

| 内容 | 指定コード | |-:-|-----| | 遅延報 | RRA, RRB, RRC, ... RRX | | 訂正報 | CCA, CCB, CCC, ... CCX | | 修正報 | AAA, AAB, AAC, ... AAX |

RRY, RRZ, CCY, CCZ, AAY, AAZ は、システム障害時等でのみ使用。

電文の検証​

電文の検証は body をencodingでデコードしたのち、SHA384でハッシュ化したものを id と比較検証し、一致すれば正常です。

type: error​

APIは各種エラーを次の通り返答します。

{
    "type": "error",
    "error": "Server error.",
    "code": 4503,
    "close": true
}
フィールド出現説明
typeいつもString
エラーを示す error で固定
errorいつもString
エラーメッセージ
codeいつもInteger
エラーコード、別記参照
closeいつもBoolean
true 時はWebSocketをその時点で終了します
エラーコード説明
4400WebSocket開始時、必要なパラメータが指定されていない場合
4404WebSocket開始時、有効なticketが指定されていない場合
4409WebSocket開始時、接続できる接続数に達している場合
4503サーバー内部エラーでサーバーアプリケーションの再起動を実施する場合
4640ユーザーが Pong を送信したとき、 pingId が一致しなかった場合
4641ユーザーが不正なデータを送信した場合（JSON以外など）
4808ユーザーが明示的にWebSocketを終了するよう操作があった場合
4807ユーザーが接続中の契約区分を解約したときに、ほかに接続中の区分がない場合