ndlsearch_api_20220829_all_en.pdf

Type: Document | Status: ready
← All sources

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 21 / 27 7. Z39.50

  • This service ended March 2, 2020

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 22 / 27 8. OAI-PMH

(1) Overview This is an interface providing metadata that this service collects by OAI-PMH (Open Archives Initiative Protocol for Metadata Harvesting).

NDL search OAI-PMH-API

Harvest request (URL)

Institution

OAI-PMH

Metadata (XML)

Figure 8-1 Overview of interface provided by OAI-PMH

OAI-PMH is a protocol being developed by OAI (Open Archives Initiative) for metadata exchange. You can find the basic specifications at the following URL: http://www.openarchives.org/OAI/openarchivesprotpcol.html In addition, the National Institute of Informatics published Japanese translation of this at http://www.nii.ac.jp/irp/archive/translation/oai-pmh2.0/

In OAI-PMH, you can access repositories by using the following six operations (called verb). "Item" is one data (In this service, a unit of information displayed as a search result).

  • GetRecord (acquires one record of metadata of a particular item)
  • Identify (acquires an information about a repository)
  • ListIdentifiers (acquires identifiers of all items)
  • ListMetadataFormats (acquires supported format of metadata)
  • ListRecords (acquires metadata of all items)
  • ListSets (acquires supported sets (group: narrowing condition))

Following describes the specifications of repository (Application Programming Interface (API) of OAI- PMH) of this service.

(2) Repository basic information As repository basic information, describe return details in response to an Identify request.

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 23 / 27

Table 8-1 Repository basic information Tag name Details Return value repositoryName Repository name NDL Digital Archive Portal baseURL Base URL of the repository http://iss.ndl.go.jp/api/oaipmh protocolVersion Version of OAI-PMH supported by the repository Version 2.0 adminEmail Email of the repository administrator

earliestDatestamp Lower limit of all the date stamps for recording change, correction, and deletion within the repository. There is no item with date stamp earlier than this date. Initial building date or full re-building date of repository deletedRecord Processing method for deleted repository records transient: Retains the information on the deletion with restriction (Retain the records with date stamp of a certain date onwards) granularity Accuracy of date supported by the repository YYYY-MM-DD repositoryIdentifier Name to uniquely identify the repository oai:iss.ndl.go.jp:ID

(3) Support requests and arguments The following requests and the arguments are supported.

Table 8-2 Requests and arguments

◎: Required, Yes: Optional (The period of from and until are limited, which is described later.)

No. Request Arguments identifier metadata Prefix from until set resumption Token 1 GetRecord ◎ ◎

2 Identify

3 ListIdentifiers

◎ ◎ Yes Yes Yes 4 ListMetadataFormats Yes

5 ListRecords

◎ ◎ Yes Yes Yes 6 ListSets

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 24 / 27

(4) Set "Set" is the definition for grouping items for selective harvest. "Set" is also used to acquire metadata related only to item group with a particular attribute. "Sets" include data provider (ID), data provider group (ID), NDC (please note you can specify it up t o the three digit class number), Collection Code and Access Rights. Collection Code and Access Rights can be used when "NDL Digital Collections (ndl-dl)" or "NDL Digital Collections (Online publication) (ndl-dl-online)" is specified.

  • Overview of the materials that can specify in Collection Code, are presented in the following page. http://dl.ndl.go.jp/en/intro.html#idx4
  • Details of Access Rights are presented in the following page. http://dl.ndl.go.jp/en/intro.html#idx2-1

