ndlsearch_api_20220829_en.pdf

Type: Document | Status: ready
← All sources

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

NDL Search

Application Programming Interface (API) Specifications

(Ver. 1.24)

August 29, 2022

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

......................................................................................................................................................
.................................................................................................................................................
..................................................................................................................................................................
..............................................................................

....................................................................................................................................................

.......................................................................................................................................................

................................................................................................

.......................................................................................................................................................

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

  1. Introduction

This document describes interface specifications which are used in search and acquisition of metadata from "NDL Search" (hereinafter referred to as this system) by applications of institutions. This system provides following Application Programming Interfaces (API).

Table 1-1 List of supported interfaces and their overviews No. Interface type Overview Input format Output format 1 SRU Protocol for searching information by using REST that was developed based on Z39.50, a communication protocol for information search URL XML 2 SRW *This service ended March 2, 2020 Protocol for searching information using WebService, which was developed based on Z39.50, a communication protocol for information search XML XML 3 OpenSearch Communication protocol for cross search, which are proposed by A9.com URL XML (RSS) 4 OpenURL Protocol for sending metadata information to link server in URL format to specify link destination of contents URL HTML 5 Z39.50 *This service ended March 2, 2020 Communication protocol in client-server style for information search Z39.50 interface Z39.50 interface 6 OAI-PMH Communication protocol, defined by OAI (Open Archives Initiative), for giving requests and receiving results in order to mechanically collect metadata between servers URL XML

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

Table 2-1 Access URL No. Provision method URL 1 SRU https://iss.ndl.go.jp/api/sru 2 SRW *This service ended March 2, 2020 3 OpenSearch https://iss.ndl.go.jp/api/opensearch 4 OpenURL https://iss.ndl.go.jp/api/openurl 5 Z39.50 *This service ended March 2, 2020 6 OAI-PMH https://iss.ndl.go.jp/api/oaipmh

You can access OpenSearch Description Document, which are the setting files for OpenSearch, respectively, at the following URL:
http://iss.ndl.go.jp/api/opensearch_description

(2) List of data providers and their IDs In each provision method, the database for a search request (hereinafter referred to as "data provider") shall be specified with data provider ID. Data providers are added at any time. For the list of the latest data providers and their IDs, see Appendix 1: List of data providers and their corresponding Application Programming Interfaces (API) in this document.

(3) Data provider group In each provision method, you can specify group of data providers instead of directly specifying data provider IDs. Following table shows data provider groups:

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 3 / 27 Table 2-2 Data provider groups No. Data provider group ID Details of data provider groups 1 digitalcontents Body text, digital images, etc. (Primary information) 2 catalogue Listing, index, etc. 3 site Site information 4 reference Information convenient for search, reference information 5 science Information about natural sciences 6 humanities Information about humanities 7 library Information concerning libraries 8 child Information for children 9 ndl Information provided by NDL

For correspondence between data provider groups and data providers, see Appendix 1: List of data providers and their corresponding Application Programming Interfaces (API) in this document.

(4) Character code Character code shall be UTF-8 for any provision method.

(5) Difference between harvest type and cross search type by data provider Data providers to be searched in this service are mainly classified into following two types as search method implementations:

Harvest type: Metadata is collected (harvested) from data providers and a database as this service is created with collected data.

Cross search type: No database is created but a request is issued directly to data providers via a network at the time of search.

At an application programming interface (API), no result is acquired from data providers in cross search describes only harvest-type data providers, and no cross search-type data provider is described.

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 4 / 27 (6) Relationship with search function of this service Available search conditions vary depending on each interface, and these conditions differ from the search items in this service. Remember that at the Application Programming Interface (API), basically only part of the conditions available for this service is supported.

(7) Format and contents of data Format (schema) and contents of data to be returned are explained in the description on each interface in the next section onwards. The "dcndl" and "dcndl_simple" formats or data to be returned are the formats defined in this service based on the NDL Dubrin Core Metadata Description (DC-NDL). For details about dcndl and dcndl_simple, see the DC-NDL (RDF) Format Specifications and DC-NDL (Simple) Format Specifications, respectively.

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

(1) Overview This is an interface for external institutions to use this service for search and acquire search results by SRU (Search/Retrieve via URL).

Figure 3-1 Overview of interface provided by SRU

You can find the basic specifications of SRU at the following URL: http://www.loc.gov/standards/sru/ This service supports SRU version 1.1 and 1.2. ZEEREX is not supported.

(2) Support range This service supports "searchRetrieve" and "explain," which are major operations of SRU (Scan operation is not supported).

(3) Argument of searchRetrieve

Table 3-1 Arguments of searchRetrieve No. Argument name Value to specify 1 operation Required "searchRetrieve" 2 version Optional 1.1 or 1.2 (The default is 1.2.)

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

No. Argument name Value to specify 3 query Required Search condition (CQL) Details are described later. 4 startRecord Start position The default is 1. 5 maximumRecords Maximum number of acquired records The default is 200. 6 recordPacking "xml" or "string" The default is "string
7 recordSchema Schema of acquired data dc, dcndl, or dcndl_simple The default is dc. 8 recordXpath Not used 9 resultSetTTL Not used 10 sortKeys Sort key information
Valid for version1.1 only 11 schema Not used 12 path title, creator, created_date, or modified_date Without sortKeys specified, the default (in the order of title) is applied. (Available only when 1.1 is specified for the version with sortKeys specified) 13 ascending "0" (descending order), "1"(ascending order) (Available only when 1.1 is specified for the version with sortKeys specified) The default is "1
14 stylesheet Not used 15 extraRequestData Not used 16 inprocess With "true" specified, only "NDL newly acquired Bibliographic data 1 " is acquired. 17 onlyBib With "true" specified, only "Bibliographic data" is acquired. (Available only when dcndl is specified for recordSchema)

