Zenn
chot Inc. tech blogPublicationへの投稿
📚️

国立国会図書館サーチのAPIをつかって得た、検索APIと書影APIの知見

arrow2nd
2024/10/29に公開1件
TypeScript
API
tech

国立国会図書館サーチのAPIとは？

国立国会図書館と全国の図書館の蔵書情報にアクセスできるAPIです。
主に3つのAPIが提供されています。

  • 検索用API
  • ハーベスト用API
  • 書影API

今回は検索用APIと書影APIを使ってみたので、その知見を共有します。

利用申請について

と、その前に簡単に利用申請について触れておきます。

非営利利用の場合は申請不要ですが、営利利用の場合は利用申請が必要な場合があります。
営利利用の判断基準については以下の通りです。

データを利用することにより、なんらかの収益を得る場合（例：サイトの運営による広告収入等）は、営利目的にあたるため、利用申請が必要です（希望されている利用方法が営利目的に該当するか判断に迷う場合は、NDLサーチAPI利用申請フォームからご相談ください）。

https://ndlsearch.ndl.go.jp/help/api#sec2

特に検索用APIでは検索対象のデータプロパイダ（データソース）を指定できるため、利用するデータプロバイダ毎に営利・非営利利用の可否を確認する必要があります。

詳しくは以下のページにある各データプロパイダの メタデータ利用条件 を参照してください。

https://ndlsearch.ndl.go.jp/help/api/provider

また、継続して利用する場合は非営利利用であっても利用申請することが推奨されています。
メンテナンスやデータの更新時などに連絡してくださるので、申請しておいて損はないかなと思います。

検索APIの知見

検索APIでは3つのプロトコルが提供されています。

プロトコル 出力形式 アクセスURL
SRU XML https://ndlsearch.ndl.go.jp/api/sru
OpenSearch XML https://ndlsearch.ndl.go.jp/api/opensearch
OpenURL HTML https://ndlsearch.ndl.go.jp/api/openurl

https://ndlsearch.ndl.go.jp/help/api/specifications

今回はOpenSearch形式の検索APIをメインで利用しました。

501件目以降のデータが取得できない

OpenSearch形式の検索APIで「Python」を含む書籍を500件取得してみます。

GET https://ndlsearch.ndl.go.jp/api/opensearch?title=python&cnt=500
レスポンス
<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:dcndl="http://ndl.go.jp/dcndl/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" version="2.0">
  <channel>
    <title>python - 国立国会図書館サーチ OpenSearch</title>
    <link>https://ndlsearch.ndl.go.jp/api/opensearch?title=python&amp;cnt=500</link>
    <description>Search results for title=python cnt=500</description>
    <language>ja</language>
    <openSearch:totalResults>6418</openSearch:totalResults>
    <openSearch:startIndex>1</openSearch:startIndex>
    <openSearch:itemsPerPage>500</openSearch:itemsPerPage>
    <item>
      <!-- 省略 -->
    </item>
  </channel>
</rss>

レスポンスの openSearch:totalResults を見ると、全部で6418件の検索結果があることがわかります。

リファレンスによると、idx パラメータで取得レコードの開始位置を指定できるようなので、idx=501&cnt=500とすれば501件目以降のデータを取得できそうです。

試してみます。

GET https://ndlsearch.ndl.go.jp/api/opensearch?title=python&idx=501&cnt=500
レスポンス
<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:dcndl="http://ndl.go.jp/dcndl/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" version="2.0">
  <channel>
    <title>python - 国立国会図書館サーチ OpenSearch</title>
    <link>https://ndlsearch.ndl.go.jp/api/opensearch?title=python&idx=501&cnt=500</link>
    <description>Search results for title=python idx=501 cnt=500</description>
    <language>ja</language>
    <openSearch:totalResults>0</openSearch:totalResults>
    <openSearch:startIndex>1</openSearch:startIndex>
    <openSearch:itemsPerPage>500</openSearch:itemsPerPage>
  </channel>
</rss>

空っぽのレスポンスが返ってきました…。

こちらは負荷回避のための仕様とのことで、リファレンスに記載がありました。
SRU形式のAPIにも同様の制約があり、回避策はなさそうです。

