jartic-traffic-volume

name	jartic-traffic-volume
description	指定の道路・エリアの現在の交通量を JARTIC 交通量 API (国土交通省) から取得する手順。「国道◯号の今の交通量」「◯◯付近の混雑」など、特定の道路や地点の最新交通量を聞かれた際に使う。 地名・道路名を国土地理院ジオコーディングで緯度経度へ変換し、WFS 2.0.0 GetFeature を BBOX と時間コードで叩く。対象は高速自動車国道と一般国道のみで、県道・市道は取得できない。

JARTIC 交通量取得

指定の道路・エリアの現在の交通量を取得する手順。実体は GeoServer の WFS 2.0.0 GetFeature であり、エンドポイントは 1 本のみ。

情報源

• OpenAPI 定義 (非公式): https://github.com/ansanloms/jartic-open-traffic-openapi
• エンドポイント: https://api.jartic-open-traffic.org/geoserver
• 国土地理院住所検索 API (無認証・無料): https://msearch.gsi.go.jp/address-search/AddressSearch
• 国土地理院逆ジオコーディング API (観測点座標→住所の確認用): https://mreversegeocoder.gsi.go.jp/reverse-geocoder/LonLatToAddress?lat=<緯度>&lon=<経度>

全体フロー

1. 道路種別を判定する (高速自動車国道/一般国道)。
2. 位置を解決して BBOX (緯度経度範囲) を組む。
3. 時間コードと様式を決める。
4. GetFeature を叩く。
5. レスポンスを整形して交通量を読む。

1. 道路種別の判定

API は常時観測点に紐づく道路種別でしか道路を区別しない。値は次の 2 種のみ。

道路種別	値	備考
高速自動車国道	1	観測点は全国で数十点と希薄。主要な高速道路の都市近郊は含まれにくい (下記注記)。
一般国道	3	全国に多数。通常はこちらで取得する。

• 県道・都道・市道・私道・農道は対象外であり、取得できない。ユーザの指定がこれらに当たる場合は取得不可と伝える。
• 道路名から高速か一般国道か判別できない場合はユーザに確認する。
• 高速自動車国道 (種別 1) の観測点は全国で約 60 点程度と極端に少なく、国土交通省直轄の一部区間に偏在する。東名・名神・東北道など NEXCO 管理の主要路線の都市近郊はほぼ含まれない。高速の特定地点を指定されても近傍に観測点が無く 0 件になるのが通常であり、その場合の打ち切り・確定の手順は「0 件・エラーの切り分け」を参照する。データが豊富なのは一般国道 (種別 3) の方である。

2. 位置の解決 (BBOX)

緯度経度・BBOX・常時観測点コードを直接渡された場合は、ジオコーディングを省略してそれを使う。地名や道路名しか無い場合は国土地理院でジオコーディングする。

curl -sS -G 'https://msearch.gsi.go.jp/address-search/AddressSearch' \
  --data-urlencode 'q=三軒茶屋'

• レスポンスは Feature の配列。geometry.coordinates は [経度, 緯度] の順 (緯度経度が逆なので注意)。properties.title が地名。
• 候補は先頭を機械的に採用しない。「横浜駅」のように同名地が各地にあり、目的地が配列の後方に来ることがある。title を見て依頼の文脈 (都市・駅・路線) に最も合う候補を選ぶ。判別できなければユーザに確認する。
• インターチェンジ名・施設名 (例: 御殿場インター) は住所検索でヒットしないことがある。その場合は市区町村名など一般的な地名へ読み替えて再検索する。
• 得た点 (経度・緯度) を中心に BBOX を張る。JARTIC の観測点は疎であり、狭すぎる BBOX では 0 件になる。緯度経度 ±0.05 度 (おおむね数 km 四方) 程度の広めから始め、ヒットした観測点の座標を見て目的の道路上の点へ絞り込む。
• BBOX の書式は BBOX(ジオメトリ, 最小経度, 最小緯度, 最大経度, 最大緯度, 'EPSG:4326')。経度が先である。
• 広すぎる BBOX はペイロードサイズ超過エラーになる。狭めるか期間を絞る。
• 重要な限界として、レスポンスの各観測点は常時観測点コードと座標のみを持ち、道路名を含まない。返ってきた点が目的の道路上にあるかは座標から判断する (上記の逆ジオコーディング API で住所を引いて確認する)。逆ジオコーディングは町名までしか返さず、道路の同定は「町名 + 道路の通過ルート知識」による推定になる。提示は断定せず「観測点は◯◯付近にあり、国道◯号上とみられる」の形にする。複数点が返った場合は座標を添えて提示し、特定が難しければユーザに委ねる。
• ヒットが 1 点のみで目的地から数 km 離れている場合は、その点を最寄りとして採用してよいが、目的地からの距離を必ず明示する。より近い点の有無は別系統 (様式 3 の CCTV トラカン) を 1 回照会するにとどめ、無ければその点で確定する。この照会のパラメータは「0 件・エラーの切り分け」節の様式 3 照会の規定 (typeNames のみ変更、他は据え置き) に従う。

