国立国会図書館サーチが提供するOAI-PMH

1. OAI-PMHについて

国立国会図書館サーチ(NDLサーチ)では、Webサービスや研究開発等にご活用いただくため、NDLサーチの書誌メタデータをOAI-PMHで提供しています。
OAI-PMHとは、データの自動収集によってメタデータを交換するためのプロトコルです。OAI-PMHの基本仕様は以下のページに記述されています(国立情報学研究所による日本語訳)。

また、国立国会図書館では、これまでのNDLサーチの経験や反省をふまえ、OAI-PMHの概要と実装時の注意点などをまとめた「OAI-PMHの要点」(ZIPファイル)を公開しています。

OAI-PMHの入力形式はURL、出力形式はXMLです。リクエスト種別や取得したいメタデータの条件、フォーマット等を指定したOAI-PMHリクエスト(URL)を送信すると、NDLサーチがそのリクエストを受け取り、リクエストされた条件やフォーマット等に合致するメタデータをXML形式で返戻します。
以下で、NDLサーチのOAI-PMHの使い方をご紹介します。

2. OAI-PMHリクエストURLの作成方法

OAI-PMHのリクエストURLの構成は以下のとおりです。
OAI-PMHのリクエストURLとその構成の図

NDLサーチへのリクエストURLはすべてこの「基本URL」から始まります。基本URLの後ろには、①リクエスト種別と②メタデータの指定条件を記述します。

①リクエスト種別は、次の6種類です。基本URLの後ろに、「verb=リクエスト種別」と記述します。1つのリクエストURLで設定できるリクエスト種別は1つだけです。

リクエスト種別内容
GetRecordNDLサーチの特定の書誌1件のメタデータを取得する
IdentifyNDLサーチがサポートするOAI-PMHについての情報を取得する
ListIdentifiersNDLサーチの全書誌のメタデータID を取得する
ListMetadataFormatsNDLサーチのサポートするメタデータの形式を取得する
ListRecordsNDLサーチのメタデータを取得する
ListSetsNDLサーチのサポートしているset(絞込み条件)を取得する

②メタデータの指定条件は、次の6つです。リクエスト種別の後ろに、「&指定条件=[値]&指定条件=[値]…」 と記述します。なお、リクエストの種類ごとに必須な指定条件や使用可能な指定条件が異なります。

メタデータの指定条件
指定条件内容
identifierNDLサーチの書誌メタデータID を指定する
metadataPrefixリクエストに対して返戻されるメタデータのフォーマットを指定する。oai_dcdcndl (DC-NDL(RDF)) のいずれかを選択可能。DC-NDL(RDF)の内容は、「DC-NDL(RDF)フォーマット仕様」のページを参照。
from日付(datestamp)の下限をYYYY-MM-DDまたはYYYY-MM-DDThh:mm:ssZ形式で指定する
until日付(datestamp)の上限をYYYY-MM-DDまたはYYYY-MM-DDThh:mm:ssZ形式で指定する
set収集対象とするsetパラメータを指定する。詳しくは後述
resumptionToken一度では取得できないメタデータの続きを取得する場合に指定する。1回のリクエストに返戻されるデータの件数の上限は200件なので、201 件以降を取得したい場合には、200 件を取得した際に通知されるresumptionToken を指定してリクエストする
setパラメータについて
NDLサーチでは、特定の属性を持つメタデータのみを取得できるよう、setパラメータを設けています。setとは、メタデータを特定の属性ごとにグループ化する定義です。NDLサーチのOAI-PMHにおけるsetは、以下の3つです。
  • データプロバイダID
  • データプロバイダグループID(オープンデータ、書誌種別、資料種別)
  • コレクション、公開範囲(国立国会図書館デジタルコレクション)

データプロバイダ及びデータプロバイダグループID については、「インターフェース仕様書 附録1」または「API提供対象データプロバイダ一覧」を参照ください。コレクション、公開範囲(国立国会図書館デジタルコレクション)は、データプロバイダ「国立国会図書館デジタルコレクション」のメタデータのうち、特定の集合を指定することができます。国立国会図書館デジタルコレクションに関して、setパラメータの詳細はインターフェース仕様書 附録4を、各コレクションの詳細は、国立国会図書館デジタルコレクションの案内をご覧ください。
setパラメータを指定してリクエストした場合、setパラメータで指定したデータプロバイダないしデータプロバイダグループ、コレクション、公開範囲(国立国会図書館デジタルコレクション)の書誌メタデータのみが返戻されます。たとえば、データプロバイダに「国立国会図書館蔵書」を指定する場合は、「set=iss-ndl-opac」のように指定します。
取得したいメタデータの特性に合わせて、setパラメータを指定してください。

3. OAI-PMHで書誌メタデータを取得する

OAI-PMHで書誌データを取得したい場合は、リクエスト種別にListRecordsを指定します。リクエスト種別の後ろにはメタデータの指定条件を記述しますが、このメタデータの指定条件は以下のとおりパラメータによって必須なもの、任意なものがあります。

