4章検索APIの基本クエリパラメータ

4章では検索APIについて、各エンドポイントに共通するクエリパラメータ（検索キーワード及びページネーションの指定）を説明します。

4.1 検索キーワード

キーワード検索で使用する「検索語」は、クエリパラメータkeywordで指定します。

4.1.1 検索条件の結合方法について

keywordパラメータは複数指定することができます。

「検索語」の前に符号を前置きすれば、結合条件を調整することができます。

AND : 前置き符号は省略
OR : 前置き符号は+
NOT : 前置き符号は-

AND結合

keyword={検索語}

keywordを複数指定したときの結合は、AND結合になります。

OR結合

keyword=+{検索語}

keywordを複数指定したときの結合を、AND結合ではなく、OR結合にします。ただし、すべての検索語に + を前置きする必要があります。

注意: URLにおける"+"はメタ文字になるので、URLエンコードした"%2B"に置き換えてください。

NOT結合

keyword=-{検索語}

「検索語」を含まない検索を実行します。

次項からは、5つのデータポイントについてkeywordの使い方を例で示します。

4.1.2 アイテム検索

エンドポイント

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

次のクエリ例を試して、検索条件ごとの検索結果の件数（レスポンスのhitの値）を確認してみましょう。

⚫️「印象派」を含むアイテムを横断検索する例（2,137件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&keyword=印象派

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?keyword=印象派

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
			--data-urlencode keyword=印象派 \
			| jq .hit

⚫️「セザンヌ」を含むアイテムを横断検索する例（1537件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&keyword=セザンヌ

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?keyword=セザンヌ

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
			--data-urlencode keyword=セザンヌ \
			| jq .hit

⚫️「印象派」を含む、かつ（AND）「セザンヌ」を含むアイテムを横断検索する例（192件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&keyword=印象派&keyword=セザンヌ

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?keyword=印象派&keyword=セザンヌ

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
			--data-urlencode keyword=印象派 \
			--data-urlencode keyword=セザンヌ \
			| jq .hit

⚫️「印象派」を含む、または（OR）「セザンヌ」を含むアイテムを横断検索する例（3,482件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&keyword=%2B印象派&keyword=%2Bセザンヌ

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?keyword=%2B印象派&keyword=%2Bセザンヌ

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
			--data-urlencode keyword=+印象派 \
			--data-urlencode keyword=+セザンヌ \
			| jq .hit

⚫️「印象派」を含む、かつ（AND）「セザンヌ」を含まないアイテムを横断検索する例（1,945件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&keyword=印象派&keyword=-セザンヌ

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?keyword=印象派&keyword=-セザンヌ

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
			--data-urlencode keyword=印象派 \
			--data-urlencode keyword=-セザンヌ
			| jq .hit

⚫️「印象派」を含まない、かつ（AND）「セザンヌ」を含むアイテムを横断検索する例（1,345件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&keyword=-印象派&keyword=セザンヌ

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?keyword=-印象派&keyword=セザンヌ

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
			--data-urlencode keyword=-印象派 \
			--data-urlencode keyword=セザンヌ \
			| jq .hit

4.1.3 ギャラリー検索

エンドポイント

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

レスポンスのlistにはpartsプロパティは含まれていませんが、partsプロパティの内容もキーワード検索の対象になります。

次のクエリ例を試して、検索条件ごとの検索結果の件数（レスポンスのhitの値）を確認してみましょう。

⚫️「印象派」を含むギャラリーを検索する例（14件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&keyword=印象派

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?keyword=印象派

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode keyword=印象派 \
			| jq .hit

⚫️「浮世絵」を含むギャラリーを検索する例（221件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&keyword=浮世絵

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?keyword=浮世絵

curlコマンド

curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode keyword=浮世絵 \
			| jq .hit

⚫️「印象派」を含む、かつ（AND）「浮世絵」を含むギャラリーを検索する例（11件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&keyword=印象派&keyword=浮世絵

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?keyword=印象派&keyword=浮世絵

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode keyword=印象派 \
			--data-urlencode keyword=浮世絵 \
			| jq .hit

⚫️「印象派」を含む、または（OR）「浮世絵」を含むギャラリーを検索する例（224件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&keyword=%2B印象派&keyword=%2B浮世絵

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?keyword=%2B印象派&keyword=%2B浮世絵

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode keyword=+印象派 \
			--data-urlencode keyword=+浮世絵 \
			| jq .hit

⚫️「印象派」を含む、かつ（AND）「浮世絵」を含まないギャラリーを検索する例（3件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&keyword=印象派&keyword=-浮世絵

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?keyword=印象派&keyword=-浮世絵

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode keyword=印象派 \
			--data-urlencode keyword=-浮世絵 \
			| jq .hit

⚫️「印象派」を含まない、かつ（AND）「浮世絵」を含むギャラリーを検索する例（210件※2024/1/31時点）

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&keyword=-印象派&keyword=浮世絵

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?keyword=-印象派&keyword=浮世絵

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode keyword=-印象派 \
			--data-urlencode keyword=浮世絵 \
			| jq .hit

4.1.4 連携データベース検索

エンドポイント

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

⚫️「アジア」を含む、または（OR）「アフリカ」を含む連携データベースを検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/database?keyword=%2Bアジア&keyword=%2Bアフリカ

簡易Web APIのURL

https://jpsearch.go.jp/api/database/search?keyword=%2Bアジア&keyword=%2Bアフリカ

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/database/search \
			--data-urlencode keyword=+アジア \
			--data-urlencode keyword=+アフリカ | jq

