APIって使ったことある？ #1

こんばんは皆さま。題目について、私は使ったことないです(笑)

ただ、最近国交DPFで利用者APIの提供が開始されて、周りの方々が喜んでいるんですよね。便利だと。
なのに私は、置いてけぼり...

そんなの嫌だ！！！！！私も周りの方々とともに喜び、データで遊んでみたい！！！！！！

ということで、国交DPFの利用者APIの利用に挑戦したいと思います！

▼この記事を読んで分かること

APIとはなにか
利用者APIが利用できるようになるまでの手順
どんな機能があるのか（GraphiQLを利用しながら）

この記事は国交DPFアドベントカレンダー2023 に参加しています。本日6日目です。
これまで、「国交DPFとは」「どんなデータと連携しているのか」「国交DPFの便利な機能」などについて記事が上がっているので、もしまだ見てないよって方は是非ご一読いただければと思います。

APIとは

早速、chatgptに聞いてみましたw

APIとはなんですか？高校生でも分かるように説明してください。

以下、答えです。

APIは、レストランのウェイターのようなものです。
レストランに行って料理を注文するとき、自分で台所に入って料理を作る必要はありません。代わりに、ウェイターが注文を台所に持っていって、料理を取り寄せ、それをあなたのもとに持ってきます。
同様に、APIは異なるソフトウェアプログラムやアプリケーションの間にいるウェイターのようなものです。それらがお互いにコミュニケーションし、情報を共有するのに役立ちますが、各プログラムが具体的にどのように動作するかを知る必要はありません。だから、あなたがウェイターに食べたいものを伝えるように、異なるソフトウェアプログラムはAPIを使ってお互いに「話し合い」、必要なデータを交換します。

国交DPFに置き換えると、国交DPFのユーザーが利用者APIにリクエストを送信すると、APIが国土交通DPFのデータベースに希望のデータを取りに行ってくれるというイメージでしょう。

APIを利用できるようになるまでの手順

では、実際にAPIを使ってみましょう。ということで、まずはアカウント登録！
この手順については国交DPFにキャプチャ付きでとても丁寧に説明されているので、ここでは省略します。

以下のたった2ステップでAPIが利用できるようになります。

ただ、最初からPythonなどのプログラミング言語を用いることって結構レベル高いですよね。
そこで使うのが GraphiQL（グラフィカル） です！！これを使えば、なんとWeb上でAPIを試すことができるんです！

では、早速使ってみましょうか。

GraphiQLでAPIを使ってみる

それでは本日は、GraphiQLを使って、「検索」「カタログ情報の取得」をしてみます。

まずはGraphiQLを開きます。

検索（search）

検索ワードや標準的な属性情報を元にデータのメタ情報を取得できるそうです。

やってみましょう。
例えば、「橋梁」というキーワード検索結果のうち上位5件の情報(id,title)を表示してみます。

query {  
  search(term:"橋梁", phraseMatch:true, first:0, size:5) {  
    totalNumber  
    searchResults {  
      id  
      title  
    }  
  }  
}

上のコードをGrapiQLにペーストし、三角ボタンを押すと右側の画面に結果が出力されました！おお～！

その他、設定できるパラメータはGraphiQL画面右上の「Docs」⇒「Query」から確認できます。

ただ、それぞれのパラメータの意味はここに書かれていないので、「APIドキュメント」を参照する必要がありました。
「トップページ」⇒「開発者向け情報」⇒「APIドキュメント」⇒「APIリファレンス」⇒「検索クエリー仕様」から見れます。

これらを参考に、パラメータを変更してみます！
今回は、「橋梁」というキーワード検索結果を、緯度を使って昇順で並べ替えたときの、上位10件の情報(id,title,lat)を表示してみます。

query {  
  search(term:"橋梁",  
    phraseMatch:true,  
    first:0,  
    size:10,  
    sortAttributeName: "DPF:latitude",  
    sortOrder: "asc",  
) {  
    totalNumber  
    searchResults {  
      id  
      title  
      lat  
    }  
  }  
}

先ほどのコードとは、5,6,7行目を変更したのですが、望み通りの結果が得られました！

カタログ情報取得(dataCatalog)

データカタログ/データセットのメタ情報を取得できるそうです。

やってみましょう。
まずはカタログIDというものが分からないので、全てのカタログのIDを確認します。

query {  
  dataCatalog(IDs: null) {  
    id  
    title  
  }  
}

これをGraphiQLで実行すると、例えば「社会資本情報プラットフォーム」は「ipf」というIDを持っていることが分かりました。

そこで、社会資本情報プラットフォームが持つ各データセットの情報（id,title,データ数,データセットの最新更新日）を表示してみます！

query {  
  dataCatalog(IDs: [ "ipf" ]) {  
    datasets {  
      id  
      title  
      data_count  
      modified  
    }  
  }  
}

おお～～～！！！出ました！！！

ちなみに、データセットのパラメータについては、「APIドキュメント」⇒「カタログとメタ情報」⇒「DatasetInfoClass」で確認できました。
（APIドキュメントのどこに、求めているパラメータ情報が載っているのか把握するのが、最初大変ですね。。）

締め

ということで、皆さまお疲れ様でした。（私もお疲れ様。）
最初やり方に慣れるまでは大変そうですが、Web上でこんなにサクッとAPIを利用できるとは正直思っていませんでした！パラメータなど使いこなせれば、もっと色んな活用ができそうな予感がします！

明日も 「GraphiQLでAPIを使ってみる」 の続きをしてみる予定です。
ファイルのダウンロード URLを取得したり、都道府県コードを取得したりと、まだまだ色んな使い方ができるらしいので。

それでは、また明日もお会いできることを楽しみにしています！