1章 簡易Web APIの概要

1.1 用語について

ジャパンサーチは、多数の「連携機関」が提供する「連携データベース」を⼀元的に統合して、横断的に検索・閲覧・活⽤できるプラットフォームです。

「連携データベース」の内容は多様で、 書籍・公⽂書・⽂化財・美術・⼈⽂学・⾃然史/理⼯学・学術資産・放送番組・映画など、 様々な分野のコンテンツのメタデータが登録されています。

ジャパンサーチの簡易WEB APIは、以下の5種類のメタデータを扱います。

1. アイテム

ジャパンサーチに登録されている、個々のコンテンツを表現するメタデータの集合単位（ジャパンサーチの検索結果詳細画面で表示される情報）を指します。

メタデータとは、コンテンツの内容、外形、所在等を記述したデータのことです。いくつか例を挙げると、メタデータには、次のようなものがあります。

連携データベースに登録されたアイテムのメタデータ項目のうち、 共通項目（詳しくは「2.1.1共通項目」を参照）に該当する項目については、 クエリパラメータを指定することで、横断的に検索することができます。

2. 連携データベース

アイテムを構成するメタデータをジャパンサーチに提供しているデータベースを指します。 各アイテムは必ず1つの連携データベースの情報を保持しています。

3. 連携機関

ジャパンサーチに連携データベースとしてメタデータ等の情報を提供している機関を指します。

4. ギャラリー

様々なテーマに沿って「アイテム」を集め、編集して作成したページが「ギャラリー」です。 「ギャラリー」は、UIでの閲覧を前提にしていますが、ページに関するメタ情報をWEB APIで参照・検索できます。 例えば、連携機関の担当者が作成したギャラリーをAPIから参照し、自分の機関のホームページに掲載するといった活用が可能です。

5. テーマ別検索

ジャパンサーチでは、特定のテーマに即した検索を行うためのあらかじめ用意された検索式を呼び出すことができる「テーマ別検索」の機能が提供されています。

これら5種類のメタデータは、それぞれ独立したエンドポイントから参照・検索することができます。

1.2 APIの種類

この文書では、「参照系」と「検索系」を以下のように区別します。

これに対応して、APIは以下のように二分されます。

ジャパンサーチに登録された各種メタデータのうち、簡易Web APIを用いて取得できる情報は、 当該アイテムの格納された連携データベースを提供している連携機関がAPI提供を許可している場合に限定されます。

1.3 APIのプロトコル

HTTPSプロトコルを使用します。

この⽂書で解説するAPIは、すべてGETメソッドを用います。

レスポンスのデータフォーマットはJSONです。

クエリパラメータとレスポンスのエンコーディングはUTF-8です。

この文書では、APIクエリ（エンドポイントとクエリパラメータ）の例を、以下の2通りの方法で示します。

ブラウザ上でURLリンクを参照することでAPIのレスポンスを確認する際は、 Firefox,やMicrosoft EdgeのようにデフォルトでJSONを整形して表示するブラウザを利用するか、 Google Chrome等整形機能のないブラウザの場合にはJSONを整形して表示するプラグインをインストールして参照することを推奨します。