概要


※検索結果の全件取得については1.3.2 検索結果が2000件以上の場合(全件取得)をご参照ください。

ジャパンサーチでは、SPARQL APIのほかに、登録されているメタデータを高速に検索・取得するための簡易的なWeb API機能を提供しています。

個別のメタデータはJSON形式で取得することができます。アイテムに限り、ジャパンサーチのメタデータ詳細画面のURLにJSON拡張子を付与すると簡易APIのURLにリダイレクトされます。
例:


データベースのIDを利用するとラベル定義情報(項目のマッピング情報)を取得することができます。

クエリの形式:
https://jpsearch.go.jp/api/database/(データベースID)/label

例:

1. アイテムに対する基本的な検索

https://jpsearch.go.jp/api/item/search/jps-cross?
を起点に、パラメータを&区切りで指定することで横断検索の検索結果を取得できます。

  1. 1.1 全データベースに対するキーワード検索
  2. 1.2 複数のキーワードを指定したキーワード検索
  3. 1.3 取得方法を指定した検索

1.1 全データベースに対するキーワード検索

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?keyword=(キーワード)

クエリ例:

1.2 複数のキーワードを指定したキーワード検索

キーワードは複数指定することが可能です。パラメータを指定しない場合、デフォルトはAND検索になります。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?keyword=(キーワード1)&keyword=(キーワード2)

クエリ例:

OR検索の場合はkeywordOrパラメータをtrueに指定します。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?keyword=(キーワード1)&keyword=(キーワード2)&keywordOr=true

クエリ例:

1.3 取得方法を指定した検索

1.3.1 検索結果が2000件以内の場合

1度に取得したい件数や取得の開始位置を指定することができます。

検索結果の取得方法には以下の2種類のパラメータを指定できます。

名称 複数指定 説明
from NG 開始位置 from=0
(※デフォルト値)
size NG クエリ1回あたりの取得件数 size=20
(※デフォルト値,最大500まで)

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?keyword=(キーワード)&from=(件数)&size=(件数)

クエリ例:

1.3.2 検索結果が2000件以上の場合(全件取得)

一度に2000件以上の検索結果の取得を行いたい場合はクエリ中の"search"を"scroll"に置き換えることで、全件取得を行うことができます。

クエリの形式:
https://jpsearch.go.jp/api/item/scroll/jps-cross?keyword=(キーワード)

一度に200件の結果を取得できます。返戻に含まれるscrollIdを次回のクエリに指定することで、検索結果の続きを取得することができます。

すべての検索結果の取得が完了すると、返戻にscrollIdが含まれなくなります。また、listは0件になります。いずれかを判断基準にしてループを抜けてください。

scrollIdは発効から20秒で失効しますので、全件取得を行いたい場合は20秒以内の間隔で継続的にクエリ送信してください。

クエリ例:

2. 連携データベースに対する検索

https://jpsearch.go.jp/api/database/search?

を起点に、パラメータを&区切りで指定することでジャパンサーチの連携データベースの情報を検索できます。

取得したデータベースのID等の情報を利用することで、対象データベースを絞り込んだ検索に利用することもできます。

  1. 2.1 全ての連携データベースの情報を得る検索
  2. 2.2 連携データベースに対するキーワード検索

2.1 全ての連携データベースの情報を得る検索

クエリの形式:
https://jpsearch.go.jp/api/database/search?from=(件数)&size=(件数)

クエリ例:

2.2 連携データベースに対するキーワード検索

ジャパンサーチの連携データベースをキーワードで検索することができます。

クエリの形式:
https://jpsearch.go.jp/api/database/search?keyword=(キーワード)

クエリ例:

例えば上のクエリの返戻からは、"id"から全国書誌のデータベースIDがbibnlであることや、"category"からデータベースのカテゴリがbookであることがわかります。

3. ギャラリーページ・連携機関に対する検索

  1. 3.1 ギャラリーページに対する検索
  2. 3.2 連携機関に対する検索

3.1 ギャラリーページに対する検索

ジャパンサーチで公開されているギャラリーページを検索することができます。

クエリの形式:
https://jpsearch.go.jp/api/curation/search?keyword=(キーワード)

クエリ例:

3.2 連携機関に対する検索

ジャパンサーチの連携機関を検索することができます

クエリの形式:
https://jpsearch.go.jp/api/organization/search?keyword=(キーワード)

クエリ例:

