次世代デジタルライブラリーのAPIについて
APIから検索・取得可能なデータ
次世代デジタルライブラリーAPIは、次世代デジタルライブラリーの収録資料（著作権保護期間が満了した図書28万点及び古典籍資料8万点）の次の情報を検索・取得できます。
- 書誌データ
- OCR全文テキストデータ（各文字列の 紙面上の座標情報を含む。）
- 資料画像から抽出した図版（挿絵、写真、図表等）領域の座標情報及び画像検索用特徴ベクトルデータ
APIのご利用に当たって
次世代デジタルライブラリーの説明ページの「ご利用に当たって」をご確認ください。
APIの説明
次世代デジタルライブラリーAPIは大きく分けて「Book API」「Illustration API」「Page API」の3種類を提供しています。 各APIの概要と指定可能なパラメータについて以下説明します。最新の返戻の形式については、（技術者向け）Swagger UIを利用したAPIドキュメントの見方を参照してください。
1. Book API
1.1. 資料検索API
収録資料の書誌データやOCR全文テキストデータを利用して、資料の横断検索を行うことができます。キーワードにヒットした箇所の前後の文字について、最大3箇所までスニペットとして取得できます。
クエリの例：
https://lab.ndl.go.jp/dl/api/book/search?keyword=ペンギン
次のクエリパラメータを指定可能です。（※は必須）
| パラメータ名 | 例 | 説明 |
|---|---|---|
| keyword(※) | ペンギン | 検索キーワード |
| size | 20 | 取得件数（デフォルトは20件） |
| from | 0 | 検索結果の表示開始位置。デフォルトの場合、最初の結果からsize件目までの結果が返る。 |
| searchfield | contentonly | 検索フィールドの指定。contentonlyを指定すると本文テキストのみ検索する。metaonlyを指定すると書誌データのみを検索する。デフォルトは全ての項目を対象とする。 |
| f-ndc | 9* | NDC（日本十進分類法（第９版））による絞り込み（前方一致） |
| fc-isClassic | true | 検索結果を古典籍資料のみに絞りたい場合はtrueを、逆に古典籍資料を除外したい場合はfalseを指定する。デフォルトは指定なし。 |
| withouthighlight | true | trueにした場合、返戻にスニペットを含めない（応答が高速になる）。デフォルトはfalse。 |
1.2. 資料メタデータ取得API
PID（※）を指定して収録資料の書誌データを取得できます。
（※）永続的識別子。URL「https://lab.ndl.go.jp/dl/api/book/ 」に続く数字で表される値。
なお、このAPIではOCR全文テキストデータの取得はできません。
取得可能なデータ形式の説明については、Swagger UI下部のModels->Bookを参照してください。
クエリの例：
https://lab.ndl.go.jp/dl/api/book/897115
指定可能なクエリパラメータはありません。
1.3. 全文テキストデータ一括ダウンロードAPI（json）
指定したPIDの資料全体のOCR全文テキストデータを取得できます。当該資料に含まれる各コマについて、フラットなテキストデータ（contents）やOCR全文テキストデータと対応する座標情報(coordjson)等が含まれます。
クエリの例：
https://lab.ndl.go.jp/dl/api/book/fulltext-json/897115
指定可能なクエリパラメータはありません。
1.4. 全文テキストデータ一括ダウンロードAPI（zip形式）
指定したPID資料全体のOCR全文テキストデータを取得できます。このAPIは、OCR全文テキストデータと対応する座標を記述したjson形式の情報と、フラットなOCR全文テキストデータの情報をzip形式に圧縮して取得します。フラットなOCR全文テキストデータを取得できる点及び当該資料全コマのOCR全文テキストデータを連結したファイルを同時に取得できる点の2点が1.3全文テキストデータ一括ダウンロードAPI（json）とは異なります。
クエリの例：
https://lab.ndl.go.jp/dl/api/book/fulltext/897115
指定可能なクエリパラメータはありません。
2. Page API
2.1. 資料内検索API
Page APIを利用すると、指定した資料の中身を全文検索することができます。資料内のヒットしたコマ全ての結果を1コマ当たり1箇所スニペットとして取得します。
クエリの例：
https://lab.ndl.go.jp/dl/api/page/search?f-book=1716435&q-contents=ペンギン
次のクエリパラメータを指定可能です。（※は必須）
| パラメータ名 | 例 | 説明 |
|---|---|---|
| f-book（※） | 1716435 | 検索対象とする資料のPID |
| q-contents（※） | ペンギン | 検索キーワード |
| size | 20 | 取得件数（デフォルトは20件） |
| from | 0 | 検索結果の表示開始位置。デフォルトの場合、最初の結果からsize件目までの結果が返る。 |
| searchfield | contentonly | 検索フィールドの指定。contentonlyを指定すると本文テキストのみ検索する。metaonlyを指定すると書誌データのみを検索する。デフォルトは全ての項目を対象とする。 |
2.2. ページ（コマ）データ取得API
指定したページ（コマ）のデータを取得します。資料のPIDとページ（コマ）番号を_（アンダースコア）でつなぐことでページを指定できます。
取得可能なデータ形式の説明については、Swagger UI下部のModels->Pageを参照してください。
クエリの例：
https://lab.ndl.go.jp/dl/api/page/897115_1
指定可能なクエリパラメータはありません。
3. Illustration API
3.1. 図版メタデータ取得API
指定した図版（挿絵、写真、図表等）のデータ を取得します。資料のPIDとページ（コマ）番号と、0から始まる通し番号を_（アンダースコア）でつなぐことで図版を指定できます。
取得可能なデータ形式の説明については、Swagger UI下部のModels->Illustrationを参照してください。
クエリの例：
https://lab.ndl.go.jp/dl/api/illustration/1221676_1_0
指定可能なクエリパラメータはありません。
3.2. 類似画像検索API（テキストから探す）
クエリパラメータで指定したテキスト（単語や文章）と類似する図版の画像検索の結果を返します。
クエリの例：
https://lab.ndl.go.jp/dl/api/illustration/searchbytext?keyword2vec=ペンギン
次のクエリパラメータを指定可能です。（※は必須）
| パラメータ名 | 例 | 説明 |
|---|---|---|
| keyword2vec（※） | ペンギン | 検索キーワード |
4. 画像データの取得方法
資料画像及び資料画像から切り出した図版画像については、上記のAPIから取得したデータをIIIF Image APIに準拠したURLに加工することで、国立国会図書館デジタルコレクションが提供するIIIF APIを用いてダウンロード可能です。
国立国会図書館デジタルコレクションのIIIFに関するヘルプについても参照ください。
例：PIDが「2558316」の資料の28コマ目の画像を取得するとき
https://dl.ndl.go.jp/api/iiif/2558316/R0000028/full/full/0/default.jpg
URLに0から100までの範囲の比率で表した座標を与えることで、画像上の特定の領域を切り出すことができます。
PIDが「2558316」の資料の28コマ目の画像について、3.1.のillustration API (https://lab.ndl.go.jp/dl/api/illustration/2558316_28_1 )から取得した座標情報(x":56.3,"y":53.3,"w":32.1,"h":26.4)を利用して、切り出した図版画像のIIIF Image APIのURLを取得する例（図1）。
https://www.dl.ndl.go.jp/api/iiif/2558316/R0000028/pct:56.3,53.3,32.1,26.4/full/0/default.jpg
（技術者向け）Swagger UIを利用したAPIドキュメントの見方
Swagger UI(外部リンク)を利用して、ソースコードから動的に仕様を生成したAPIドキュメントを提供しています。クエリを問い合わせた際の具体的なAPIの挙動がWebブラウザ上で確認できます。
ドキュメントの見方 Swagger UIでは次の3つのAPI群に分けて表示しています。 - book-controller（Book API）：収録資料に関するデータを取得・検索するためのAPI群 - illust-controller（Illustration API）：収録資料に含まれる図版に関するデータを取得・検索するためのAPI群 - page-controller（Page API）：資料のページに関するデータを取得・検索するためのAPI群
利用したい機能のAPI群をクリックすると、当該API群に属するAPIが一覧表示されます。
利用したいAPIを選択すると、パラメータの指定方法や返戻の形式が表示されます。
「Try it out」ボタンを押すと、次のような画面になり、Webブラウザ上でAPIを試すことができます。