For NDC, Collection Code and Access Rights, prefix match shall be applied. For example, if a digit "7" is specified, bibliographic data with the classification code "7xx" will be returned. If three digit "D07" is specified for the Collection Code, metadata with the Collection Code "D07X" (lower level of Collection Code "D07") will be returned (see appendix4 for exceptions). For example, if Aozora Bunko is specified for the data provider, specify as "set=aozora".
To specify multiple items at the same time, for example, if you want to specify data provider and NDL classification simultaneously, you must separate each item with a colon (:). You can specify in any order, for the data whose NDC classification is "735", specify as "set=735". For the data of Aozora Bunko with NDC classification "735", specify as "set=aozora:735" or "set=735:aozora." For the data with Collection Code
"D07” of NDL Digital Collection ( Online publications ), you should specify "set=ndl-dl-online:D07" or "set=D07:ndl-dl-online". For the data with NDC “735” of NDL Digital Collection (Online publications), with Collection Code "D07" and Access Rights "Available only at the NDL, you should specify "set=ndl-dl- online:735:D07:ARkannai", or "set=ARkannai:735:D07:ndl-dl-online".
You cannot specify multiple conditions in the same field. For example, when you specify NDL classification simultaneously (request example "set=913:914"), it will return an error. Even if Collection Code or Access Right in a record is changed, delete record will not be returned retrospectively. Therefore, if you harvest data with set “Collection Code” or “Access Rights”, you are supposed to update all of data on a regular schedule.

  • If you want to know about the latest Collection Code and Access Rights, see Appendix 4: List of Collection Code and Access Rights.
  • Since 2010, NDL has provided the newly acquired NDL bibliographic data. The data provider of the newly acquired NDL bibliographic data is NDL Online. If you want to acquire the metadata of the newly acquired bibliographic data, make a request with "set=iss -ndl-opac-inprocess" specified. Note that although the metadata of NDL Online can be acquired by a request with "set=iss -ndl-opac" specified, the result from this request does not include the data of the newly acquired NDL bibliographic data.
  • Since 2013, NDL Search provides the Japanese national bibliography . The data provider NDL Online includes the Japanese national bibliography. If you want to scope the Japanese national bibliography, make a NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 25 / 27 request with "set=iss -ndl-opac-national". Note that the Japanese n ational bibliography is equivalent to data with "set=iss-ndl-opac" and JPNO.

(5) Number of returned data records For ListIdentifiers, ListRecords, and ListSets, the number of returned data records at a time is 200. To acquire 201st and later records, make a request while specifying the resumptionToken notified when the first 200 records were acquired.

(6) Return format The data return format is XML. For the schema (metadataPrefix), you can select either oai_dc , dcndl or dcndl_simple.
To acquire the bibliographic data only, make a request with onlyBib=true specified. (Available only when dcndl is specified for metadataPrefix)

For an example of returned data, see Appendix 3 (Examples of returned data for each interface) in this document.

(7) Identifier For OAI-PMH, a unique item identifier on the repository side can be received on the service provider side. By using this, you can update the data on the service provider at the time of differential harvest (the parameter described as the identifier in (3) Support requests and argument). This service uses this identifier as the metadata ID. (The ID, with the configuration shown below, uniquely given to all the metadata of this service.) oai:iss.ndl.go.jp :[repository number]-[item number]-[branch number]

(8) from, until If a date (YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ) is specified for "from,” the bibliographic data updated after the specified date is returned. If a date (YYYY -MM-DD or YYYY-MM-DDThh:mm:ssZ) is specified for "until" the bibliographic data updated earlier than the specified date is returned. The restriction on the period of "from" and "until,” see "(10) Access restriction of OAI-PMH.”

(9)Access restriction of OAI-PMH OAI-PMH applies following restriction to accesses in order to prevent the load on this service from being raised by accesses for large data acquisition. For ListRecords and Listidentifier, "from" is required. The following restriction is applied to the range (period) that can be specified by "from" or "until":

  • Maximum period is one year. NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 26 / 27
  • In case of non-specified, maximum period (one year) is automatically assigned.

(11) Request sample Example 1: Identify request http://iss.ndl.go.jp/api/oaipmh?verb=Identify

Example 2: ListMetadataFormats request http://iss.ndl.go.jp/api/oaipmh?verb=ListMetadataFormats

Example 3: ListIdentifiers request http://iss.ndl.go.jp/api/oaipmh?verb=ListIdentifiers&metadataPrefix=oai_dc&from=2010-07-01

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 27 / 27

Example 4: ListRecords request http://iss.ndl.go.jp/api/oaipmh?verb=ListRecords&metadataPrefix=oai_dc&set=aozora&from=2010-07- 01

