Information regarding NDL Search API changes

January 5th, 2024

We would like to inform you about the changes related to the API of NDL Search, which was renewed in January 2024.

0. General information

Please refer to the following page when using the API.
Help > How to use How to use NDL Search API
We are now preparing the English specifications of the API of NDL Search after January 2024. You can check the English specifications of the API of NDL Search before December 2023.
Help > NDL Search API Specifications (in Japanese) > 4. API specifications in English
Please refer to the following page for DC-NDL (RDF) format specifications.
Collaboration with NDL Search > DC-NDL (RDF) format specifications (Japanese page only)

1. Changes to API providing databases

The table below shows the changes to the API provided by databases with the NDL Search renewal in January 2024.
If you want to know the current API providing databases, please check “The list of API-providing databases”.
If you want to know the current Data providing databases, please check “The list of Data providing databases” (Japanese page only).

Repository Number	Data Provider ID	Data Providing Database	Change details
R100000002	iss-ndl-opac	National Diet Library Catalog	Added the metadata of journal or periodical volumes to the output metadata
R100000002	iss-ndl-opac-bib	National Diet Library Catalog (Not Including Volumes)	Newly created as the National Diet Library Catalog not including the metadata of journal or periodical volumes
R100000004 R100000039 （R100000040）	ndl-article-online	NDL Online Publications (Article)	Newly created as an article database constituted of the NDL Periodical Index (Online) and the articles of the NDL Digital Collections (Online Publications)
R100000039 （R100000040）	ndl-dl ndl-dl-online	NDL Digital Collections NDL Digital Collections (Online Publications)	Merged databases and abolished the repository number of R100000040 *You can specify the NDL Digital Collections or NDL Digital Collections (Online Publications) by the data provider ID, same as before
R000000006	refkyo	Collaborative Reference Database	End to providing API. Switched from API collaboration to cross-search collaboration. *You can retrieve the API of the Collaborative Reference Database from its API. “The manual of the Collaborative Reference Database” (in Japanese)
R000000020	warp	Web Archiving Project（WARP）	Switched from cross-search collaboration to API collaboration; start to provide API
R000000023	－	Asian Historical Records Database	End of collaboration
R000000024	cinii	CiNii Articles	End of collaboration (Start to collaborate as CiNii Research from January 2024)
R000000025	jairo	Institutional Repositories DataBase(IRDB)(Institutional Repository)	Changed data provider ID from “jairo” to “irdb”
R000000033	webcont	Electronic exhibitions of the NDL	End of collaboration
R100000049	tenroku	Union Catalog of Materials for Persons with Disabilities in Japan	Changed the name of the data providing database from the “National Union Catalog of Braille & Recorded Books in Japan” to the “Union Catalog of Materials for Persons with Disabilities in Japan” (No change to data provider ID)
R000000063	－	INTERNET magazine Back Number Archives	End of collaboration
R000000066	－	NII Digital Archive of Toyo Bunko Rare Books	End of collaboration
R000000067	hukuoka	Digital Library of Fukuoka Prefectural Library	End of collaboration（collaborate in ADEAC）
R000000068	tottori	Map Images of Tottori Prefectural Library	End of collaboration（collaborate as Tottori Digital Collections）
R000000184	research	Research Navi	End to providing API. Switched from API collaboration to cross-search collaboration.
R000000189	yamagatashi	Yamagata Prefectural Library Digital Library	Changed data provider ID from ”yamagatashi” to “yamagata”
R000000192	－	Collection Database of Nara National Museum	End of collaboration
R000000197	－	e-Museum - National Treasures & Important Cultural Properties of National Museums, Japan	End of collaboration
R100000027	－	The National Library of Korea Catalog	End of collaboration
R100000028	－	Full-text Database System for the Minutes of the Diet	End of collaboration
R100000029	－	Database System for the Minutes of the Imperial Diet	End of collaboration
R100000030	－	Index Database to Japanese Laws, Regulations and Bills	End of collaboration
R100000031	hourei-meiji	Index to Laws & Regulations in early Meiji Japan	End of collaboration
R100000034	－	Website of the House of Representatives	End of collaboration
R100000035	－	Website of the House of Councillors	End of collaboration
R100000036	－	Website of the Judge Impeachment Court	End of collaboration
R100000037	－	Website of the Judge Indictment Committee	End of collaboration
R100000067	kinkan	Japan Publication Registry Office	Merged into the newly created data providing database, the Japan Publication Registry Office (R100000137、jpro)
R100000076	－	JapanKnowledge	Switched from API collaboration to cross-search collaboration. Not providing API (No change).
R100000096	ciniib	CiNii Books	End of collaboration (start to collaborate as CiNii Research from January 2024)
R100000130	jpro-online and others	the Japan Publication Registry Office (ElectronicBook)	Merged into the newly created data providing database, the Japan Publication Registry Office (R100000137、jpro)
R100000136	ciniir	CiNii Research	Newly created
R100000137	jpro	Japan Publication Registry Office	Newly created Provide the whole metadata from the Japan Publication Registry Office Change to providing the paper book metadata for an unlimited period from providing the paper book metadata for 60 days
R100000141	irdb-pub	National Institute of Informatics Accessible Metadata Database for Persons with Print Disabilities	Newly created
－	－	NDL Image Bank	Start cross-search collaboration.
－	－	NDL Gallery	Start cross-search collaboration.
－	－	Japan Search	Start cross-search collaboration.

