NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 11 / 27 Example: <lst name="REPOSITORY_No"> <int name="R100000001">159</int> <int name="R100000004">7</int>
</lst>- Numeric value specified by name= is repository number of data provider. For details about repository number, see Appendix 1: List of data providers and their corresponding Application Programming Interfaces (API) in this document.
NDC In NDC classification of documents, the number of the first digit of NDC code is interpreted as genre, and number of search results for each field is returned.
Example: <lst name="NDC"> <int name="7">1</int> <int name="9">2</int>
</lst>- Year of publication Number of search results for each publication year is returned. Search result of facet does not include record if its year of publication is unknown.
Example: <lst name="ISSUED_DATE"> <int name="1600">1</int> <int name="1650">3</int>
</lst>NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 12 / 27 For details about examples of returned data, see Appendix 3 "Examples of returned data for each interface" in this document.
(7) Error message If an error occurs, such as a syntax error or a server error, the server returns an error message. Return format and error message details shall comply with the SRU standard specifications "Diagnostics List" (at
(8) Request example (CQL example) Example 1: If the material was published after January 1, 2008 and the title includes " the request shall be title=" "AND from="2008
- For the actual request URL to this service, this request is encoded to
(title%3d%22%e6%a1%9c%22%20AND%20from%3d%222008%22),
and this is added to the query, resulting in the following:
http://iss.ndl.go.jp/api/sru?operation=searchRetrieve&query=title%3d%22%e6%a1%9c%22%20AND%20fro m%3d%222008%22
Example 2: The author is " " (exact match).
CQL is creator exact "
- For the actual request URL to this service, this request is encoded to
(creator%20exact%20%22%e5%a4%8f%e7%9b%ae%e6%bc%b1%e7%9f%b3%22), and this is added to the query, resulting in the following:
http://iss.ndl.go.jp/api/sru?operation=searchRetrieve&query=creator%20exact%20%22%e5%a4%8f%e7%9b %ae%e6%bc%b1%e7%9f%b3%22
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 13 / 27 4. SRU/SOAP(SRW)
- This service ended March 2, 2020
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 14 / 27 5. OpenSearch (1) Overview This is an interface for external institutions to use this service for search and acquire the search result by OpenSearch.
Figure 5-1 Overview of interface provided by OpenSearch
OpenSearch issues a search request in a URL and acquires the search result in RSS 2.0 format. You can find the basic specifications at the following URL. Supported version for this service is 1.0. http://a9.com/-/spec/opensearchrss/1.0/
(2) Request format Request format is following URL.
http://iss.ndl.go.jp/api/opensearch?dpid=[dpid]&title=[title]&...
(3) Argument ([query]) format Following table shows possible items to be specified in a request.
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 15 / 27
Table 5-1 Search items of OpenSearch No. Reference name Details Match condition Multipl e values 1 dpid Data provider ID Exact match Yes 2 dpgroupid Data provider group ID Exact match No 3 any All items are searched. Partial match Yes 4 title Title Partial match Yes 5 creator Creator Partial match Yes 6 publisher Publisher Partial match Yes 7 digitized_publ isher Digitized publisher Partial match Yes 8 ndc Classification (NDC) Prefix match No 9 from Start date of publication (YYYY-MM-DD)
No 10 until End date of publication (YYYY-MM-DD) (YYYY-MM- DD)
No 11 cnt Upper limit of output record (The default is 200.)
No 12 idx Start position of record acquisition (The default is 1.)
No 13 isbn ISBN If entered in 10 or 13 digits, the item is converted to both 10 and 13 digits for exact match search. If entered in other digits, prefix match search is performed. Exact match or Prefix match No 14 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 Exact match Yes Note: The logical conditions between items are all AND. Note: Space-separated multiple keywords can be specified in one search item. In this case, OR search is used for "dpid" and AND search for other items. No search is available with only "dpid" or "dpgroupid" specified. Note: If an argument (parameter) is wrong, no search result is acquired.
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 16 / 27
(4) Number of returned data records Records of up to the number specified for cnt parameter are returned. The default is 200. The maximum number of records that can be acquired at a time is 500.
(5) Return format The data return format is an extended version of RSS 2.0 for this service. For details about examples of returned data, see the appendix 3 ("Examples of returned data for each interface") in this document.
(6) Request example Example 1: Title includes " ".
http://iss.ndl.go.jp/api/opensearch?title=%e3%83%9e%e3%83%aa%e3%83%bc%e3%82%a2%e3%83%b3 %e3%83%88%e3%83%af%e3%83%8d%e3%83%83%e3%83%88
Example 2: Within Aozora Bunko, author includes " ".
http://iss.ndl.go.jp/api/opensearch?dpid=aozora&creator=%e5%a4%8f%e7%9b%ae
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 17 / 27 6. OpenURL
(1) Overview This is an interface for external institutions to use this service for search and acquire search results by OpenURL.
Figure 6-1 Overview of interface provided by OpenURL
OpenURL returns a result on the screen (HTML) for a request issued in a URL. You can find the basic specifications at the following URL: http://www.niso.org/kst/reports/standards?step=2&gid=None&project_key=d5320409c5160be4697dc0466 13f71b9a773cd9e
(2) Request format A request is an URL in following format
Note that a search result HTML returned in this URL format is the same as the search result screen on the Web of this service; therefore, the result can be displayed only by a browser supporting this service.
(3) genre specification and where to search genre (or rtf.genre) can be specified. This service searches a different place depending on following three patterns. Note that the same result is acquired when specifying "genre=" or
- For genre=article
- For other than genre=article (Other than article among possible items for genre for OpenURL)
- When genre is not specified For details about correspondence between genre and data providers, see Appendix 2 "Specification of OpenURL-genre and the corresponding data provider" in this document.
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 18 / 27
If there is an inconsistency between specified items for genre (or rft.genre) and atitle or btitle, an error message is displayed and the search is stopped. In addition, if ndl_dpid is specified for search, data provider specified for genre becomes invalid.
(4) atitle or btitle specification and where to search If ndl_dpid is specified for search, specified atitle or btitle for search location becomes invalid, and the search is performed in the same manner when the title=search character string&ndl_dpid=search location is specified.
(5) Possible search items This service supports a part of parameters (keys) of OpenURL1.0. Following table shows possible parameters:
Table 6-1 Search items concerning OpenURL No. Item genre=art icle Other than genre=article genre is not specified Match condition Search method Multi ple values 1 aulast (or rft.aulast) Yes Yes Yes Partial match Same as au(rft.au) *1 No 2 aufirst (or rft.aufirst) Yes Yes Yes 3 au (or rft.au) Yes Yes Yes Partial match Authors are searched. Yes 4 title, atitle (or rft.title, rft.atitle) Yes
Yes Partial match Titles (of articles) are searched. Yes 5 btitle (or rft.btitle)
Yes Yes Partial match Titles are searched. Yes
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 19 / 27 No. Item genre=art icle Other than genre=article genre is not specified Match conditi on Search method Multi ple values 6 jtitle (or rft.jtitle) Yes
Yes Partial match Journal titles are searched. Yes 7 pub (or rft.pub)
Yes Yes Partial match Publishers are searched. Yes 8 issn (or rft.issn) Yes Yes Yes Prefix match ISSNs are searched. No 9 isbn (or rft.isbn)
Yes Yes Exact match or Prefix match ISBNs are searched. (If 10- 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, the prefix match search is performed.) No 10 Any Yes Yes Yes Partial match All data are searched. (Equivalent to Simple search) Yes 11 ndl_jpno
Yes Yes Prefix match National Bibliography No. is searched. (Uniquely extended) No 12 ndl_dpid Yes Yes Yes Exact match Given data providers only are searched. (Uniquely extended) Yes 13 mediatype Yes
Yes
Exact
match
Material types are searched.
(Uniquely extended)
Yes
Note: The logical conditions between items are all AND.
Note: Space-separated multiple keywords can be specified for an item other than isbn, issn, and ndl_jpno.
If multiple keywords are specified, OR search is used for "ndl_dpid" and AND search for other items.
*1: If "aufirst" and "aulast" are specified at the same time, these two conditions are used for AND search.
NDL Search Application Programming Interface (API) Specifications (Ver. 1.24) 20 / 27 (6) Number of returned data records Number of returned data records is limited to 500.
(7) Return format Data is returned in the HTML format to requested client, and is displayed in GUI on browser.
(8) Request example Example 1: Title includes "
http://iss.ndl.go.jp/api/openurl?btitle=%e9%9b%bb%e5%ad%90%e5%9b%b3%e6%9b%b8%e9%a4%a8
Example 2: Author includes "
http://iss.ndl.go.jp/api/openurl?au=%e5%a4%8f%e7%9b%ae%e6%bc%b1%e7%9f%b3
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).
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