（4）データの返戻件数
cnt パラメータで指定した件数までが返却される。デフォルトの返戻件数は 200 件で、一度に取得できる最大件数は 500 件である。ただし、検索負荷回避のための制約により、idx パラメータと cnt パラメータと使って 501件目以降を指定した場合でも該当のデータを取得することはできない。
外部提供インターフェース仕様書(第1.0版) 12ページより引用

OpenURL形式のAPIだと最大で10,000件まで取得できるものの、出力形式がHTMLなので正直扱いづらいかなという印象です。

（6）データの返戻件数
10,000 件までという制限がある。
外部提供インターフェース仕様書(第1.0版) 15ページより引用

新刊を最速で取得したい

国立国会図書館新着書誌情報（iss-ndl-opac-inprocess） というデータプロパイダがあり、これを使うと作成中の書誌データを取得できます。

作成中の全国書誌データ（新着書誌データ）※。当館納入後約4日で取得可能。未完成の書誌であるため、後に修正される場合がある。

国立国会図書館法 によると、出版から 30日以内 に納入しなければならないと定められているので、実際に取得可能になるまでは少し時間がかかりそうです。

もっと早く新刊のデータが欲しい…！そんな場合は 出版情報登録センター（jpro） が提供しているデータプロバイダを利用することで取得できます。（営利利用は要申請）

この記事を書いている 2024/10/28 に取得したデータですが、2024/10/25 に出版された書籍 ぼっち・ざ・ろっく！外伝　廣井きくりの深酒日記　３巻 が含まれていることが確認できました。

GET https://ndlsearch.ndl.go.jp/api/opensearch?title=廣井きくりの深酒日記&dpid=jpro
レスポンス
<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/" xmlns:dcndl="http://ndl.go.jp/dcndl/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" version="2.0">
  <channel>
    <title>廣井きくりの深酒日記 jpro - 国立国会図書館サーチ OpenSearch</title>
    <link>https://ndlsearch.ndl.go.jp/api/opensearch?title=%E5%BB%A3%E4%BA%95%E3%81%8D%E3%81%8F%E3%82%8A%E3%81%AE%E6%B7%B1%E9%85%92%E6%97%A5%E8%A8%98&amp;dpid=jpro</link>
    <description>Search results for title=廣井きくりの深酒日記 dpid=jpro</description>
    <language>ja</language>
    <openSearch:totalResults>3</openSearch:totalResults>
    <openSearch:startIndex>1</openSearch:startIndex>
    <openSearch:itemsPerPage>200</openSearch:itemsPerPage>
    <item>
      <title>ぼっち・ざ・ろっく!外伝廣井きくりの深酒日記</title>
      <link>https://ndlsearch.ndl.go.jp/books/R100000002-I033286846</link>
      <!-- 省略 -->
    </item>
    <item>
      <title>ぼっち・ざ・ろっく!外伝廣井きくりの深酒日記</title>
      <link>https://ndlsearch.ndl.go.jp/books/R100000002-I033396785</link>
      <!-- 省略 -->
    </item>
    <item>
      <title>ぼっち・ざ・ろっく！外伝　廣井きくりの深酒日記　３巻</title>
      <link>https://ndlsearch.ndl.go.jp/books/R100000137-I83220449e00000000000</link>
      <description><![CDATA[<p><p><ul><li>タイトル：ぼっち・ざ・ろっく！外伝　廣井きくりの深酒日記　３巻</li><li>タイトル（読み）：ボッチザロックガイデンヒロイキクリノフカザケニッキ03カン</li><li>責任表示：はまじあき 著・文・その他,くみちょう 著・文・その他</li><li>シリーズ名：ＦＵＺコミックス</li><li>シリーズ名（読み）：ファズコミックス</li></ul>]]></description>
      <author>はまじあき,くみちょう,はまじあき 著・文・その他,くみちょう 著・文・その他</author>
      <category>図書</category>
      <category>電子書籍・電子雑誌</category>
      <category>デジタル</category>
      <guid isPermaLink="true">https://ndlsearch.ndl.go.jp/books/R100000137-I83220449e00000000000</guid>
      <pubDate>Fri, 25 Oct 2024 21:21:36 +0900</pubDate>
      <dc:title>ぼっち・ざ・ろっく！外伝　廣井きくりの深酒日記　３巻</dc:title>
      <dcndl:titleTranscription>ボッチザロックガイデンヒロイキクリノフカザケニッキ03カン</dcndl:titleTranscription>
      <dc:creator>はまじあき</dc:creator>
      <dc:creator>くみちょう</dc:creator>
      <dcndl:creatorTranscription>ハマジアキ</dcndl:creatorTranscription>
      <dcndl:creatorTranscription>クミチョウ</dcndl:creatorTranscription>
      <dcndl:seriesTitle>ＦＵＺコミックス</dcndl:seriesTitle>
      <dcndl:seriesTitleTranscription>ファズコミックス</dcndl:seriesTitleTranscription>
      <dcndl:publicationPlace>JP</dcndl:publicationPlace>
      <rdfs:seeAlso rdf:resource="https://www.books.or.jp/book-details/83220449e00000000000"/>
      <rdfs:seeAlso rdf:resource="https://www.books.or.jp/book-details/9784832204492"/>
      <dc:description/>
    </item>
  </channel>