2. Changes to data group IDs and other IDs

The table below shows the changes to the data group IDs. You can specify the metadata not only by using the data provider IDs above, but also by using the data group IDs below.

Name of the data group	Data group ID	Explanation
Open Data	open	Created as a new data group for open data with CC0 or CC BY license
Title Bibliography	title	Created as a new data group for bibliographies which group volumes or books such as titles of serial publications and books in series
Book or Volume Bibliography	book	Created as a new data group for bibliographies, which will be the basic unit for using materials such as volumes, books, and maps of journals
Article Bibliography	article	Created as a new data group for bibliographies of articles and papers published in journals
NDC	－	Stopped specifying the metadata by NDC in OAI-PMH
mediatype	－	Stopped specifying the metadata by “mediatype” as value "1"~"9". Instead, started specifying the metadata by material type or material format described in (5-1)
Data Provider Group ID	digitalcontents, catalogue, site, reference, science, humanities, library, child, ndl	Stopped specifying the metadata by the provider group described on the left

3. Changes to the metadata providing format

The provision of metadata in DC-NDL (simple) has ended.
*The provision of metadata in DC-NDL (RDF) will continue in the future, but minor revisions have been made to the format specifications.
Collaboration with NDL Search > DC-NDL (RDF) format specifications (Japanese page only)

4. Changes to harvest APIs (OAI-PMH)

(4-0) Changes common to all databases

(A) Changes to the base URL

The base URL has been changed as follows:
Old URL: https://iss.ndl.go.jp/api/oaipmh?
New URL: https://ndlsearch.ndl.go.jp/api/oaipmh?
The old URL will be automatically redirected to the new URL of the NDL Search API. There is currently no end date planned for the redirect.

(B) Changes to the identifiers of OAI-PMH

Old identifier: oai:iss.ndl.go.jp:[Repository number]-[Item number]-00
New identifier: oai:ndlsearch.ndl.go.jp:[Repository number]-[Item number]

The identifiers of OAI-PMH have been changed as follows:

Format: The prefix of the old identifier “oai:iss.ndl.go.jp:” has been changed to “oai:ndlseaarch.ndl.go.jp:”, and the end of the old identifier “-00” has been removed.
Value: The number part starting with I has been changed in many databases.

(C) Comparison table of OAI-PMH identifiers between the old and new identifiers

You can download the comparison table of old and new identifiers from the following URL. Please specify repository number.

https://ndlsearch.ndl.go.jp/files/idlist/[Repository number].gz

(D) Distribution of the whole delete records of old identifier

You can download the delete records of each database provided by the old NDL Search below. Please make use of them to delete records which were provided by the old NDL Search.

https://ndlsearch.ndl.go.jp/files/deleterecords/[Repository number].gz

(E) The start date of the metadata of the new NDL Search

The start date of the metadata of the new NDL Search is “2023-12-16”. By specifying “from=2023-12-16”, all records with the new identifier can be retrieved from OAI-PMH.

(F) Distribution of the full metadata provided by OAI-PMH

If you want to retrieve the full metadata of the new identifier, you can download it from the following URL:
https://ndlsearch.ndl.go.jp/files/oaipmhAllData/allData_dcndlXX.gz

The files contain all the database metadata which can be obtained from OAI-PMH.
Please replace “XX” with the numbers from “01” to “32”.
The gzip file you can download above is about 1.5 GB and contains about 2.4 million records.
To use the file, you must refer to the “How to use NDL Search API”.
You can see the database in the setSpec tag. You must follow the terms and conditions of the database.

