6章 アイテムに対する特殊な検索

6章ではアイテム検索APIのエンドポイントを利用した特殊な検索について説明します。

6.1 画像検索

画像検索機能として類似画像検索機能及びモチーフ検索機能をサポートしています。

6.1.1 類似画像検索 image

「画像から類似した別の画像を検索する」機能であり、サムネイル画像を持つアイテムのIDをクエリパラメータはimageで指定すると、似たサムネイル画像を持つアイテムの一覧が取得できます。

クエリパラメータ

image={アイテムID}

ジャパンサーチの横断検索UIの検索結果画面や個々のアイテム詳細画面において「類似画像検索アイコン」をクリックしたときの動作に相当します。

⚫️ColBaseに収録されている「能面 小面」(cobas-59051)の類似画像を横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&image=cobas-59051

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?image=cobas-59051

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode image=cobas-59051 | jq

6.1.2 モチーフ検索 text2image

「任意の文字列から想起される画像を検索する」機能であり、画像のモチーフをテキストでクエリパラメータtext2imageに指定すると、該当するサムネイル画像を持つアイテムの一覧が取得できます。

クエリパラメータ

image2text={モチーフのテキスト}

レスポンスのlistプロパティにあるcommon.thumbnailUrlが、類似するサムネイル画像のURLになります。

ジャパンサーチの横断検索UIにおける「画像の中身を検索」の検索窓に相当します。

⚫️「鶴の日本画」に近いモチーフの画像を横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&text2image=鶴の日本画

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?text2image=鶴の日本画

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode text2image=鶴の日本画 | jq

6.2 時間、場所、人物で検索

ジャパンサーチ利活用スキーマを利用した検索機能をサポートしています。

6.2.1 「時間/時代」で検索 q-tempo

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

クエリパラメータ

q-tempo={時間/時代のテキスト}

ジャパンサーチの横断検索UIにおける「時間/時代」の絞り込み条件に相当します。

「5.1.6 時間/時代 f-tempo」との違いは、コード値ではなく文字列による検索を行う点です。

レスポンスのlistプロパティにあるrdfindex.temporalに、指定した「時間/時代」の文字列が含まれるアイテムを取得できます。

⚫️「時間/時代」が「南北朝」のアイテムを横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&q-tempo=南北朝

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?q-tempo=南北朝

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode q-tempo=南北朝　| jq

⚫️「時間/時代」が「明徳4年」のアイテムを横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&q-tempo=明徳4年

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?q-tempo=明徳4年

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode q-tempo=明徳4年 | jq

6.2.2 「場所」で検索 q-loc

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

クエリパラメータ

q-loc={場所のテキスト}

これはジャパンサーチの横断検索UIにおける「場所」の絞り込み条件に相当します。

レスポンスのlistプロパティにあるcommon.locationを見ると、指定した「場所」の文字列が含まれているのがわかります。

⚫️「場所」が「西荻窪」のアイテムを横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&q-loc=西荻窪

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?q-loc=西荻窪

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode q-loc=西荻窪 | jq

6.2.3 「人物/団体」で検索 q-contributor

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

クエリパラメータ

q-contributer={人物/団体のテキスト}

これはジャパンサーチの横断検索UIにおける「人物/団体」の絞り込み条件に相当します。

レスポンスのlistプロパティにあるcommon.contributorを見ると、指定した「人物/団体」の文字列が含まれているのがわかります。

⚫️「人物/団体」が「藤原定家」のアイテムを横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&q-contributor=藤原定家

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?q-contributor=藤原定家

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode q-contributor=藤原定家 | jq

6.3 正規化機能で検索

6.3で説明するクエリパラメータは、以下のエンドポイントで実行できます。

エンドポイント

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

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

注意:

このAPIを利用したUIは今後公開予定ですが、APIについては二次利用の促進のために前倒して提供しています。 本機能はジャパンサーチに登録されたメタデータの検索を補助する目的で、機械的に付与しているものです。付与されている情報が必ずしも正確でない点にご留意ください。

6.3.1 正規化された「時間」で検索 r-tempo

メタデータに含まれる時間表現を正規化した情報を利用して、年代情報をレンジ（いつからいつまで）で検索することができます。

クエリパラメータ

r-tempo=(始点),(終点)

始点と終点は、4桁の西暦年(yyyy)で指定してください。

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

レスポンスのlistプロパティにあるcommon.temporalを見ると、指定した「時間」レンジ内に含まれているのがわかります。

⚫️ アイテムを1156年から1159年までの期間で横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&r-tempo=1156,1159

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?r-tempo=1156,1159

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode r-tempo=1156,1159 | jq

6.3.2 正規化された「場所」で検索 g-coordinates

特定の緯度経度を指定してある「場所」の周辺を検索することができます。 メタデータに含まれる地名や住所は緯度経度に変換（正規化）されています。この正規化された場所情報を検索対象にしてます。

以下は正規化の例になります。

クエリパラメータ

g-coordinates=(緯度),(経度),(半径)

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

レスポンスのlistプロパティにあるcommon.coordinatesを見ると、指定した緯度経度の周辺が含まれているのがわかります。

住所についてはGeoNLPが作成した日本の郡・市区町村（2013年9月）を利用しています。 住所に対する正規化は、基本的には市町村区までの緯度経度であり、当該地域の都道府県市町村役場の所在地が入ります。 例：東京都千代田区永田町1-10-1であれば、東京都千代田区役所の所在地の緯度経度。

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

⚫️ アイテムを北緯35.29784、東経139.47745、半径200m（神奈川県藤沢市江ノ島の周辺）で横断検索する例

ジャパンサーチUIのURL

https://jpsearch.go.jp/csearch/jps-cross?csid=jps-cross&g-coordinates=35.29784,139.47745,200m

簡易Web APIのURL

https://jpsearch.go.jp/api/item/search/jps-cross?g-coordinates=35.29784,139.47745,200m

curlコマンド

$ curl -sG https://jpsearch.go.jp/api/item/search/jps-cross \
--data-urlencode g-coordinates=35.29784,139.47745,200m | jq