</rss>

ただ、国立国会図書館由来のデータと比べてタイトルに巻数が含まれていたり、書誌IDがないなど、併用する際にはなんらかの方法で整合性を取る必要があるかなと思いました。

検索APIで得た書籍の書影を取得したい

書影APIの使い方は以下の通りです。

https://ndlsearch.ndl.go.jp/thumbnail/[isbn又はJP-eコード].jpg

https://ndlsearch.ndl.go.jp/help/api/thumbnail

ここで、書影を取得したい書籍のデータを見てみます。（OpenSearch形式）

<item>
  <title>ぼっち・ざ・ろっく!外伝廣井きくりの深酒日記</title>
  <link>https://ndlsearch.ndl.go.jp/books/R100000002-I033286846</link>
  <description>
    <![CDATA[ <p>1,芳文社,2024,978-4-8322-0365-5<p><ul><li>タイトル：ぼっち・ざ・ろっく!外伝廣井きくりの深酒日記</li><li>タイトル（読み）：ボッチ ・ ザ ・ ロック ! ガイデン ヒロイ キクリ ノ フカザケ ニッキ</li><li>責任表示：くみちょう 漫画</li><li>シリーズ名：FUZ comics</li><li>NDC(10)：726.1</li></ul> ]]>
  </description>
  <author>くみちょう,くみちょう 漫画</author>
  <category>図書</category>
  <category>紙</category>
  <guid isPermaLink="true">https://ndlsearch.ndl.go.jp/books/R100000002-I033286846</guid>
  <pubDate>Fri, 16 Feb 2024 19:16:19 +0900</pubDate>
  <dc:title>ぼっち・ざ・ろっく!外伝廣井きくりの深酒日記</dc:title>
  <dcndl:titleTranscription>ボッチ ・ ザ ・ ロック ! ガイデン ヒロイ キクリ ノ フカザケ ニッキ</dcndl:titleTranscription>
  <dc:creator>くみちょう</dc:creator>
  <dcndl:creatorTranscription>クミチョウ</dcndl:creatorTranscription>
  <dcndl:volume>1</dcndl:volume>
  <dcndl:seriesTitle>FUZ comics</dcndl:seriesTitle>
  <dc:publisher>芳文社</dc:publisher>
  <dcndl:publicationPlace>JP</dcndl:publicationPlace>
  <dc:date xsi:type="dcterms:W3CDTF">2024</dc:date>
  <dcterms:issued>2024.2</dcterms:issued>
  <dcndl:price>720円</dcndl:price>
  <dc:extent>174 p</dc:extent>
  <dc:identifier xsi:type="dcndl:ISBN">978-4-8322-0365-5</dc:identifier>
  <dc:identifier xsi:type="dcndl:NDLBibID">033286846</dc:identifier>
  <dc:identifier xsi:type="dcndl:JPNO">23942939</dc:identifier>
  <dcndl:genre>漫画</dcndl:genre>
  <dcndl:genreTranscription>マンガ</dcndl:genreTranscription>
  <dc:subject xsi:type="dcndl:NDLC">Y84</dc:subject>
  <dc:subject xsi:type="dcndl:NDC10">726.1</dc:subject>
  <dc:description>出版</dc:description>
  <rdfs:seeAlso rdf:resource="https://ndlsearch.ndl.go.jp/books/R100000002-I033286846"/>
  <rdfs:seeAlso rdf:resource="https://www.books.or.jp/book-details/83220365e00000000000"/>
  <rdfs:seeAlso rdf:resource="https://www.books.or.jp/book-details/9784832203655"/>
  <dc:description> 2024</dc:description>
