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.
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 https://www.loc.gov/standards/sru/diagnostics/diagnosticsList.html).
(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.
NDL search OpenSearch-API
Search request (URL)
Institution
OpenSearch
Search result (RSS2.0)
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.
NDL search OpenURL-API
Search request (URL)
Client
OpenURL
Search result (HTML)
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
http://iss.ndl.go.jp/api/openurl?genre=[genre]&…
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 "rtf.genre=.”
- 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