3. 時間コードと様式

「現在の交通量」は 5 分間交通量 (様式 1) を既定とする。

様式	typeNames	観測機器	集計単位	検索可能期間
様式 1	t_travospublic_measure_5m	常設トラカン	5 分間交通量	過去 1 か月分
様式 2	t_travospublic_measure_1h	常設トラカン	1 時間交通量	過去 3 か月分
様式 3	t_travospublic_measure_5m_img	CCTV トラカン	5 分間交通量	過去 1 か月分
様式 4	t_travospublic_measure_1h_img	CCTV トラカン	1 時間交通量	過去 3 か月分

時間コードは YYYYMMDDhhmm。5 分値は分を 5 の倍数へ切り捨て、1 時間値は分を 00 へ切り捨てる。現在 (JST) を 5 分単位へ切り捨てた時間コードは次で得る。

TZ=Asia/Tokyo date +%Y%m%d%H%M | awk '{printf "%s%02d\n", substr($0,1,10), int(substr($0,11,2)/5)*5}'

• データには反映ラグがある。実測では JST 17:50 時点で最新の 5 分値は 17:30 (約 20 分前) であり、17:45 はまだ 0 件であった。よって現在時刻ちょうどの時間コードは 0 件になりやすい。
• 手順は「現在を丸めた時間コードで叩き、0 件なら 5 分ずつ (1 時間値なら 1 時間ずつ) 遡る」を基本とする。数スロット遡っても 0 件なら、ラグではなく観測点不在を疑い BBOX を見直す。
• 1 時間値が必要なら様式 2 (t_travospublic_measure_1h) を使い、分を 00 へ切り捨てる。
• 常設トラカン (様式 1) で 0 件のとき CCTV トラカン (様式 3 t_travospublic_measure_5m_img) を試す価値がある。両者は別系統の観測点である。
• 近畿地方整備局の管轄エリアの CCTV トラカンは、当面は様式 3 (5 分間交通量) のみ提供される。

4. リクエスト

${TC} は時間コード、${minLon} 〜 ${maxLat} は BBOX、道路種別=3 は一般国道の例 (高速は 1)。

curl -sS -G 'https://api.jartic-open-traffic.org/geoserver' \
  --data-urlencode 'service=WFS' \
  --data-urlencode 'version=2.0.0' \
  --data-urlencode 'request=GetFeature' \
  --data-urlencode 'typeNames=t_travospublic_measure_5m' \
  --data-urlencode 'srsName=EPSG:4326' \
  --data-urlencode 'outputFormat=application/json' \
  --data-urlencode 'exceptions=application/json' \
  --data-urlencode "cql_filter=道路種別=3 AND 時間コード=${TC} AND BBOX(ジオメトリ,${minLon},${minLat},${maxLon},${maxLat},'EPSG:4326')"

• service version request typeNames srsName outputFormat は必須。exceptions=application/json を付けるとエラーも JSON で返る (未指定時は XML)。
• cql_filter は CQL 文字列。フィールド名と値を 道路種別=3 のように素で書く形式で動作する (OpenAPI 仕様書の "道路種別"='3' のクォート形式も有効)。
• 特定の観測点だけ取りたい場合は BBOX の代わりに 常時観測点コード=01234567 (8 桁 0 埋め) を指定できる。このとき道路種別も不要になる (コードで一意のため)。置換後の完全形は cql_filter=時間コード=${TC} AND 常時観測点コード=03310890。ジオコーディングも省略する。

