2章 参照API
2章では個々のメタデータの情報を指定してアクセスするための参照APIについて、各エンドポイントとレスポンスのデータ形式を説明します。 参照APIのエンドポイントに含まれるメタデータの名前は、次のとおりです。
- アイテム: item
- 連携データベース: database
- 連携機関: organization
- ギャラリー: curation
- テーマ別検索: csearch
2.1 アイテム参照API
エンドポイントの形式
https://jpsearch.go.jp/api/item/{アイテムID}
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | アイテムID | |
| common | オブジェクトの配列 | 詳細は2.1.1参照 | |
| rdfindex | オブジェクトの配列 | 詳細は2.1.2参照 | |
| {データベースID}-xx | 複数 | 文字列 | 詳細は2.1.3参照 |
※{データベースID}-xxの「xx」には任意の半角英数字文字列が入る
⚫️「東京富士美術館収蔵品データベース」(tfam_art_db)の「若い婦人の肖像」(tfam_art_db-1232)を参照する例
ジャパンサーチUI上の詳細画面のURL
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/tfam_art_db-1232 | jq
なお、ジャパンサーチUI上の詳細画面のURLの末尾に「.json」を付すことで簡易Web APIのURLにリダイレクトされます。
次に、各プロパティについて説明します。
2.1.1 common
commonは、共通項目と呼ばれ、データベース間に共通する項目を表しています。 commonの下位には次のプロパティが格納されます。
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | アイテムID | |
| title | 文字列 | 名称/タイトル | |
| titleEn | 文字列 | 名称/タイトル英語 | |
| titleYomi | 文字列 | 名称/タイトルヨミ | |
| thumbnailUrl | 文字列の配列 | サムネイル画像URL | |
| contentsUrl | 文字列の配列 | コンテンツURL | |
| linkUrl | 文字列 | 連携データベースにおける当該アイテムのURL | |
| iiifUrl | 文字列 | IIIFマニフェストURL | |
| contentsType | 文字列 | コンテンツフォーマット | |
| contentsRightsType | 文字列 | コンテンツの権利区分 | |
| contentsAccess | 文字列の配列 | コンテンツ公開状況 | |
| category | 文字列の配列 | カテゴリー | |
| description | 文字列 | 解説 | |
| descriptionEn | 文字列 | 解説（英語） | |
| contributor | 文字列の配列 | 人物/団体 | |
| temporal | 文字列の配列 | 時間/時代 | |
| location | 文字列の配列 | 場所 | |
| provider | 文字列 | 所属機関 | |
| ownerOrg | 文字列 | つなぎ役機関 | |
| database | 文字列 | データベース | |
| apiType | 文字列 | API対応 | |
| subCategory | 文字列の配列 | サブカテゴリー | |
| access | 文字列 | 公開範囲 | |
| dclass | 文字列 | 分類（自動付与） |
2.1.2 rdfindex
rdfindexは、ジャパンサーチ利活用スキーマによって変換したアイテムの情報を、 ジャパンサーチに書き戻すことで追加した情報を表しています。
これらのプロパティに記述された内容は、元データベースの情報をもとに、ジャパンサーチが加工及び正規化した情報が格納されています。詳しくは6.3正規化機能検索をご覧ください。
rdfindexの下位には次のプロパティが格納されます。
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| type | 文字列の配列 | 種類 | |
| temporal | 文字列の配列 | 時代情報 | |
| spatial | 文字列の配列 | 場所情報 |
2.1.3 {データベースID}-xx
{データベースID}-から始まる項目は、個別項目と呼ばれ、データベースが元々保持していたアイテムの情報を格納しています。
次のエンドポイントで個別項目を含むデータベースのラベル定義情報を取得できます。
エンドポイント
https://jpsearch.go.jp/api/database/{データベースID}/label
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | データベースID | |
| edit | オブジェクト | 最終更新者や最終更新日の情報を格納する。 | |
| userId | 文字列 | 最終編集者のID | |
| orgId | 文字列 | 最終編集した連携機関のID | |
| date | 数値 | 最終更新日 | |
| action | 文字列 | 当該アイテムのCRUD情報（更新ならUPDATE、新規追加ならCREATE） | |
| fieldLabels | オブジェクトの配列 | 個別項目のラベル情報 | |
| path | 文字列 | アイテム参照APIにおける{データベースID}-xxと対応付くプロパティの名前 | |
| originalPath | 文字列 | 連携データベースにおける元の階層構造のパス | |
| storeType | 文字列 | 当該個別項目の格納種別情報。（normal：通常、guionly：APIから取得できない項目、ignore：ジャパンサーチには登録されない項目） | |
| indexType | 文字列 | 当該個別項目のインデックス種別情報。（string：文字列、keyword：完全一致文字列、html：ハイパーテキスト、uri：URI、date：日付、latlon：座標、code：コード値、number：数字、exists：データ有無を表すブール値） | |
| label | オブジェクト | 当該個別項目の名称。日本語表記(ja)と英語表記(en)が存在する。 | |
| unique | 数値 | 当該個別項目の値のユニーク数 | |
| filled | 数値 | 当該個別項目の値の充足数 | |
| description | オブジェクト | 個別項目の説明。日本語表記(ja)と英語表記(en)が存在する。 | |
| commonLabels | オブジェクトの配列 | 共通項目のマッピング情報 | |
| path | 文字列 | 当該共通項目に指定されたfieldLabelsのoriginalPath | |
| commonType | 文字列 | 該当するcommonプロパティの名前 |
⚫️データベース「ColBase」(cobas)のデータソース項目を参照する例
ジャパンサーチUIのURL
N/A ※ジャパンサーチのUIにデータベースのラベル定義情報を表示する画面はありません
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/database/cobas/label | jq
⚫️データベース「ColBase」(cobas)のラベル定義情報を参照する例
fieldLabelsプロパティのラベル名称(path)とラベルの日本語表記(label.ja)を取得する場合。
curlコマンド
$ curl -s https://jpsearch.go.jp/api/database/cobas/label \
| jq -c '.fieldLabels | sort_by(.originalPath|tonumber)' \
| jq -r '.[] | "\(.path): \(.label.ja)"'
cobas-0-s: JPS_ID
cobas-1-u: URL
cobas-2-s: 機関管理番号
cobas-3-s: 文化財指定
cobas-4-s: 分類
cobas-5-s: 作品名
cobas-6-s: 作品名かな
...
個別項目のpathとcommonプロパティのcommonTypeの対応関係を抽出する場合。
curlコマンド
$ curl -s https://jpsearch.go.jp/api/database/cobas/label \
| jq -c '.commonLabels |sort_by(.path|tonumber)' \
| jq -r '.[] | "\(.path): \(.commonType)"'
0: id
1: linkUrl
5: title
6: titleYomi
...
2.2 連携データベース参照API
エンドポイント
https://jpsearch.go.jp/api/database/{連携データベースID}
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | 連携データベースID | |
| recordCount | 数値 | 当該データベースのメタデータ件数 | |
| lastDataUpdated | 数値 | 最終更新日 | |
| currentCollecting | 文字列 | 現在公開されている収集ID（システム情報） | |
| name | オブジェクト | データベース名称 | |
| ja | 文字列 | 日本語表記 | |
| en | 文字列 | 英語表記 | |
| yomi | 文字列 | ふりがな | |
| description | オブジェクト | データベースの説明文。日本語表記(ja)と英語表記(en)が存在する。 | |
| url | 文字列 | 連携データベースのURL | |
| category | 文字列の配列 | データベースのカテゴリを示すコード値（コード値の詳細については3.2.2.3を参照） | |
| metadataRights | オブジェクト | メタデータの権利表示。日本語表記(ja)と英語表記(en)が存在する。 | |
| apiType | 文字列 | API提供可のデータベースかどうかを示すコード値(ok:可、ng:不可) | |
| thumbnailRights | オブジェクト | サムネイル画像の権利表示。日本語表記(ja)と英語表記(en)が存在する。 | |
| contentsRightsType | 文字列 | コンテンツの権利区分を示すコード値（コード値の詳細については3.2.2.1 を参照） | |
| contentsRights | オブジェクト | コンテンツの権利表示。日本語表記(ja)と英語表記(en)が存在する。 | |
| contentsAccess | 文字列 | コンテンツの公開情報を示すコード値（コード値の詳細については3.2.2.2 を参照） | |
| contentsType | 文字列 | コンテンツ種別（コード値の詳細については3.2.2.2 を参照） | |
| image | オブジェクト | 代表画像情報（システム情報） | |
| provider | 文字列 | 所蔵機関名 | |
| providerUrl | 文字列 | 所蔵機関URL | |
| notification | オブジェクト | お知らせ情報 | |
| easyIIIF | ブール値 | 簡易IIIF機能を利用しているかを示すブール値（システム情報） | |
| rdfEnabled | ブール値 | 利活用スキーマに対応したデータベースかを示すブール値（システム情報） | |
| rdfDate | 数値 | 最後に利活用スキーマへ変換を行った日付（システム情報） | |
| permission | オブジェクト | システム情報 | |
| publicationLevel | 文字列 | - | |
| level | 文字列 | - | |
| ownerOrg | 文字列 | - |
⚫️連携データベース「上田市立美術館収蔵品」(u003)の情報を参照する例
ジャパンサーチUIのURL
簡易Web APIのURL
$ curl -sG https://jpsearch.go.jp/api/database/u003 | jq
2.3 連携機関参照API
エンドポイント
https://jpsearch.go.jp/api/organization/{連携機関ID}
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | 連携機関ID | |
| name | オブジェクト | 連携機関名称 | |
| ja | 文字列 | 日本語表記 | |
| en | 文字列 | 英語表記 | |
| yomi | 文字列 | ふりがな | |
| aliases | 文字列の配列 | 連携機関名称の別名 | |
| description | オブジェクト | 連携機関の説明文。日本語表記(ja)と英語表記(en) が存在する。 | |
| url | 文字列 | 連携機関のHP等URL | |
| location | 文字列 | 連携機関の所在地 | |
| image | オブジェクト | 代表画像情報（システム情報） | |
| status | 文字列 | システム情報 | |
| type | 文字列 | システム情報 | |
| permission | オブジェクト | システム情報 | |
| publicationLevel | 文字列 | - | |
| level | 文字列 | - | |
| ownerOrg | 文字列 | - | |
| created | 数値 | ページ作成日 |
⚫️連携機関「上田市」(UedaUMIC)の情報を参照する例
ジャパンサーチUIのURL
簡易Web APIのURL
$ curl -sG https://jpsearch.go.jp/api/organization/UedaUMIC | jq
2.4 ギャラリー参照API
エンドポイント
https://jpsearch.go.jp/api/curation/{ギャラリーID}
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | ギャラリーID | |
| curationType | 文字列 | "GALLERY"が入る | |
| title | オブジェクト | ギャラリー名称 | |
| ja | 文字列 | 日本語表記 | |
| en | 文字列 | 英語表記 | |
| yomi | 文字列 | ふりがな | |
| summary | オブジェクト | ギャラリーの1行概要。日本語表記(ja)と英語表記(en)が存在する。 | |
| rights | オブジェクト | 二次利用条件表示（HTML可）。日本語表記(ja)と英語表記(en)が存在する。 | |
| rightsType | 文字列 | 権利区分を示すコード値（コード値の詳細については3.2.2.1 を参照） | |
| tag | オブジェクトの配列 | タグ（トピックやキーワード） | |
| id | 文字列 | タグを示すコード値。トピック系(o-)とキーワード系(w-)が存在する。 | |
| label | オブジェクト | タグ名称。日本語表記(ja)と英語表記(en)が存在する。 | |
| responsibility | オブジェクト | 責任表示。日本語表記(ja)と英語表記(en)が存在する。 | |
| image | オブジェクト | ||
| url | 文字列 | ギャラリーの代表画像のコンテンツURL | |
| thumbnailUrl | 文字列 | ギャラリーの代表画像のサムネイルURL | |
| itemId | 文字列 | ジャパンサーチ内のアイテムを利用する場合、アイテムIDが入る | |
| itemIndex | 文字列 | 代表画像が複数ある場合のインデックス | |
| imgType | 文字列 | 画像の登録方法を表すコード値（システム情報） | |
| x | 数値 | （代表画像の一部を切り出している場合）左上x座標 | |
| y | 数値 | （代表画像の一部を切り出している場合）左上y座標 | |
| w | 数値 | （代表画像の一部を切り出している場合）切り出しの幅 | |
| h | 数値 | （代表画像の一部を切り出している場合）切り出しの高さ | |
| title | オブジェクト | 代表画像の名称。日本語表記(ja)と英語表記(en)が存在する。 | |
| description | オブジェクト | 代表画像の説明。日本語表記(ja)と英語表記(en)が存在する。 | |
| source | オブジェクト | 代表画像の出典。日本語表記(ja)と英語表記(en)が存在する。 | |
| permission | オブジェクト | システム情報 | |
| publicationLevel | 文字列 | - | |
| level | 文字列 | - | |
| ownerOrg | 文字列 | - | |
| edit | オブジェクト | システム情報 | |
| orgId | 文字列 | - | |
| date | 数値 | - | |
| parts | - | オブジェクトの配列 | ページの詳しい構造が記述される領域 |
⚫️ギャラリー「燕子花・杜若」(ndl-ZwlK4987YNP)を参照する例
ジャパンサーチUIのURL
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/curation/ndl-ZwlK4987YNP | jq
2.4.1 連携データベースページの参照
ジャパンサーチの連携データベースを紹介するページを参照できます。
エンドポイント
https://jpsearch.go.jp/api/curation/{連携データベースID}-db
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | {連携データベースID}-db | |
| curationType | 文字列 | "DB"が入る | |
| title | オブジェクト | データベース名称 | |
| summary | オブジェクト | 不使用 | |
| rights | オブジェクト | 不使用 | |
| tag | オブジェクトの配列 | 不使用 | |
| responsibility | オブジェクト | 不使用 | |
| permission | オブジェクト | ページの公開状況 | |
| edit | オブジェクト | システム情報 | |
| parts | オブジェクトの配列 | ページの詳しい構造が記述される領域 |
ギャラリー参照APIのレスポンスのサブセットになります。
⚫️連携データベース「国立国会図書館デジタルコレクション」(ndl)の紹介ページを参照する例
ジャパンサーチUIのURL
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/curation/dignl-db | jq
2.4.2 連携機関ページの参照
ジャパンサーチの連携機関を紹介するページを参照できます。
エンドポイント
https://jpsearch.go.jp/api/curation/{連携機関ID}-org
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | 連携機関ID-org | |
| curationType | 文字列 | "ORGANIZATION"が入る | |
| title | オブジェクト | 連携機関名称 | |
| summary | オブジェクト | 不使用 | |
| rights | オブジェクト | 不使用 | |
| tag | オブジェクトの配列 | 不使用 | |
| responsibility | オブジェクト | 不使用 | |
| permission | オブジェクト | ページの公開状況 | |
| edit | オブジェクト | システム情報 | |
| parts | オブジェクトの配列 | ページの詳しい構造が記述される領域 |
ギャラリー参照APIのレスポンスのサブセットになります。
⚫️連携機関「国立国会図書館」(ndl)の紹介ページを参照する例
ジャパンサーチUIのURL
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/curation/ndl-org | jq
2.5 テーマ別検索参照API
エンドポイント
https://jpsearch.go.jp/api/csearch/{テーマ別検索ID}
JSONレスポンス
| プロパティ | データ型 | 説明 | |
|---|---|---|---|
| id | 文字列 | テーマ別検索ID | |
| name | オブジェクト | テーマ別検索名称。日本語表記(ja)と英語表記(en)が存在する。 | |
| type | 文字列 | "DB" 、"NOTE"または"NORMAL"が入る | |
| description | オブジェクト | テーマ別検索の説明。日本語表記(ja)と英語表記(en) が存在する。 | |
| databaseIds | 文字列の配列 | 検索対象となる連携データベースID | |
| searchFields | オブジェクトの配列 | 検索フィールドの定義 | |
| key | 文字列 | 検索フィールド名 | |
| name | オブジェクト | 検索フィールドのラベル。日本語表記(ja)と英語表記(en) | |
| type | 文字列 | 当該個別項目のインデックス種別情報。（string：文字列、keyword：完全一致文字列、html：ハイパーテキスト、uri：URI、date：日付、latlon：座標、code：コード値、number：数字、exists：データ有無を表すブール値） | |
| fields | 文字列の配列 | 検索対象となるフィールド名 | |
| hasFacet | ブール値 | ファセットの有無 | |
| constraints | オブジェクトの配列 | 検索条件 | |
| c | 文字列 | 検索条件の結合法 | |
| q | オブジェクト | 検索条件の詳細 | |
| columns | オブジェクトの配列 | 検索結果を表示する表の情報 | |
| header | 文字列 | 表のヘッダー。日本語表記(ja)と英語表記(en)が存在する。 | |
| fields | 文字列の配列 | 対象フィールド（個別項目のパスが入る） | |
| type | 文字列 | カラム種別（システム情報） | |
| keywordFields | 文字列の配列 | キーワード検索の対象フィールド | |
| keywordPlaceholder | オブジェクト | テーマ別検索のプレースフォルダー値 | |
| sampleQuery | 文字列の配列 | サンプルとなるクエリ文字列 | |
| image | オブジェクト | 画像 | |
| permission | オブジェクト | システム情報 | |
| publicationLevel | 文字列 | - | |
| level | 文字列 | - | |
| ownerOrg | 文字列 | - | |
| edit | オブジェクト | システム情報 |
⚫️テーマ別検索「南画検索」(ndl-DB7B6wq3pBTD6b)の定義情報を参照する例
ジャパンサーチUIのURL
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/csearch/ndl-DB7B6wq3pBTD6b | jq
itemエンドポイントで「テーマ別検索ID」を指定すると、テーマ別検索を実行できます。
エンドポイント
https://jpsearch.go.jp/api/item/search/{テーマ別検索ID}
⚫️テーマ別検索「南画検索」(ndl-DB7B6wq3pBTD6b)を実行する例
ジャパンサーチUIのURL
https://jpsearch.go.jp/csearch/ndl-DB7B6wq3pBTD6b?csid=ndl-DB7B6wq3pBTD6b
簡易Web APIのURL
curlコマンド
$ curl -sG https://jpsearch.go.jp/api/item/search/ndl-DB7B6wq3pBTD6b | jq
searchFieldsのfasFacetプロパティがtrueの場合、レスポンスにfacetsプロパティが含まれます。
次のcurlコマンドから、hasFacetがtrueのフィールド(fc1とfc3)が、実行結果レスポンスのfacetsプロパティのキーになっているのがわかります。
⚫️テーマ別検索「南画検索」(ndl-DB7B6wq3pBTD6b)の定義情報からsearchFieldsプロパティを抜粋する例
$ curl -sG https://jpsearch.go.jp/api/csearch/ndl-DB7B6wq3pBTD6b | jq .searchFields
[
{
"key": "fc3",
"name": {
"ja": "作者"
},
"type": "keyword",
"fields": [
"cobas-8-s"
],
"hasFacet": true
},
{
"key": "fc1",
"name": {
"ja": "データベース"
},
"type": "database",
"fields": [
"common.database"
],
"hasFacet": true
}
]
⚫️テーマ別検索「南画検索」(ndl-DB7B6wq3pBTD6b)の実行結果からfacetsプロパティを抜粋する例
$ curl -sG https://jpsearch.go.jp/api/item/search/ndl-DB7B6wq3pBTD6b | jq .facets
[
{
"key": "fc3",
"counts": {
"池大雅筆": 26,
"椿椿山筆": 11,
"谷文晁筆": 11,
"青木木米作": 9,
"田能村竹田筆": 8,
"浦上玉堂筆": 4,
"与謝蕪村筆": 3,
"富岡鉄斎筆": 3,
"祇園南海筆": 3,
"伝谷文晁筆": 2
}
},
{
"key": "fc1",
"counts": {
"cobas": 124,
"bunka": 65,
"dignl": 41
}
}
]