(4-1) On the National Diet Library Catalog (iss-ndl-opac and others, R100000002) and NDL Periodical Index (zassaku, R000000004)

(A) Changes to the identifiers of OAI-PMH

The identifiers of OAI-PMH have been changed as follows:

Format: The prefix of the old identifier “oai:iss.ndl.go.jp:” has been changed to “oai:ndlseaarch.ndl.go.jp:”, and the end of the old identifier “-00” has been removed.
Value: The number part starting with I does not change.

ex. The identifier of the metadata of the National Diet Library Catalog (iss-ndl-opac and others, R100000002)
Old identifier: <identifier>oai:iss.ndl.go.jp:R100000002-I000000511306-00</identifier>
New identifier: <identifier>oai:ndlsearch.ndl.go.jp:R100000002-I000000511306</identifier>

Also, you can download the comparison table of old and new identifiers. Please refer to (4-0).

(B) Distribution of the full delete records or the full metadata provided by OAI-PMH

You can retrieve the full delete records or the full metadata. Please refer to (4-0).

(4-2) On the NDL Digital Collections (ndl-dl, ndl-dl-online, R100000039) and the Digital Material for Persons with Print Disabilities (ndl-dl-daisy, R100000073)

(A) Changes to the identifiers of OAI-PMH

The identifiers of OAI-PMH have been changed in format and value.

ex. The identifier of the metadata of the NDL Digital Collections (ndl-dl, R100000039)
Old identifier: <identifier>oai:iss.ndl.go.jp:R100000039-I000690430-00</identifier>
New identifier：<identifier>oai:ndlsearch.ndl.go.jp:R100000039-I1302584</identifier>

(B) Comparison table of OAI-PMH identifiers between the old and new identifiers

You can download the comparison table of old and new identifiers of the NDL Digital Collections (ndl-dl, ndl-dl-online) and the Digital Material for Persons with Print Disabilities (ndl-dl-daisy) . Please refer to (4-0).

(C) Distribution of the full delete records or the full metadata provided by OAI-PMH

You can retrieve the whole delete records or the whole metadata. Please refer to (4-0).

(D) Changes to the value to specify a collection

The value of collection codes to specify a collection in OAI-PMH have been changed.

ex. Rare books and old materials
Old value: D02
Request example in old NDL Search:
https://iss.ndl.go.jp/api/oaipmh?verb=ListRecords&metadataPrefix=dcndl&set=ndl-dl:D02&from=2023-01-01&2023-01-31
New value: A00003 (reference)https://dl.ndl.go.jp/collections/A00003
Request example in new NDL Search:
https://ndlsearch.ndl.go.jp/api/oaipmh?verb=ListRecords&metadataPrefix=dcndl&set=A00003&from=2024-01-01&2024-01-31

(4-3) Other data providing databases

(A) Changes to the identifiers of OAI-PMH

The identifiers of OAI-PMH have been changed in format and value. You can download the comparison table of old and new identifiers. Please refer to (4-0).

(B) Distribution of the full delete records or the full metadata provided by OAI-PMH

You can retreive the full delete records or the full metadata. Please refer to (4-0).

5. Changes to search API (SRU, OpenSearch, OpenURL)

(5-0) Changes to the base URL

The base URL has been changed as follows: (SRU example)

Old URL: https://iss.ndl.go.jp/api/sru?
New URL: https://ndlsearch.ndl.go.jp/api/sru?

The old URL will be automatically redirected to the new URL of the NDL Search API. There is currently no end date planned for the redirect.

(5-1) Changes to the value for “mediatype” for material type and material format

The “mediatype” parameter for specifying material type and material format has been changed and expanded. The new “mediatype” values are listed below.
In addition, specifying the metadata by the old data provider group ID is no longer supported.

Material format

booklet
micro
media
digital

Material type

books
periodicals
articles
newspapers
oldmaterials
maps
electronic
video
audio
online
doctoral
reports
web
scores
manuscripts

Collection

children
repository
mina
mina-daisy
mina-audio
mina-braille
mina-text
mina-video
mina-booklet

6. Changes to thumbnail APIs

The URL has been changed as follows:

Old URL: https://iss.ndl.go.jp/thumbnail/ [isbn or JP-e code]
New URL: https://ndlsearch.ndl.go.jp/thumbnail/ [isbn or JP-e code] .jpg

*The extension ".jpg" has been added to the end of the URL.