5. レスポンスの読み方

成功時は GeoJSON の FeatureCollection。features[] の 1 件が 1 観測点である。

• 様式 1・2 の properties は方向別 (上り/下り) × 車種別 (小型/大型/車種判別不能) の交通量を持つ。単位は様式 1 が台/5 分、様式 2 が台/時。
• ある方向の交通量は小型・大型・車種判別不能を足して求める。両方向の合計はさらに上りと下りを足す。様式 1・2 の実キーは 上り・小型交通量 上り・大型交通量 上り・車種判別不能交通量 (下りは 下り・…) であり、上り・小型 のような略記ではない。集計前に features[0].properties の実キーを 1 度確認すると取り違えを防げる。
• 欠測・異常フラグを確認する。上り・欠測/下り・欠測 が "1" なら欠測で、交通量は null になる。停電/ループ異常/超音波異常 が "1" の点も異常である。null や異常値は合計から除くか、注記を添える。
• 時間帯 は hhmm、時間コード は YYYYMMDDhhmm、常時観測点コード で観測点を識別する。座標は geometry.coordinates ([経度, 緯度])。
• 様式 3・4 (CCTV) は項目名が異なり、上り・自動車交通量（集計値） などを持つ。カメラプリセット位置 が "1" (異常) の場合は交通量が null になる。

0 件・エラーの切り分け

• 0 件時の対処は次の順で行う: (1) 時間コードを遡る (最大 4 スロット = 20 分。実測ラグをカバーする) → (2) 種別 3 で切り分け照会 → (3) BBOX を系列で拡大 → (4) CCTV (様式 3) を 1 回 → (5) 打ち切り。各段は直前の段で確定したパラメータ (時間コード・BBOX・道路種別) を引き継ぎ、その段で変えるものだけを変える。CCTV 照会で変えるのは typeNames のみ。道路種別は元の照会と同じ値に据え置き、BBOX と時間コードは「直前に実施した (またはヒットが確認できた) 照会と同じ値」を使う。0 件フローから来た場合は最大まで広げた BBOX、1 点ヒットの近傍確認から来た場合は元の BBOX がそれに当たる。
• 0 件: features が空配列で crs が null。一般国道 (種別 3) なら時間コードを遡る、BBOX を少し広げる、で対処する。
• 高速 (種別 1) の 0 件は観測点不在が大半。BBOX は ±0.05 → ±0.10 → ±0.15 度の系列で広げ、CCTV (様式 3) も 1 回試して 0 件なら打ち切る。広域へ無限に広げない。
• 打ち切って「取得不可」で終える場合、同じ BBOX で取れた一般国道 (種別 3) の値があれば「参考値 (別道路)」と明示して添えてよい。その際も観測時刻・観測点・道路種別の注記を省かない。
• 0 件が「観測点不在」か「API・時間コードの不備」かを切り分けるには、同じ BBOX・時間コードで一般国道 (種別 3) を 1 回照会する。時間コードは、(1) の遡りを実施済みなら「遡った中で最も古いスロット」(反映ラグの影響が最小のもの) を使う。点が返れば API と時間コードは正常であり、種別 1 の 0 件は観測点不在と確定できる。これを根拠に「API が高速を提供していない」ではなく「その地点に高速の観測点が無い」と答える。
• HTTP 400 で {"message": ...}: 必須パラメータ (typeNames など) の欠落。
• HTTP 200 で {"version": ..., "exceptions": [...]}: typeNames などの値が不正 (exceptions=application/json 指定時)。
• {"errorMessage": ..., "errorType": ...}: ペイロードサイズ超過。BBOX か期間を狭める。

注意

• 各種トラカンは観測条件により精度が大きく変動する。気象や機器故障で不正確なデータが含まれることがあり、国土交通省による正式な交通量の調査結果ではない。職員によるデータチェックも実施されていない。
• 本 API の利用には「交通量 API 利用規約」への事前同意が必要である。
• 取得値を提示する際は観測時刻 (時間コード) と観測点を必ず添え、欠測・異常があればその旨を明示する。推測で値を埋めない。