5章 フィルタによる絞り込み
5章では検索APIについて検索結果を絞り込むためのクエリの作り方やファセットの見方を説明します。
5.1 アイテム検索における絞り込み
5.1で説明するクエリパラメータは、次のエンドポイントで実行できます。
エンドポイント
https://jpsearch.go.jp/api/item/search/jps-cross
5.1.1 利用条件 f-rights
ジャパンサーチの横断検索UIにおける「利用条件」の絞り込み条件に相当します。
クエリパラメータ
f-rights={利用条件のコード値}
f-rightsに指定可能なコード値については「3.2.2.1 利用条件 rights」のコード値表を参照してください。
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とrightsファセットの頻度情報を確認してみましょう。
⚫️「利用条件」が「商用利用(com)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-rights=com
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-rights=com
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-rights=com | jq
⚫️「利用条件」が「著作権あり(incr)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-rights=incr
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-rights=incr
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-rights=incr | jq
⚫️「利用条件」が「商用利用(com)」かつ「PDM(pdm)」でないアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-rights=com&f-rights=-pdm
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-rights=com&f-rights=-pdm
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-rights=com \
--data-urlencode f-rights=-pdm | jq
⚫️「利用条件」が「商用利用(com)」または「著作権あり(incr)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-rights=%2Bcom&f-rights=%2Bincr
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-rights=%2Bcom&f-rights=%2Bincr
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-rights=+com \
--data-urlencode f-rights=+incr | jq
5.1.2 コンテンツ f-contents
ジャパンサーチの横断検索UIにおける「コンテンツ」の絞り込み条件に相当します。
クエリパラメータ
f-contents={コンテンツのコード値}
f-contentsに指定可能なコード値については「3.2.2.2 コンテンツ contents」のコード値表を参照してください。
注意
- facetsの頻度情報と動作に不一致があります。
- AND結合は組み合わせに関係なく0件になります。
- OR結合は動作します。
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とcontentsファセットの頻度情報を確認してみましょう。
⚫️「コンテンツ」が「画像(image)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-contents=image
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-contents=image
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-contents=image | jq
⚫️「コンテンツ」が「文書(text)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-contents=text
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-contents=text
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-contents=text | jq
⚫️「コンテンツ」が「画像(image)」または「文書(text)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-contents=%2Bimage&f-contents=%2Btext
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-contents=%2Bimage&f-contents=%2Btext
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-contents=+image \
--data-urlencode f-contents=+text | jq
5.1.3 種類 f-type
ジャパンサーチの横断検索UIにおける「種類」の絞り込み条件に相当します。
ジャパンサーチ利活用スキーマによって付与された情報を利用しています。
typeは排他的であり、複数指定する場合はOR結合のみ有効です。
クエリパラメータ
f-type={種類のコード値}
f-typeに指定可能なコード値については「3.2.2.3 種類 type」のコード値表を参照してください。
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とtypeファセットの頻度情報を確認してみましょう。
⚫️「種類」が「雑誌・新聞・定期刊行物(periodical)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-type=periodical
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-type=periodical
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-type=periodical | jq
⚫️「種類」が「図書(book)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-type=book
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-type=book
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-type=book | jq
⚫️「種類」が「雑誌・新聞・定期刊行物(periodical)」または「図書(book)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-type=%2Bperiodical&f-type=%2Bbook
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-type=%2Bperiodical&f-type=%2Bbook
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-type=+periodical
--data-urlencode f-type=+book | jq
5.1.4 データベース f-db
ジャパンサーチの横断検索UIにおける「データベース」の絞り込み条件に相当します。
dbは排他的であり、複数指定する場合はOR結合のみ有効です。
クエリパラメータ
f-db={データベースID}
f-dbに指定可能な値(データベースID)については「3.2.2.4 データベース db」のコード値表を参照してください。
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とdbファセットの頻度情報を確認してみましょう。
⚫️「データベース」が「全国書誌(bibnl)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-db=bibnl
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-db=bibnl | jq
⚫️「データベース」が「国立国会図書館デジタルコレクション(dignl)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-db=dignl
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-db=dignl | jq
⚫️「データベース」が「全国書誌(bibnl)」または「国立国会図書館デジタルコレクション(dignl)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-db=%2Bbibnl&f-db=%2Bdignl
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-db=%2Bbibnl&f-db=%2Bdignl
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-db=+bibnl \
--data-urlencode f-db=+dignl | jq
5.1.5 分野 f-cm
ジャパンサーチの横断検索UIにおける「分野」の絞り込み条件に相当します。
クエリパラメータ
f-cm={分野のコード値}
f-cmに指定可能なコード値については「3.2.2.5 分野 cm」のコード値表を参照してください。
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とcmファセットの頻度情報を確認してみましょう。
⚫️「分野」が「書籍等(book)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-cm=book
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-cm=book | jq
⚫️「分野」が「地図(map)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-cm=map
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-cm=map | jq
⚫️「分野」が「書籍等(book)」かつ「地図(map)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-cm=book&f-cm=map
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-cm=book&f-cm=map
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-cm=book \
--data-urlencode f-cm=map | jq
⚫️「分野」が「書籍等(book)s」または「地図(map)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-cm=%2Bbook&f-cm=%2Bmap
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-cm=%2Bbook&f-cm=%2Bmap
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-cm=+book \
--data-urlencode f-cm=+map | jq
5.1.6 時間/時代 f-tempo
ジャパンサーチの横断検索UIにおける「時間/時代」の絞り込み条件に相当します。
クエリパラメータ
f-tempo={時間/時代のコード値}
f-tempoに指定可能なコード値については「3.2.2.6 時間/時代 tempo」のコード値表を参照してください。
注意
- facetsのカウントと動作に不一致があります。
- OR結合は動作します。
- AND結合はOR結合と同じ動作になります。
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とtempoファセットの頻度情報を確認してみましょう。
⚫️「時間/時代」が「飛鳥(asuka)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-tempo=asuka
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-tempo=asuka
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-tempo=asuka | jq
⚫️「時間/時代」が「奈良(nara)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-tempo=nara
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-tempo=nara
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross
--data-urlencode f-tempo=nara | jq
⚫️「時間/時代」が「飛鳥(asuka)」または「奈良(nara)」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-tempo=%2Basuka&f-tempo=%2Bnara
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-tempo=%2Basuka&f-tempo=%2Bnara
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross
--data-urlencode f-tempo=+asuka
--data-urlencode f-tempo=+nara | jq
5.1.7 アクセス f-caccess
ジャパンサーチの横断検索UIにおける「コンテンツ」の絞り込み条件のうち一部に相当します。
クエリパラメータ
f-caccess={コード値}
指定可能なコード値は次の通りです
- internet
- restricted
- not_exist
次のクエリ例を試して、検索条件ごとの検索結果の件数(レスポンスのhitの値)とcontentsファセットの頻度情報を確認してみましょう。
⚫️「アクセス」が「internet」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-caccess=internet
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-caccess=internet
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-caccess=internet | jq
⚫️「アクセス」が「restricted」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-caccess=restricted
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-caccess=restricted
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-caccess=restricted | jq
⚫️「アクセス」が「not_exist」のアイテムを横断検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&f-caccess=not_exist
簡易Web APIのURL
https://jpsearch.go.jp/api/item/search/jps-cross?f-caccess=not_exist
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode f-caccess=not_exist | jq
5.2 ギャラリー検索における絞り込み
5.2で説明するクエリパラメータは、次のエンドポイントで実行できます。
エンドポイント
https://jpsearch.go.jp/api/curation/search
5.2.1 トピック f-topic
ジャパンサーチのギャラリー検索UIにおける「トピック」の絞り込み条件に相当します。
クエリパラメータ
f-topic={コード値}
f-topicに指定できるコード値については、「3.2.3 ギャラリー検索APIのfacetsプロパティ」のコード値表を参照してください。
⚫️「トピック(f-topic)」が「人(o-person)」のギャラリーを検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/gallery?csid=jps-gallerycs&f-topic=o-person
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/curation/search \
--data-urlencode f-topic=o-person | jq
レスポンスにおけるhitの値とfacetsのcounts.o-personの値が等しいのを確認してください。
5.2.2 キーワード f-keyword
ジャパンサーチのギャラリー検索UIにおける「キーワード」の絞り込み条件に相当します。
クエリパラメータ
f-keyword={コード値}
f-keywordで指定できるコード値については、「3.2.3 ギャラリー検索APIのfacetsプロパティ」を参照してください。
⚫️「キーワード(f-keyword)」が「江戸時代(w-edo)」のギャラリーを検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/gallery?csid=jps-gallerycs&f-keyword=w-edo
簡易Web APIのURL
$ curl -sG https://jpsearch.go.jp/api/curation/search \
--data-urlencode f-keyword=w-edo | jq
レスポンスにおける検索結果の件数(hitの値)とkeywordファセットのw-edoの件数が等しくなっています。
5.2.3 作成機関 f-permission.ownerOrg
ギャラリーは作成機関の連携機関IDで検索結果を絞り込むことができます。
以下のように、クエリパラメータの値には「連携機関ID」を指定します。
クエリパラメータ
f-permission.ownerOrg={連携機関ID}
⚫️「作成機関(f-permission.ownerOrg)」が「国立国会図書館(ndl)」のギャラリーを検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/gallery?csid=jps-gallerycs&f-permission.ownerOrg=ndl
簡易Web APIのURL
https://jpsearch.go.jp/api/curation/search?f-permission.ownerOrg=ndl
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/curation/search \
--data-urlencode f-permission.ownerOrg=ndl | jq
⚫️「作成機関(f-permission.ownerOrg)」が「国立国会図書館(ndl)」以外のギャラリーを検索する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/gallery?csid=jps-gallerycs&f-permission.ownerOrg=-ndl
簡易Web APIのURL
https://jpsearch.go.jp/api/curation/search?f-permission.ownerOrg=-ndl
$ curl -sG https://jpsearch.go.jp/api/curation/search \
--data-urlencode f-permission.ownerOrg=-ndl | jq