4. 絞り込み検索

  1. 4.1 データベースIDを指定した絞り込み検索
  2. 4.2 コンテンツの公開状況を指定した絞り込み検索
  3. 4.3 コンテンツの利用条件を指定した絞り込み検索
  4. 4.4 コンテンツのメディアタイプを指定した絞り込み検索
  5. 4.5 除外ファセットによる絞り込み検索

4.1 データベースIDを利用した絞り込み検索

2. 連携データベースに対する検索で取得したデータベースIDを利用して絞り込みを行うことができます。

検索対象としたいデータベースが1つに決まっている場合は以下のようなクエリが高速です。

クエリの形式(対象データベースを1つに指定した絞り込み検索):
https://jpsearch.go.jp/api/item/search/(データベースID)-default?

例えば全国書誌(bibnl)に限定した検索を行いたい場合、以下のようなクエリになります。

クエリ例:

検索対象としたいデータベースが複数ある場合には、横断検索に対してパラメータを指定することで絞り込むことができます。

クエリの形式(パラメータを指定してデータベースを絞り込む絞り込み検索):
https://jpsearch.go.jp/api/item/search/jps-cross?f-db=(データベースのID)

例えば全国書誌(bibnl)と国立国会図書館デジタルコレクション(dignl)のどちらかに含まれるアイテムに対してキーワード検索を行いたい場合、以下のようなクエリになります。

クエリ例:

4.2 コンテンツの公開状況を指定した絞り込み検索

コンテンツの公開状況を指定して絞り込みを行うことができます。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?f-contents=(区分の指定)

区分には以下の4つを指定可能です。(複数選択可)

  • f-contents=thumb (サムネイルあり)
  • f-contents=internet (インターネット公開)
  • f-contents=iiif (IIIF(International Image Interoperability Framework)対応)
  • f-contents=restricted (アクセス制限あり)

クエリ例:

4.3 コンテンツの利用条件を指定した絞り込み検索

コンテンツの利用条件を指定して絞り込みを行うことができます。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?f-rights=(区分の指定)

区分には以下の3つを指定可能です。(複数選択可)

  • f-rights=com (商用利用可)
  • f-rights=noncom (非商用利用可)
  • f-rights=edu (教育利用可)

クエリ例:

4.4 コンテンツのメディアタイプを指定した絞り込み検索

コンテンツのメディアタイプを指定して絞り込みを行うことができます。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?f-cm=(区分の指定)

区分には以下の8つを指定可能です。

  • f-cm=official (公文書)
  • f-cm=science (自然史・理工学)
  • f-cm=book (書籍等)
  • f-cm=humanities (人文学)
  • f-cm=cultural (文化財)
  • f-cm=regeional (地域)
  • f-cm=art (美術)
  • f-cm=broadcast (放送番組)

クエリ例:

4.5 除外ファセットによる絞り込み検索

除外ファセット機能を利用することで、検索結果から特定の条件に該当するアイテムを除外することができます。いずれも複数指定が可能です。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?fc-(ファセット名)=-(除外したい条件の指定)

4.5.1 特定のカテゴリを除外する絞り込み検索

除外可能な条件は以下の通りです。

  • fc-category=-official (公文書資料を除外)
  • fc-category=-science (自然史・理工学資料を除外)
  • fc-category=-book (書籍等資料を除外)
  • fc-category=-humanities (人文学資料を除外)
  • fc-category=-cultural (文化財資料を除外)
  • fc-category=-regeional (地域資料を除外)
  • fc-category=-art (美術資料を除外)
  • fc-category=-broadcast (放送番組資料を除外)
クエリ例:

4.5.2 特定のコンテンツ公開区分を除外する絞り込み検索

除外可能な条件は以下の通りです。(複数指定可)

  • fc-caccess=-internet (ウェブ公開資料を除外)
  • fc-caccess=-restricted (限定公開資料を除外)
  • fc-caccess=-not_exist (デジタルコンテンツのない資料を除外)
クエリ例:

4.5.3 特定のデータベースを除外する絞り込み検索

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?fc-db=-(データベースID)
クエリ例:

5. 項目を指定した検索

  1. 5.1 「時間」の項目を指定した検索
  2. 5.2 「場所」の項目を指定した検索
  3. 5.3 「人物」の項目を指定した検索

5.1 「時間」の項目を指定した検索

時代名等を利用して検索することができます。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?q-tempo=(キーワード)

クエリ例:

5.2 「場所」の項目を指定した検索

場所の名称を利用して検索することができます。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?q-loc=(キーワード)

クエリ例:

5.3 「人物」の項目を指定した検索

人物の名称を利用して検索することができます。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?q-contributor=(キーワード)

クエリ例:

