公共データポータルのオープンAPIを初めてつなぐとき、何を先に確かめるべきか

公共データポータルとは何で、どこから始めるか

data.go.krは韓国の政府と公共機関が保有するデータを一箇所で開放するサイトです。行政安全部が運営し、根拠法は「公共データの提供および利用活性化に関する法律」です。病院・薬局といった医療機関情報から建築物台帳、行政洞人口、公共交通、気象まで入っています。

提供形態は大きく二つです。ファイルデータ(CSV・SHPなどをダウンロードするもの)とオープンAPI(アドレスで呼び出して受け取るもの)です。ポータルのトップ画面にある人気データ・最新データの領域にも、この二つのタブが並んでいます。後述しますが、この区分は実際の開発でかなり重要です。

始める手順は簡単です。会員登録をし、使いたいデータの詳細ページで利用申請を押し、マイページでサービスキーを受け取ります。多くのAPIは申請後すぐ、または一日以内に承認されます。キーはURLのクエリにserviceKey=として付けます。このときキーに含まれる特殊文字をURLエンコードしないと認証に失敗するので、コード側で必ずエンコードして付けます。

最初の落とし穴 — 知らないパラメータを拒否せず無視する

病院と薬局の位置を地図に載せる道具を作る過程で、健康保険審査評価院の薬局情報サービスをつなぎました。ソウルの分だけ受け取ろうとして地域パラメータを入れたのですが、そこで問題が起きました。

Q0=ソウル特別市を入れて呼ぶと総件数が25,771件で返りました。ソウルの薬局がそれほど多いはずがないのでパラメータをまるごと外して呼び直したところ、やはり25,771件でした。つまりそのパラメータは最初から何もしていなかったのです。

原因はパラメータ名でした。Q0は国立中央医療院が提供する別の薬局APIのものであり、審査評価院の薬局情報サービスはsidoCd(市道コード)を使います。ソウルは110000です。正しく入れて呼び直すと5,883件が返りました。

ここで重要なのは数字の差ではなく、失敗の仕方です。誤ったパラメータを送ったのにサーバーは400も警告も返さず、HTTP 200と正常なJSON構造で応答し、データも本物の薬局レコードでした。範囲がソウルではなく全国だっただけです。ソウルの薬局数を4.4倍に膨らませて受け取りながら、エラー信号を一つも見ていなかったことになります。

この種の失敗はログにも残らず、目でも捕まりません。データを数件開いても形は正常なので違和感がありません。地図に打ってみて、ソウル外の座標が混じっているのに気づく、という具合です。

だから最初の検証は総件数の比較だ

この経験以降、公共データAPIをつなぐときの最初の検証を一つに固定しました。フィルタを外した総件数と入れた総件数を並べて出してみることです。二つが同じなら、そのフィルタは効いていません。

同じやり方で病院APIも確認しました。フィルタなしで呼ぶと79,797件(全国)、sidoCd=110000を入れると19,880件(ソウル)です。値が変わるのでこちらはフィルタが正常に働いています。薬局は同じ値だったので効いていなかったわけです。判定に一分もかかりません。

総件数はたいてい応答のtotalCountフィールドにあり、numOfRows=1で呼んでもその値は全体基準で返ります。ですからデータを一件も受け取らずに総件数だけ比較できます。パイプラインを組む前に、データを一行でも覗く前に、これを先にやります。

同じ原理を他のフィルタにも当てます。市郡区・種別・科目などフィルタを一つ足すたびに総件数が減るかを見ます。減らなければ、そのフィルタは無いのと同じです。

ポータルにあることとAPIで取得できることは別だ

二番目によくずれる地点です。「そのデータはポータルにあります」と「そのデータはAPIで取得できます」は別の言葉です。

地図を一つ作るのに必要だった五つをポータルで実際に検索してみると、はっきり分かれます。病院・薬局・建築物台帳はオープンAPIがあり周期的に呼べますが、行政洞境界と行政洞人口はファイルデータとしてのみ存在します。境界をAPIで検索すると見当違いの結果(干ばつ分析など)が出て、境界ポリゴンのAPIは掛かりません。

この違いがパイプライン設計を決めます。病院・薬局は開閉業が絶えず生じるのでAPIで周期取得するのが正しい。一方で行政洞境界と人口は行政洞の数だけの固定値なので、ファイルを一度受け取って積めば足ります。更新周期の違う資料を同じやり方で扱おうとすると、仕事が無駄に増えます。

そこでデータを選ぶときは「あるか」の次にすぐ「どんな形であるか」を見ます。詳細ページのアドレスがopenapi.doで終わればAPI、fileData.doで終わればファイルです。

複数のデータセットをつなぐ鍵は何か

データを複数受け取れば、結局は突き合わせることになります。医療機関の側でその鍵は療養機号(ykiho)です。健康保険審査評価院が療養機関ごとに付与するコードで、病院APIと薬局APIが同じ体系を使うため、二つのデータセットをそのまま結合できます。

名称や住所で突き合わせようとすると必ず壊れます。同じ機関が表記だけ違って入ってくることが多く(空白の有無など)、住所は道路名と地番が混じります。コードがあるのに文字列でマッチングしないことです。

他の領域でも同じものを探します。建築物側には台帳キーがあり、行政区域には行政洞コードがあります。データセットを受け取る前に「これを何で他とつなぐのか」を先に決めておくと、後で戻る回数が減ります。

実際につなぐときの順序

整理するとこの順序です。第一に、ポータルでデータを探し、詳細ページのアドレスでAPIかファイルかを確かめます。第二に、利用申請のうえサービスキーを受け取り、URLエンコードして呼び出します。第三に、フィルタなしで一度、フィルタを入れて一度呼び、総件数を比べます。同じならパラメータ名が誤っているので、ドキュメントの要求変数表を見直します。

第四に、結合キーを決めます。第五に、更新周期に応じてAPI周期取得とファイル一回積載に経路を分けます。第六に、積載した総件数をどこかに記録しておきます。次に値が大きく変わったとき、源が変わったのか自分の呼び出しが変わったのかを照らす根拠になります。

最後に、公共データは機関ごとに規格がまちまちだという前提で扱います。同じ「薬局情報」でも提供機関が違えばパラメータ名が違い、あるAPIは誤った入力を静かに無視します。ドキュメントは読む、しかし鵜呑みにしない。総件数で確かめる習慣が、結局は時間を節約してくれます。