(4) CQL specifications CQL is the specification of search queries in SRW. This service is provided based on CQL 1.2. The basic specification of CQL can be found at URL shown in 3 SRU (1) Overview." The following shows the items available when issuing a query using CQL.

1 Quick delivery service of inprocess bibliography information on domestic publications and overseas publications collected by NDL https://www.ndl.go.jp/jp/data/data_service/jnb/index.html

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 7 / 27 Table 3-2 Search items of SRU No. Reference name Details 1 dpid Data provider ID 2 dpgroupid Data provider group ID 3 title Title 4 creator Creator 5 publisher Publisher 6 digitized_publisher Digitized publisher 7 ndc Classification (NDC, NDLC, LCC, DCC, UDC) 8 ndlc Classification (NDLC) 9 description Contents description 10 subject Subject 11 isbn ISBN (Search is available in either 10- or 13-digit format) 12 issn ISSN 13 jpno National Bibliography No. 14 from Start date of publication (YYYY-MM-DD) 15 until End date of publication (YYYY-MM-DD) 16 anywhere The search items are the same as that of Simple search of NDL Search. 17 itemno Item number of bibliography within NDL Search (repository number - item number - branch number) 18 mediatype Material type Corresponds to the material type of Advanced Search of NDL Search. "1": Book "2": Article/Paper "3": Newspaper "4": Children's literature "5": Reference information "6": Digital material "7": Others "8": Material for the persons with disabilities (Material for Material search for persons with disabilities) "9": Legislative information 19 sortBy (available only when "1.2" is specified for the version argument of searchRetrieve) Describe the reference name of the sort criterion.

To indicate the ascending or descending order, /sort.ascending or /sort.descending shall follow the item.

NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 8 / 27 If a To avoid this error, add "%20" to before and after "%3d" and execute search. Example: When you want to specify the search keyword "andy" for the title

, , prefix match (^), partial match, and exact match (exact) can be specified as matching condition. If no condition is specified, partial match is assumed. For other items, no matching condition can be specified.

  • or 13-digit isbn is entered, the condition is converted to both 10 and 13 digits to perform exact match search. If entered in other digits than 10 or 13, the exact match search shall be performed; no other search, such as the prefix search, shall be performed.
  • For the items other than "dpid" and "dpgroupid" for which exact match is assumed, see "Table 3-3

For description and subject, partial match is assumed.

The items, from and until, are specified in YYYY-MM-DD format, and exact match is assumed as matching condition for them. Note that YYYY or YYYY-MM format is also available, and in this case, YYYY-01-01 or YYYY-MM-01 for YYYY or YYYY-MM, respectively, is assumed to be specified as matching condition for exact match. In addition, a

Following table shows possible conditions for each item

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

Table 3-3 Possible conditions for each item of SRU No. Reference name Match condition (^, exact) Logical condition
(all, any, =) Multiple values 1 dpid No (exact match) =, any only Yes 2 dpgroupid No (exact match) = only No 3 title Yes Yes Yes 4 creator Yes Yes Yes 5 publisher Yes Yes Yes 6 digitized_publisher Yes Yes Yes 7 ndc No (prefix match) = only No 8 ndlc No (prefix match) = only No 9 description No (partial match) Yes Yes 10 subject No (partial match) Yes Yes 11 isbn No (exact match) = only No 12 issn No (exact match) = only No 13 jpno No (exact match) = only No 14 from No = only No 15 until No = only No 16 anywhere No (partial match) Yes Yes 17 itemno No (exact match) = only No 18 mediatype No (exact match) = only Yes

To specify multiple values for one item, you must use "" to enclose the specified values (example: title="ruby python"). If specified value is just one and thus no ambiguity occurs, "" can be omitted. (Example: title=architecture)

(5) Number of returned data records Records of up to specified number for maximumRecords are returned. The default is 200. Also, the maximum number of records that can be acquired at a time is 500.

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

(6) Return format

Table 3-4 Details of SearchRetrieve Response No. Item name Return value 1 Version "1.2" or "1.1" (Specified in the request) 2 numberOfRecords Number of search results 3 resultSetId Not used 4 resultSetIdleTime Not used 5 Records Search result list 6 nextRecordPosition Start position of next record With startRecord=1 and maximumRecords=200, if the number of search results is more than 200, 201 is returned, and if the number of search result is less than 200 (no next page exists), 0 is returned. 7 Diagnostics Error message list 8 extraResponseData Search result (facet) 9 echoedSearch retrieveRequest Not used 10 Record Start of 1 Book 11 recordSchema Schema 12 recordPacking "xml" or "string" 13 recordData Start of Bibliographic data 14 recordPosition Position of the Bibliographic data

The format of returned data is XML. The schema is specified at request, which shall be dc, dcndl, or dcndl_simple.

As extraResponseData, facet data of search results is returned. The facet items are as follows. (Note that a facet item whose search result is zero is not included in the returned data):

  • Data provider Number of search results for each data provider is returned. Search result is expressed as dpid="data provider ID" in dp element. For data provider ID, see Appendix 1: List of data providers and their corresponding Application Programming Interfaces (API) in this document.
Page 1 of 3