6. 正規化機能を利用した検索

ジャパンサーチはユーザの検索を支援するために、時間や場所について簡易的な正規化機能を有しています。

このAPIを利用したインターフェースは今後公開予定ですが、APIについては二次利用の促進のために前倒して提供しています。

おことわり:本機能はジャパンサーチに登録されたメタデータの検索を補助する目的で、機械的に付与しているものです。付与されている情報が必ずしも正確でない点にご留意ください。

  1. 6.1 「時間」の正規化を利用した検索
  2. 6.2 「場所」の正規化を利用した検索

6.1 「時間」の正規化を利用した検索

メタデータに含まれる時間表現を正規化した情報を利用して、年代情報をレンジで検索することができます。正規化対象は以下の通りです。

  • 年代表記の揺れ(例:2019年2月27日,2019/02/27,20190227等をすべて2019-02-27へ変換)
  • 和暦や旧暦(例:平成三十一年二月二十七日を2019-02-27へ変換、万延元年5月1日を1860-06-19へ変換)

正規化にあたって利用した情報リソースと補足説明

和暦や旧暦から西暦年月日への変換には、HuTime APIから取得した対応関係を利用しています。

元のメタデータ中に月日の情報がないものについては、それぞれ1月と1日として扱っています。(例:「2019年2月」の場合は2019-02-01、「2019年」のみの場合は2019-01-01)

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?q-tempo=(始点),(終点)

始点と終点は、yyyy,yyyy-MM,yyyy-MM-DDのいずれかの形式で指定してください。

クエリ例:

6.2 「場所」の正規化を利用した検索

メタデータに含まれる地名や住所を、緯度経度に変換することで正規化した情報を利用して、特定の緯度経度を指定して周辺を検索することができます。正規化対象は以下の通りです。

  • 住所(例:「東京都千代田区」を、35.6939,139.7535へ変換)
  • 歴史地名(例:「野麦峠」を、36.0522,137.6059へ変換)

正規化にあたって利用した情報リソースと補足説明

住所についてはGeoNLPが作成した日本の郡・市区町村(2013年9月)を利用しています。

住所に対する正規化は、基本的には市町村区までの緯度経度であり、当該地域の都道府県市町村役場の所在地が入ります。
例:東京都千代田区永田町1-10-1であれば、東京都千代田区役所の所在地の緯度経度。

歴史地名については、人間文化研究機構およびH-GIS研究会の研究成果である歴史地名辞書データを加工して利用しています。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?g-coordinates=(緯度),(経度),(半径)

半径は、「15km」や「100m」といった形式で指定してください。単位が入っていない場合、メートルとして解釈されます。

クエリ例:

7. 画像検索

ジャパンサーチの類似画像検索を利用するためのAPIです。

サムネイル画像を持つアイテムのIDを指定すると、似たサムネイル画像を持つアイテムを返します。

クエリの形式:
https://jpsearch.go.jp/api/item/search/jps-cross?image=(サムネイルを持つアイテムのID)

クエリ例:

キーワード検索と組みあわせて絞り込んで使うこともできます。

以下の例では、能面の画像を類似画像検索し、「中将」に該当する能面を絞り込んでいます。

8. 検索パラメータ一覧

名称 複数指定 説明
keyword OK 検索キーワード keyword=江戸
keywordOr NG trueのとき複数キーワードが指定された際にOR検索する。
falseのときAND検索。
keywordOr=false
(※デフォルト値)
f-db OK データベースIDによる絞り込み f-db=dignl
f-cm OK メディアタイプによる絞り込み f-cm=book
f-contents OK コンテンツの公開状況による絞り込み f-contents=internet
fc-category OK 特定のカテゴリを除外する絞り込み
(※ハイフンをつける)
fc-category=-book
fc-caccess OK 特定のコンテンツ公開区分を除外する絞り込み
(※ハイフンをつける)
fc-caccess=-internet
fc-db OK 特定のデータベースを除外する絞り込み
(※ハイフンをつける)
fc-db=-bibnl
q-tempo OK 「時間」の項目を使って検索する q-tempo=江戸
q-loc OK 「場所」の項目を使って検索する q-loc=世田谷
q-contributor OK 「人物」の項目を使って検索する q-contributor=徳川家康
r-timespan NG 正規化された年代情報を使って検索する r-timespan=1500-01-01,1600-12-31
g-coordinates NG 正規化された地理情報を使って検索する g-coordinates=35.679813,139.7435848,10km
image NG サムネイル画像を持つアイテムを使って類似画像検索する image=cobas-94554