</item>

書影APIを利用するにはISBNがあればいいので、<dc:identifier> にあるISBNを使えば良さそうですね。

これで書影を取得してみます。

GET https://ndlsearch.ndl.go.jp/thumbnail/9784832203655.jpg

が、取得できませんでした…。

取得できなかった画面

書影APIにはJP-eコードも指定可能とあったので、これだと取得できそうな気がします。

ISBNがあった <dc:identifier> の部分を見てみます。

<dc:identifier xsi:type="dcndl:ISBN">978-4-8322-0365-5</dc:identifier>
<dc:identifier xsi:type="dcndl:NDLBibID">033286846</dc:identifier>
<dc:identifier xsi:type="dcndl:JPNO">23942939</dc:identifier>

……JP-eコード……なくない？

JP-eコードどこ？？？問題

レスポンスの中を探し回った結果どうやら <rdfs:seeAlso> のURL内に含まれているようでした。

<rdfs:seeAlso rdf:resource="https://ndlsearch.ndl.go.jp/books/R100000002-I033286846"/>
<rdfs:seeAlso rdf:resource="https://www.books.or.jp/book-details/83220365e00000000000"/>
<rdfs:seeAlso rdf:resource="https://www.books.or.jp/book-details/9784832203655"/>

JP-eコードは数字と大文字小文字のアルファベットからなる20桁の文字列です。

電子出版コードについて (PDF) 4ページに記載

この例では、上から2つ目のURL末尾にある 83220365e00000000000 がJP-eコードになります。

XMLパーサのライブラリで <rdfs:seeAlso> を (string | undefined)[] に変換した後、以下のような関数を使って抽出しました。

TypeScript
/**
 * JP-eコードを取得
 * @param seeAlsoUrls URLの配列
 * @returns JP-eコード
 */
export function getJpeCode(seeAlsoUrls: (string | undefined)[]): string | undefined {
  const jpeUrlRegex = /^https:\/\/www\.books\.or\.jp\/book-details\/([a-zA-Z0-9]{20})$/;

  // JP-eコードを取り出す
  const jpeCode = seeAlsoUrls.find((url) => url && jpeUrlRegex.test(url));

  return jpeCode?.match(jpeUrlRegex).at(1);
}

これを使ってAPIを叩くと、無事書影が取得できました！

GET https://ndlsearch.ndl.go.jp/thumbnail/83220365e00000000000.jpg

取得できた書影
取得できた書影

まとめと注意点

私が調べた限りではJP-eコードを直接取得する方法は見つかりませんでした。

また、ISBNとJP-eコードの両方がある場合、どちらか一方で必ず取得できるという訳ではない ため、両方を使って書影を取得できるか試す必要がありました。

もっとシンプルな方法がありましたら、教えていただけると幸いです 🙏

さいごに

少しつまづく点もありましたが、データ数が非常に多く、しかも無料で利用できるので非常にありがたいなと感じました。

書影を取得する手段としても openBD API の提供が終了してしまった今、これが唯一の手段かなと思います。（営利利用は要申請）

書籍の情報がほしい！そんな時はぜひ国立国会図書館サーチのAPIを利用してみてください📚️

chot Inc. tech blog
chot Inc. tech blogPublication

ちょっと株式会社（chot-inc.com）のエンジニアブログです。 フロントエンドエンジニア募集中！ カジュアル面接申し込みはこちらから chot-inc.com/recruit/iuj62owig

Discussion

tektektektek

色々自分でも試してみましたが、プロバイダをjproに指定しても発売日２日前の本が取得できなかったりするので発売前の情報の取得は色々難しそうですね・・・
検索でヒットするものでも未完成の書誌の場合RSSの情報にはカテゴリやCコードの情報が載ってないですし、そうなると500件以内に収まるよう絞るのが難しい・・・。