ListRecordsリクエストの場合のメタデータの指定条件
指定条件内容
identifier使用不可
metadataPrefix必須
from必須
until任意
set任意
resumptionToken任意 (排他)

fromuntilを使用して特定の期間の書誌メタデータを取得したり、setパラメータを使用して特定のデータプロバイダの書誌メタデータを取得するなど、目的に合わせてメタデータ選択基準の値を設定してください。
なお、resumptionTokenは排他(exclusive)のパラメータです。resumptionTokenを指定する場合は他のパラメータを指定しないでください。
from、untilの指定には次の制約がありますので注意してください。

  • 1年を超える期間を指定することはできない。
  • untilを指定しない場合には、上記の最大の期間がuntilに指定されたものとみなす

リクエスト例は次のとおりです。

その他、OAI-PMHにおける ListRecords以外のリクエストの詳細、及びNDLサーチが提供するAPI全般については、以下をご覧ください。

⇒「API仕様の概要> 3. API仕様書(日本語版)

4. OAI-PMHで国立国会図書館作成の書誌メタデータを取得する

3. OAI-PMHで書誌メタデータを取得するで書誌メタデータを取得する方法をご紹介しましたが、特に国立国会図書館作成の書誌メタデータのみを取得したい場合のリクエストURL作成方法についてご紹介します。
国立国会図書館が提供するAPIデータプロバイダについては「API提供データプロバイダ一覧」の「国立国会図書館作成書誌のデータプロバイダ詳細」をご覧ください。国立国会図書館の書誌データの提供については、国立国会図書館ウェブサイト「書誌データの提供」のページも合わせてご覧ください。

4-1. 「国立国会図書館蔵書」の書誌データ

「国立国会図書館蔵書」(NDL新着書誌情報・全国書誌情報を含む)の書誌データをOAI-PMHで取得する場合、メタデータ選択基準のsetパラメータにiss-ndl-opac、もしくはiss-ndl-opac-nationaliss-ndl-opac-inprocessを指定します(リクエスト種別はListRecordsです)。

リクエスト例は次のとおりです。

4-2. 「国立国会図書館雑誌記事索引」の書誌データ

「国立国会図書館雑誌記事索引」の書誌データをOAI-PMHで取得する場合、メタデータ選択基準のsetパラメータにzassakuまたはzassaku-onlineを指定します。
リクエスト例は次のとおりです。

4-3. 国立国会図書館デジタルコレクションの書誌データ

国立国会図書館デジタルコレクションの書誌データをOAI-PMHで取得する場合は、メタデータ選択基準のsetパラメータにndl-dl、もしくはndl-dl-onlineを指定します(リクエスト種別はListRecordsです)。

リクエスト例は次のとおりです。

4-4. 国立国会図書館作成書誌データの起点日

国立国会図書館作成書誌データの起点日(最も古い更新日のデータ)は、以下のとおりです。

データプロバイダ名データプロバイダID(set)起点日
国立国会図書館蔵書iss-ndl-opac2023-12-16
国立国会図書館新着書誌情報iss-ndl-opac-inprocess2023-12-16
国立国会図書館全国書誌情報iss-ndl-opac-national2023-12-16
国立国会図書館雑誌記事索引zassaku2023-12-16
国立国会図書館雑誌記事索引オンライン資料編zassaku-online2023-12-16
国立国会図書館デジタルコレクションndl-dl2023-12-16
国立国会図書館デジタルコレクション(電子書籍・電子雑誌)ndl-dl-online2023-12-16

リクエストに対する1度の返戻は200件が上限です。resumptionTokenを指定することで200件以降の取得が可能になります。
fromuntilを使用して特定の期間の書誌メタデータを取得することができますが、1年を超える期間を指定することはできません(untilを指定しない場合には、最大の期間がuntilに指定されたものとみなされます)。
全件のデータ量が多いため、できるだけ期間等で対象を絞ってリクエストしていただくことを推奨いたします。

5. OAI-PMHの全件ファイル提供について

NDLサーチのOAI-PMHでメタデータの提供を可としているデータプロバイダについては、以下のURLから、OAI-PMHのListRecordsリクエストに対するレスポンス仕様に準じた全件ファイルを提供しております。

https://ndlsearch.ndl.go.jp/files/oaipmhAllData/allData_dcndlXX.gz

  • XX」の部分を、01~32までの数字に置き換えて全件データをダウンロードください。
  • 上記URLでダウンロードできるgzipファイルは、1ファイル当たり、ファイルサイズ約1.5GB(展開後は約11GB)、件数は約240万件です。
  • 全件ファイルの更新頻度は月1回です。データ断面日は第一土曜日です。
    現在提供している全件ファイルのデータ断面日は12/27です。定期更新は3月から開始する予定です。(2024年2月9日更新)
  • 全件ファイルの利用に際しては、APIのご利用についてをご確認の上、条件を守ってご利用ください。
  • 各メタデータが属するデータプロバイダは、メタデータのsetSpecタグに出力されていますので、当該のデータプロバイダの二次利用条件に従ってご利用ください。

6. 関連ページ