http://iss.ndl.go.jp/api/oaipmh?verb=ListRecords&metadataPrefix=dcndl_simple&f rom=2011-02- 01&set=iss-ndl-opac-inprocess

Example 5: GetRecord request http://iss.ndl.go.jp/api/oaipmh?verb=GetRecord&metadataPrefix=oai_dc&identifier=oai:iss.ndl.go.jp:R00 0000014-I000044174-00

Example 6: ListSets request http://iss.ndl.go.jp/api/oaipmh?verb=ListSets

Appendix 1,
Application Programming Interface (API) Specifications
1 / 13

List of data providers and their corresponding Application Programming Interface (API)

The following table lists the latest data providers and their corresponding Application Programming Interface (API) and data provider IDs (see (2) “List of data providers and IDs" in 2 “Common Items" in this document).

Table 1 List of data providers and their corresponding Application Programming Interface (API) Data provider name Data provider ID Repository No. API for search API for harvest NDL Periodical Index zassaku R000000004 Yes Yes NDL Periodical Index (Online) zassaku-online R000000004 No Yes Shinsho Map shinsho R000000005 Yes No Collaborative Reference Database refkyo R000000006 Yes No Current Awareness awareness R000000007 Yes No Aozora Bunko aozora R000000014 Yes Yes J-STAGE jstage R000000016 Yes Yes CiNii Articles cinii R000000024 Yes No Institutional Repositories DataBase(IRDB)(Institutional Repository) jairo R000000025 Yes No The Japan P.E.N. Club Digital Library penclub R000000030 Yes No Image database of Nara Women's University narajo R000000032 Yes Yes Electronic exhibitions of the NDL webcont R000000033 Yes Yes Digital Library of Ibaraki Prefectural Library ibaraki R000000034 Yes Yes NARA regional historical materials catalog nara-tiiki R000000038 Yes Yes Nara Prefectural Library and Information Center (Furusato digitized books＋Drawing Exhibition Gallery) nara-book R000000039 Yes Yes Union Catalog of the Collections of the National Art Museums, Japan (Image) artm-1 R000000040 No No Union Catalog of the Collections of the National Art Museums, Japan (No image) artm-2 R000000041 No No Rare Books Collection / University of Tsukuba Library tsukuba R000000046 Yes Yes

Appendix 1,
Application Programming Interface (API) Specifications
2 / 13 Data provider name Data provider ID Repository No. API for search API for harvest Online catalog of reading room of material related to Okinawa war (digitalized) okinawa-1 R000000047 Yes Yes Online catalog of reading room of material related to Okinawa war (not digitalized) okinawa-2 R000000048 Yes Yes Rare material gallery of ISHIKAWA prefectural library ishikawa R000000049 Yes Yes KOTENSEKI SOGO DATABASE(Japanese & Chinese Classics) (Waseda University Library) waseda R000000050 Yes Yes Digital archive of books material of Japan Fisheries Research and Education Agency suisan R000000051 Yes Yes Eichi no Mori WEB (Miyagi Prefectural Library) miyagi R000000054 Yes Yes Special Collections of Hiroshima Central City Library hiroshima-c R000000055 Yes Yes Digital gallery of Japanese and Chinese Materials of Mie Prefectural Library mie-p R000000056 Yes Yes Digital library of Sapporo Municipal Central Library sapporo R000000058 Yes Yes Northern Materials Digital library of Hokkaido Prefectural Library hokkaido R000000059 Yes Yes Digital library of Tokushima Prefectural Library tokushima R000000061 Yes Yes OSAKA PREFECTURAL LIBRARY OSAKA e- COLLECTION osaka-n R000000062 Yes Yes Local Material Images of Okayama Municipal Central Library okayamashi R000000065 Yes Yes Digital Library of Fukuoka Prefectural Library hukuoka R000000067 Yes Yes Map Images of Tottori Prefectural Library tottori R000000068 Yes Yes RESEARCH NAVI research R000000184 Yes No Digital library of Saitama Prefectural Library saitama R000000185 Yes Yes Collection of pictorial postcard of Nagoya (Nagoya City Tsuruma Central Library) nagoyashi R000000186 Yes Yes Chiba Digital Archive chiba R000000187 Yes Yes

Page 3 of 9