4.1.5 連携機関検索

エンドポイント

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

⚫️「東京都」を含む、かつ（AND）「美術館」を含む連携機関を検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/organization?keyword=東京都&keyword=美術館

簡易Web APIのURL

https://jpsearch.go.jp/api/organization/search?keyword=東京都&keyword=美術館

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/organization/search \
			--data-urlencode keyword=東京都 \
			--data-urlencode keyword=美術館 | jq

4.1.6 テーマ別検索に対する検索

エンドポイント

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

⚫️「古地図」を含む、または（OR）「刀剣」を名称に含むテーマ別検索を検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch?keyword=%2B古地図&keyword=%2B刀剣 ↑古地図が0件

簡易Web APIのURL

https://jpsearch.go.jp/api/csearch/search?keyword=%2B古地図&keyword=%2B刀剣

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/csearch/search \
			--data-urlencode keyword=+古地図 \
			--data-urlencode keyword=+刀剣 | jq

４.２ページネーション

空検索で説明したように、検索結果の最大取得件数はデフォルトでは20件になっています。この最大取得件数は、sizeで調整できます。

一回で取得可能な範囲を超える検索結果を取得するには、検索結果の開始位置(from)の値をずらしたリクエストを複数回反復する必要があります。

sizeとfromで取得可能な件数の上限は2,000件までです。2,000件を超える検索結果を取得する必要がある場合には、4.2.2 全件取得(scroll)を参照してください。

４.２.1 fromとsizeによる指定

sizeとfromのデフォルト値は次の通りです。

size=20
from=0

一度の検索で取得可能な上限（つまりsizeの値の上限）は500件まで、検索結果全体で2,000件までの結果を取得できます。

以下のクエリ例を試して、レスポンスにおけるhitの値、fsromの値、listプロパティの配列のサイズを確認してみてください。

⚫️ギャラリーを空検索し、検索結果を冒頭から(from=0)、最大100件(size=100)取得する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/gallery?csid=jps-gallerycs&from=0&size=100

簡易Web APIのURL

https://jpsearch.go.jp/api/curation/search?from=0&size=100

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/curation/search \
			--data-urlencode from=0 \
			--data-urlencode size=100 \
			| jq -r '"\(.hit) \(.from) \(.list|length)"'

⚫️連携データベースを空検索し、検索結果を冒頭から(from=0)、最大100件(size=100)取得する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/database?from=0&size=100

簡易Web APIのURL

https://jpsearch.go.jp/api/database/search?from=0&size=100

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/database/search \
			--data-urlencode from=0 \
			--data-urlencode size=100 \
			| jq -r '"\(.hit) \(.from) \(.list|length)"'

⚫️連携データベースを空検索し、検索結果を200件目から(from=200)、最大100件(size=100)取得する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/database?from=200&size=100

簡易Web APIのURL

https://jpsearch.go.jp/api/database/search?from=200&size=100

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/database/search \
			--data-urlencode from=200 \
			--data-urlencode size=100 \
			| jq -r '"\(.hit) \(.from) \(.list|length)"'

4.2.2 全件取得(scroll)

アイテム検索APIにおいて、検索結果を全件取得するためのAPIです。

エンドポイント

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

scroll APIに問い合わせると、検索結果のスナップショットが一時的に作成され、スナップショット毎にユニークな参照用のscrollIdが払い出されます。 scrollIdを指定することで検索結果の全件を200件ずつ順番に取得することができます。

1) 初回のリクエスト

初回のリクエストでは、searchと同じように、検索パラメータを指定します。

JSONレスポンスにscrollIdプロパティが含まれます。またfacetsプロパティは空になります。

$ curl -sG https://jpsearch.go.jp/api/item/scroll/jps-cross \
			--data-urlencode keyword=一遍聖絵 \
			| jq

			{
				"list": [
					{
						...
					},
					...
				]
				"hit": 398,
				"facets": [],
				"scrollId": "FGluY...略...UcwUQ=="
			}

2) 2回目以降のリクエスト

レスポンスに含まれるscrollIdの値を次のクエリで指定することで、後続する次の200件分を取得することができます。

クエリパラメータ

scrollId={scrollIdの値}

$ curl -sG https://jpsearch.go.jp/api/item/scroll/jps-cross \
			--data-urlencode scrollId=FGluY...略...UcwUQ== \
			| jq 

			{
				"list": [
					{
						...
					},
					...
				]
				"hit": 398,
				"facets": [],
				"scrollId": "FGluY...略...UcwUQ=="
			}

3) 最後のリクエスト

レスポンスにscrollIdプロパティが存在しない場合、 scrollによるページネーションを終了します。レスポンスのlistプロパティは空になります。

$ curl -sG https://jpsearch.go.jp/api/item/scroll/jps-cross \
			--data-urlencode scrollId=FGluY...略...UcwUQ== \
			| jq 

			{
				"list": [],
				"hit": 398,
				"facets": []
			}

4章 検索APIの基本クエリパラメータ

4.1 検索キーワード

4.1.1 検索条件の結合方法について

4.1.2 アイテム検索

4.1.3 ギャラリー検索

4.1.4 連携データベース検索

4.1.5 連携機関検索

4.1.6 テーマ別検索に対する検索

４.２ ページネーション

４.２.1 fromとsizeによる指定

4.2.2 全件取得(scroll)

1) 初回のリクエスト

2) 2回目以降のリクエスト

3) 最後のリクエスト

4章検索APIの基本クエリパラメータ

４.２ページネーション