ジャパンサーチAPIを利用したWebアプリケーション作成チュートリアル
第1章 ジャパンサーチの提供しているAPI
第0節 目的
ジャパンサーチは書籍等分野、文化財分野、メディア芸術分野など、さまざまな分野のデジタルアーカイブと連携して、我が国が保有する多様なコンテンツのメタデータをまとめて検索できる「国の分野横断統合ポータル」（https://jpsearch.go.jp/）です。
ジャパンサーチでは二次利用を円滑に行えるよう、Web APIとSPARQL APIを提供しています。 また、より簡単にSPARQLを扱えるよう、SPARQL APIをREST APIのように扱えるSPARQLラッパー(EasySPARQL)も提供しています。
提供されている解説資料と実際のアプリケーション制作の間のギャップを埋めるため、ジャパンサーチからのデータの取得と利用に焦点を絞って、実際にウェブアプリケーションを作成した際に資料のどういった部分を参照したかを紹介します。
第1節 ジャパンサーチの提供しているAPIに関する資料
このチュートリアルでは、主に以下の資料を参照しています。
ジャパンサーチ公式によるAPIの解説資料
- ジャパンサーチWeb API（https://jpsearch.go.jp/api/webapi/）
- ジャパンサーチSPARQL API (https://jpsearch.go.jp/api/sparql-explain/)
- ジャパンサーチEasySPARQL API(https://jpsearch.go.jp/api/sparql-explain/#sec4)
ジャパンサーチ公式によるSPARQL APIの利活用スキーマの解説資料
- 利活用スキーマ概説 (https://jpsearch.go.jp/api/introduction/)
神崎正英先生による、SPARQLエンドポイントの利活用事例や補足説明
- ジャパンサーチ非公式サポートページ(https://www.kanzaki.com/works/ld/jpsearch/)
（参考）ジャパンサーチの全体構成 （開発者による記事）
- ジャパンサーチのシステム・アーキテクチャ(http://www.arg.ne.jp/node/9738)
第2節 ジャパンサーチの提供しているAPIの特徴
| Web API | Easy SPARQL | SPARQL | |
| メタデータの構造化 | △ | ◎ | ◎ |
| 応答速度 | ◎ | 〇 | ×～〇(※クエリ次第) |
| クエリの自由度 | 〇 | △ | ◎ |
| 取得可能な形式 | json | json,xml | json,xml,csv,ttl等 |
| 習得しやすさ | 〇 | ◎ | △ |
ジャパンサーチの提供するAPIには複雑さや自由度にトレードオフがあります。各APIを使いながらそれぞれの特徴を見ていきます。
第3節 説明のために取り上げるアプリケーション事例
「空から標本資料を見てみよう！(Web API ver)」(https://apitemplate.github.io/jpsapisample/specimenwebapi/)
「空から標本資料を見てみよう！(SPARQL ver)」(https://apitemplate.github.io/jpsapisample/specimen/)
※ソースコードは以下にあります。(https://github.com/apitemplate/jpsapisample/)
作品の概要
国土地理院提供の航空写真APIと、国立科学博物館等からジャパンサーチに提供されている標本資料のメタデータをジャパンサーチのSPARQL APIでマッシュアップし、標本が採集された時期に撮影された航空写真上で、対象の標本を見られるようにした作品です。
作品の画面
この例では、ジャパンサーチのSPARQL APIを利用して「ミカン」を検索し、1975年に採取されたミカン科イヌザンショウの標本を、1975年撮影の航空写真上にマッピングしています。
今回の事例においてジャパンサーチのAPIから取得したい情報の整理
- 要件1. ウェブアプリケーションに組み込んで利用したい
- 要件2. 検索結果をJSON形式で取得したい
- 要件3. 標本資料に限ってメタデータを検索したい
- 要件4. 検索結果から地理情報を取得したい
- 要件5. 検索結果から採集された時間情報を取得したい
ジャパンサーチの各APIを利用してウェブアプリを開発するにあたって、これらの要件を満たすために、ジャパンサーチの解説資料や外部資料をどのように参照し、参考にするとよいかを紹介します。
実装の概要
要件1と要件2を満たすために、AjaxでジャパンサーチのAPIに必要なクエリを送信し、取得した検索結果を画像ビューアであるLeafletを用いて表示した国土地理院の航空写真上にマッピングする静的ページとし、GitHub Pagesによって公開する方針を取りました。
Leafletと国土地理院の航空写真APIの使い方は、
「Leafletと国土地理院のGSIタイルデータを使った地図アプリの作成」(https://qiita.com/mix_dvd/items/81cf41c392a36dbacc15)
等が参考になります。
下に赤字で示したAjaxでAPIから情報を取得するエンドポイントのURLとクエリのパラメータ部分と、検索結果のデータを加工する部分以外のソースコードはWeb API・SPARQL APIとも共通です。
$.ajax({
url:(APIのエンドポイントのURL)
type:'GET',
timeout:10000,
data:{
(クエリのパラメータ部分)
}
}).then(function(data){
(検索結果に対する加工部分)
}
第2章 Web APIの利用
「空から標本資料を見てみよう！」をジャパンサーチのWeb APIを使って作ります。
デモは こちら
ソースコードは こちら
第0節 検索対象となるメタデータの把握
実際にAPIからメタデータを取得する前に、ジャパンサーチにどのようなDBが登録されているか調べてみます。
連携データベースのページ(https://jpsearch.go.jp/database?from=0)を見ると、ジャパンサーチに登録されているデータベースの一覧を見ることができます。
今回は、「要件3. 標本資料に限ってメタデータを検索したい」のために、
サイエンスミュージアムネット(https://jpsearch.go.jp/database/s_net)に注目しました。
URLに含まれる「s_net」がデータベース固有のIDにあたり、これを使って絞り込み検索を行うことができます。
次に、APIから取得できるアイテムのメタデータを見てみます。
Web APIは、ジャパンサーチが保持しているJSON形式のメタデータをそのまま出しているため、提供形式はJSONのみです。
ジャパンサーチWeb APIの解説資料の「概要」を参照しながら、提供されているアイテムのJSONフォーマットを調べてみます。
まず、ジャパンサーチの検索結果から、適当なアイテムを開いてみます。
https://jpsearch.go.jp/item/s_net-2448523
赤い矢印の位置にあるJSONアイコンをクリックすると、ジャパンサーチ上に搭載されているJSON形式のメタデータを参照することができます。また、以下のようにjson拡張子をつけても同様に参照することができます。
https://jpsearch.go.jp/item/s_net-2448523.json
このjsonから、
「要件4. 検索結果から地理情報を取得したい」
に対応する項目はcommon→coordinates→lat,lonにあり、
「要件5. 検索結果から採集された時間情報を取得したい」
に対応する項目（ジャパンサーチ上では記録年月日（始め））は、s_net-43-sにあることが分かります。
第1節 Web APIの利用
サイエンスミュージアムネットの資料をWeb APIを使って検索してみます。
ジャパンサーチWeb APIの解説資料の「4.絞り込み検索」から、特定のデータベースに絞り込んで検索する際のクエリの書き方として以下のような書き方があるとわかります。
「データベースID単位のエンドポイントを利用する場合」
https://jpsearch.go.jp/api/item/search/s_net-default?keyword=ミカン
「横断検索のエンドポイントからデータベースIDを指定する場合」
https://jpsearch.go.jp/api/item/search/jps-cross?f-db=s_net&keyword=ミカン
今回は「データベースID単位のエンドポイントを利用する場合」を使ってみます。
また、ジャパンサーチWeb APIの解説資料の「1.アイテムに対する基本的な検索」から、sizeパラメータを指定することで検索結果の件数を指定できることが分かります。
ajaxを使ってAPIからデータを取得している部分は以下のようになります。
$.ajax({
url:"https://jpsearch.go.jp/api/item/search/s_net-default",//APIのエンドポイントのURL
type:'GET',
data:{
keyword : title,
size: "500"
}
}).then(function(data){ //dataにクエリによる検索結果がJSON形式で入る
//返ってきた検索結果に対する処理
}
titleにはユーザの入力した検索キーワードが入ります。
サービス全体の書き方についてはソースコードのコメントを参考にしてください。
第3章 SPARQL APIの利用
「空から標本資料を見てみよう！」をジャパンサーチのSPARQL APIを使って作ります。
デモは こちら
ソースコードは こちら
第0節 検索対象となるメタデータの把握
第2章と同様にSPARQL APIを利用するにあたって、どのようなメタデータが取得できるのか調べてみます。
ジャパンサーチの検索結果から、第2章と同じアイテムを開いてみます。
https://jpsearch.go.jp/item/s_net-2448523
今回はSPARQLによって取得される利活用フォーマットのメタデータを取得したいので、上図の赤い矢印の、RDFマークをクリックします。
https://jpsearch.go.jp/item/s_net-2448523
のitemをdataに置き換えて
https://jpsearch.go.jp/data/s_net-2448523
としても同様のページが表示されます。
また、以下のようにURLの末尾に取得したい形式の拡張子を付与することや、
https://jpsearch.go.jp/data/s_net-2448523.json
https://jpsearch.go.jp/data/s_net-2448523.rdf
https://jpsearch.go.jp/data/s_net-2448523.ttl
例えばcurlを使った場合、以下のようにリクエストヘッダのAcceptにフォーマットを記述することで、
curl -H 'Accept: application/text/turtle' https://jpsearch.go.jp/data/s\_net-2448523取得したいファイルフォーマットを指定して取得することができます。
これらを利用することで、実際に取得したいメタデータ項目の所在や指定に必要な語彙が分かります。
拡張子による指定については利活用スキーマ概説に記述があり、また、Acceptに記述できる値については、SPARQL 1.1 Protocol W3C Recommendation 21 March 2013に記載があります。
利活用フォーマットのメタデータをブラウザで表示した際のキャプチャ
取得されたメタデータから、今回必要な要件である緯度経度はschema:latitudeとschema:longitudeとしてjps:spatialの下のschema:geoの中にあることが分かります。また、記録年月日はjps:temporalの中のschema:descriptionに入っているようです。
各語彙の説明については、利活用スキーマ概説の1.利活用データのデータモデルを参照することで把握することができます。また、利活用データでは、各データベースから集めたメタデータの値のうち「いつ（時間）」「どこで（場所）」「誰が（人）」に関わる情報をできるだけ正規化し、関連する他のデータのURIにリンクしています。正規化の方法については、利活用スキーマ概説の「利活用データにおける正規化について」に概説しています。
第1節 EasySPARQL API(https://jpsearch.go.jp/rdf/sparql/easy/)の利用
EasySPARQLは、SPARQLをWeb APIのように扱えるAPIです。EasySPARQL APIの解説資料に使い方の説明があります。
例えばキーワード検索はtextに値を入れて
https://jpsearch.go.jp/rdf/sparql/easy/?text=%E3%83%9F%E3%82%AB%E3%83%B3
のように使用したり、エンドポイントをブラウザから開いて、一番下にある検索窓に入れて検索することで使用することができます。
EasySPARQLのブラウザにおける表示
今回のように「ミカン」のようなキーワードによるクエリは返戻に地理情報や時間情報が含まれておらず、また、標本資料以外の資料も含まれていて、そのままでは今回作りたいアプリに使えません。ですが、EasySPARQL APIの生成したクエリから、必要なSPARQLクエリを自分で作るためのヒントを得ることができます。
EasySPARQLを利用して「ミカン」でキーワード検索すると、以下のようなクエリが生成されます。
PREFIX jps: <https://jpsearch.go.jp/term/property#>
PREFIX schema: <http://schema.org/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX type: <https://jpsearch.go.jp/term/type/>
SELECT DISTINCT ?s ?label ?creator ?type WHERE {
?s rdfs:label ?label ; a ?type .
OPTIONAL {?s schema:creator ?creator .}
?s ?p ?value.
FILTER(bif:contains(?value, '"ミカン"')) .
?s jps:sourceInfo ?source .
} LIMIT 200
この生成されたクエリに肉付けする形で、要件を満たすSPARQLクエリを作っていきます。
第2節 SPARQL API(https://jpsearch.go.jp/rdf/sparql/)の利用
アプリに必要なメタデータを検索できるようにSPARQLクエリを作っていきます。
まず、第1節で生成された元となるクエリに、「要件3. 標本資料に限ってメタデータを検索したい」を加えてみます。利活用フォーマットのtypeには「標本」があるので、標本資料に限定したクエリを作ることができます。SPARQLエンドポイント解説資料の「2.4 なに：階層関係を利用した範囲の拡大」を参考にしました。
PREFIX jps: <https://jpsearch.go.jp/term/property#>
PREFIX schema: <http://schema.org/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX type: <https://jpsearch.go.jp/term/type/>
SELECT DISTINCT ?s ?label ?creator ?type WHERE {
?s rdfs:label ?label ; a/rdfs:subClassOf? type:標本.
OPTIONAL {?s schema:creator ?creator .}
?s ?p ?value.
FILTER(bif:contains(?value, '"ミカン"')) .
?s jps:sourceInfo ?source .
} LIMIT 500
赤字が変更箇所です。このクエリで検索すると、標本資料だけがヒットするようになります。
次に、「要件4. 検索結果から地理情報を取得したい」を加えます。作成者(creator)は不要で、代わりに緯度経度情報(schema:latitude とschema:longitude)を入れたいので、SPARQLエンドポイント解説資料の、「2.2 どこ：位置情報とGeohash」を参考にクエリを修正しました。
PREFIX jps: <https://jpsearch.go.jp/term/property#>
PREFIX schema: <http://schema.org/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX type: <https://jpsearch.go.jp/term/type/>
SELECT ?s ?label ?lat ?long WHERE {
?s rdfs:label ?label ; a/rdfs:subClassOf? type:標本.
?s jps:spatial ?place .
?place schema:geo [schema:latitude ?lat; schema:longitude ?long ].
?s ?p ?value.
FILTER(bif:contains(?value, '"ミカン"')) .
?s jps:sourceInfo ?source.
} LIMIT 500
赤字が変更箇所です。このクエリで検索すると、緯度経度が取得できるようになります。
最後に「要件5. 検索結果から採集された時間情報を取得したい」に対応します。利活用フォーマットでは時間情報はjps:temporalに入っているのですが、標本データの記録年月日は、その中のschema:descriptionに入っていることを第0節で確認しました。
PREFIX jps: <https://jpsearch.go.jp/term/property#>
PREFIX schema: <http://schema.org/>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX type: <https://jpsearch.go.jp/term/type/>
SELECT ?s ?label ?lat ?long ?desc WHERE {
?s rdfs:label ?label ; a/rdfs:subClassOf? type:標本.
?s jps:spatial ?place .
?place schema:geo [schema:latitude ?lat; schema:longitude ?long ].
?s schema:description ?value.
FILTER(bif:contains(?value, '"ミカン"')).
?s jps:temporal [schema:description ?desc]
?s jps:sourceInfo ?source.
} LIMIT 500
このクエリによる検索結果をSPARQLエンドポイントから取得してみます。
クエリURLと画面のキャプチャ
緯度も経度も返戻に含まれており、記録年月日もdescriptionに含まれていて、どうやらこれでよさそうです。
意図通りのクエリを作れたので、第2章で使用したAjaxの部分を差し替えます。
var query = "PREFIX jps: <https://jpsearch.go.jp/term/property#> ";
query += " PREFIX schema: <http://schema.org/> ";
query += " PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> ";
query += " PREFIX type: <https://jpsearch.go.jp/term/type/> ";
query += " SELECT ?s ?label ?lat ?long ?desc ";
query += " WHERE { ";
query += " ?s rdfs:label ?label ; a/rdfs:subClassOf? type:標本. ";
query += " ?s jps:spatial ?place . ";
query += " ?place schema:geo [schema:latitude ?lat; schema:longitude ?long ]. ";
query += " ?s schema:description ?value. ";
query += " FILTER(bif:contains(?value, \"\'"+title+"\'\")). ";//titleが検索キーワード
query += " ?s jps:temporal [schema:description ?desc]. ";
query += " ?s jps:sourceInfo ?source. ";
query += " } LIMIT 500";
$.ajax({
url:"https://jpsearch.go.jp/rdf/sparql",//APIのエンドポイントのURL
type:'GET',
timeout:10000,
data:{
query : query,//上で書いたクエリを入れる
format : "json"//返戻をjson形式に指定
}
}).then(function(data){//dataにクエリによる検索結果がJSON形式で入る
//返ってきた検索結果に対する処理
}
以上の流れでジャパンサーチのSPARQL APIを利用してウェブサービスを作ることができました。
第4章 まとめ
同じ機能を別々のAPIを利用して実装した2つのアプリケーションを比較すると、検索時のレスポンスの速さではWeb APIに利があることが分かります。
一方で、データベースを横断して共通のプロパティによる抽出条件の指定が可能な点や取得できる内容・フォーマットの柔軟性においてはSPARQLの方が良さそうです。また、両者から取得できるデータの正規化の程度や方法に差異があります。
作りたい機能に応じて、APIを使い分け、あるいは併用して、皆さんも面白いサービスを作ってみてください！