3章 検索API

3章ではジャパンサーチ上のメタデータを探索するための検索APIについて、各エンドポイントの概要及びレスポンスのファセットに含まれるコード値を説明します。

3.1 検索APIのエンドポイント

検索APIのエンドポイントは次の通りです。

  1. アイテム検索: https://jpsearch.go.jp/api/item/search/jps-cross
  2. ギャラリー検索: https://jpsearch.go.jp/api/curation/search
  3. 連携データベース検索: https://jpsearch.go.jp/api/database/search
  4. 連携機関検索: https://jpsearch.go.jp/api/organization/search
  5. テーマ別検索に対する検索: https://jpsearch.go.jp/api/csearch/search

3.1.1 空検索

クエリパラメータを省略した場合、空のキーワード検索（空検索）と同等になり、全件検索になります。 検索結果の返戻件数は、デフォルトでは20件までです。件数の制御方法については「4.2 ページネーション」で説明します。

⚫️アイテムを空検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross | jq

⚫️ギャラリーを空検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search | jq

⚫️連携データベースを空検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/database

簡易Web APIのURL

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

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/database/search | jq

⚫️連携機関を空検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/organization

簡易Web APIのURL

https://jpsearch.go.jp/api/organization/search

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/organization/search | jq

⚫️連携機関の空検索結果からIDの日本語名称を抜粋する例

$ curl -sG https://jpsearch.go.jp/api/organization/search \
--data-urlencode size=200 \
| jq -r '.list[] | "\(.id): \(.name.ja)"' ex_066.json | sort -f
apmoa: 愛知県美術館
arc_ritsumeikan: 立命館大学アート・リサーチセンター
bpcj: 公益財団法人 放送番組センター
bunkazai: 文化庁
chigamu: 茅ヶ崎市博物館
edo_tokyo_museum: 江戸東京博物館
...

⚫️テーマ別検索を空検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch

簡易Web APIのURL

https://jpsearch.go.jp/api/csearch/search

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/csearch/search | jq

3.1.2 データベースIDを利用した絞り込み

データベースIDを利用して絞り込みを行うことができます。 検索対象としたいデータベースが1つに決まっている場合、高速に取得可能ですが、後述するファセットは出力されません。

エンドポイント

https://jpsearch.go.jp/api/item/search/{データベースID}-default

⚫️連携データベースを「全国書誌(bibnl)」に限定して検索する例

ジャパンサーチUIのURL

N/A

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/bibnl-default

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/bibnl-default | jq

3.2 JSONレスポンスのデータ構造

3.2.1 検索APIレスポンスのプロパティ

JSONレスポンス

プロパティ データ型 説明
list オブジェクトの配列 検索結果の配列
hit 数値 条件に合致する総ヒット件数
from 数値 検索結果の開始位置
facets オブジェクトの配列 ファセット情報
key 文字列 ファセット項目
count オブジェクト ファセット項目のコード値ごとの該当件数
  1. fromプロパティ

検索結果の取得開始位置を示します。 検索結果の1回あたりの取得件数と開始位置は、クエリパラメータで指定します。 詳細については「4.2 ページネーション」を参照ください。

  1. listプロパティ

検索条件に合致したメタデータが配列として格納されます。 データ構造は「2章 メタデータ参照API」のJSONレスポンスで示した内容と基本的に同様です（ギャラリーの場合partsは出力されません）。

  1. facetsプロパティ

アイテムとギャラリーに対する検索の場合、JSONレスポンスにfacetsプロパティが含まれます。 検索結果全体に含まれるファセット毎の出現頻度の統計情報を表しています。

3.2.2 アイテム検索APIのfacetsプロパティ

アイテム検索APIの場合、レスポンスのfacetsプロパティに含まれるファセット項目（keyの値）は、次の6種類です。

3.2.2.1 利用条件 rights

rightsファセットに列挙されるコード値及び頻度情報は、common.contentsRightsTypeの値を集約しています。

common.contentsRightsTypeのコード値表

コード値 説明
edu 教育利用
noncom 非商用利用
com 商用利用
cc0 CC0
pdm PDM
ccby CC BY（表示）
ccbysa CC BY-SA（表示—継承）
ccbynd CC BY-ND（表示—改変禁止）
ccbync CC BY-NC（表示—非営利）
ccbyncsa CC BY-NC-SA（表示—非営利—継承）
ccbyncnd CC BY-NC-ND（表示—非営利—改変禁止）
incr 著作権あり
incr_edu 著作権あり-教育目的の利用可
nocr_cont 著作権なし-契約による制限あり
nocr_other 著作権なし-他の法的制限あり
uneval 著作権未評価
undet 著作権未決定-裁定制度利用著作物
others 該当なし

3.2.2.2 コンテンツ contents

contentsファセットに列挙されるコード値及び頻度情報は、common.contentsAccess及びcommon.contentsTypeの値を集約しています。

common.contentsAccessのコード値表

コード値 説明
not_exist デジタルコンテンツなし
internet ウェブ公開
restricted 限定公開

common.contentsTypeのコード値表

コード値 説明
thumb サムネイル有
iiif IIIF対応
image 画像
video 動画
text 文書
table 表形式
sound 音声
3d 3D
pdf PDF

3.2.2.3 種類 type

typeファセットに列挙されるコード値及び頻度情報は、

ジャパンサーチ利活用スキーマによって付与されたrdfindex.typeの情報をコード値に変換して集約しています。

rdfindex.typeのコード値表

コード値 説明 rdfindex.typeの値
book 図書 図書、画集・画本
periodical 雑誌・新聞・定期刊行物 雑誌・新聞・継続資料、雑誌、新聞
article 記事・論文 博士論文、記事・論文、記事
map 地図 地図資料
ancdoc 古文書 古書・古文書、書跡、書簡、書写資料、稀覯
poetry 短歌・和歌・俳句・詩 収録作品
poster ポスター・デザイン デザイン、ポスター、端物印刷物
postcard 絵葉書など 絵葉書
offdoc 公文書 会議録、行政文書、政府刊行物
docs その他 文書資料、資料一般、出版物、文章要素、法人文書、個人・団体の文書資料
archeology 考古・民俗 考古、歴史資料、民族資料、拓本
custom 風俗・祭事 風俗・祭事
site 史跡・名勝・天然記念物 史跡、名勝、天然記念物
stone 石碑 石碑
weaponry 刀剣・武器 刀剣、武器、金工・武器
woodw 木工 木工
metal 金工 金工
ceramic 陶磁 陶磁
lacquer 漆工 漆工
daw 染織 染織
craft その他 竹工芸、工芸、装飾・工芸、屏風、楽器、面、硬貨、馬具
architecture 建築 建造物・建築、建築
paint 絵画・版画 絵画等、絵画、版画、水彩、素描
sculpture 彫刻 彫刻
photo 写真 写真、記録写真
movie 映画 映画
mediaart メディア芸術 メディア芸術
performance 上演・公演・演奏 上演、演奏、パフォーマンス、公演
mscore 楽譜 楽譜
exhibition 展覧会の日程や場所 展覧会
arts その他 芸術・美術、建築・芸術、インスタレーション
video 映像 映像資料
recording 録音 録音資料
broadcast 放送番組 放送番組
game ゲーム ゲーム
anime アニメーション アニメーション
Website ウェブサイト ウェブサイト
ematerial 電子資料 電子資料
3d 3D・モーションキャプチャ 3D資料
media その他 静止画資料
mineral 鉱物 宝石
natural 博物 博物資料、標本、植物標本
other その他 構成要素、記述情報、コレクション、画像要素
dataset データセット データセット
org 機関・施設情報 機関・施設情報

3.2.2.4 データベース db

dbファセットに列挙されるコード値及び頻度情報は、common.databaseの値を集約しています。

次のcurlコマンドでデータベースを一覧取得できます。

$ curl -sG https://jpsearch.go.jp/api/database/search  \
--data-urlencode size=250 \
| jq -r '.list[] | "\(.id): \(.name.ja)"' | sort -f
a12345: データカタログサイト
a1545100173162: 演劇博物館名品セレクション
adeac: デジタルアーカイブシステムADEAC
aokenshida_doc: 青森県史デジタルアーカイブス　古文書・文献史料データベース
aokenshida_lib: 青森県史デジタルアーカイブス　県史関係図書・論文データベース
...

3.2.2.5 分野 cm

cmファセットに列挙されるコード値及び頻度情報は、common.categoryの値を集約しています。

common.categoryのコード値表

コード値 説明
anime アニメ
movie 映画
game ゲーム
official 公文書
science 自然史・理工学
book 書籍等
humanities 人文学
regional 地域
map 地図
dataset データセット
art 美術
pfart 舞台芸術
cultural 文化財
broadcast 放送番組
manga マンガ
media メディアアート

3.2.2.6 時間/時代 tempo

tempoファセットに列挙されるコード値及び頻度情報は、common.temporalの値を集約しています。

common.temporalのコード値表

コード値 説明
ancient 縄文・弥生・古墳
asuka 飛鳥
nara 奈良
heian 平安
kamakura 鎌倉
muromachi 室町
aduchi 安土桃山
edo 江戸
meiji 明治
taisyo 大正
showa 昭和
heisei 平成
reiwa 令和

3.2.3 ギャラリー検索APIのfacetsプロパティ

ギャラリー検索APIの場合、レスポンスのfacetsプロパティに含まれるファセット項目（keyの値）は、次の2種類です。

トピックとキーワードは「2.4 ギャラリー参照API」のJSONレスポンスに含まれるtag.idの接頭辞の違いによって区別することができます。

tag.idのコード値表（トピックのみ）

コード値 説明
o-person 人
o-natural 自然物
o-artifact もの
o-work 作品
o-event 出来事
o-art 芸術・芸能・工芸
o-architecture 建築
o-doctrine 主義・思想・技芸
o-location 地名
o-title 職業・地位
o-organization 機関

※キーワードについては統制されたコード値ではないため記載省略

⚫️ギャラリーのファセットに含まれるファセット項目のコード一覧を取得する例

$ curl -sG https://jpsearch.go.jp/api/curation/search  \
--data-urlencode size=500 \
| jq -r '.list[].tag' | jq -s 'flatten | sort | unique' \
| jq -r '.[] | "\(.id) : \(.label.ja) \(.label.en)"'

3.3 利用可能なクエリパラメータの対応早見表

クエリパラメータ 説明箇所 item curation database organization csearch
keyword 4.1を参照 ○ ○ ○ ○ ○
size 4.2を参照 ○ ○ ○ ○ ○
from 4.2を参照 ○ ○ ○ ○ ○
f-クエリ 5章を参照 ○ ※ × × ×
image 6.1.1を参照 ○ × × × ×
text2image 6.1.2を参照 ○ × × × ×
q-クエリ 6.2を参照 ○ × × × ×
r-クエリ 6.3.1を参照 ○ × × × ×
g-クエリ 6.3.2を参照 ○ × × × ×

※はギャラリー固有のパラメータを利用