レファレンス協同データベースシステム 検索用API 1.0 仕様書
リクエストパラメータ
| 項目 | 必須区分 | パラメータ | 値 | 内容 | 備考 |
| 検索条件結合 | 任意 | query_logic | int | 1 ： AND条件で結ぶ 2 ： OR条件で結ぶ |
queryで複数条件が指定された場合の項目間の結合パターンを指定 指定がない場合はデフォルト値「1」を補完する。 |
| 検索条件 | 何れか必須 | query | string （UTF-8でURLエンコード） |
（通常検索 / NOT検索） 00_ / 00not_ ： 管理番号 01_ / 01not_ ： 質問 02_ / 02not_ ： 回答 03_ / 03not_ ： キーワード 04_ / 04not_ ： 参考資料 05_ / 05not_ ： 回答プロセス 06_ / 06not_ ： 照会先 07_ / 07not_ ： 事前調査事項 08_ / 08not_ ： 寄与者 09_ / 09not_ ： 備考 10_ / 10not_ ： 提供館名 |
検索項目に管理番号が指定された場合のみ前方一致で、それ以外は中間一致で検索する。 検索項目は最大5つまでセパレータ『.』(半角ピリオド)で連結可能とする。 また、項目内の条件はスペース区切り（AND条件）、またはカンマ区切り（OR条件）で5個まで指定可能とする。 ※区切り文字のスペースとカンマは全角、半角の区別をしない |
| NDC | NDC | 値の先頭に『not_』が設定されていた場合は、Not検索として扱う。 | 前方一致で検索する。 セパレータ『.』（半角ピリオド）で最大3つまで指定可能とする。 |
||
| 登録番号 | SYS-ID | 完全一致で検索する。 | |||
| 提供館コード | LIB-ID | 値の先頭に『not_』が設定されていた場合は、Not検索として扱う。 | 完全一致で検索する。 | ||
| 事例作成日FROM | CRT-DATE_from | YYYYMMDD | |||
| 事例作成日TO | CRT-DATE_to | YYYYMMDD | |||
| 登録日FROM | REG-DATE_from | YYYYMMDD | |||
| 登録日TO | REG-DATE_to | YYYYMMDD | |||
| 最終更新日FROM | LST-DATE_from | YYYYMMDD | |||
| 最終更新日TO | LST-DATE_to | YYYYMMDD | |||
| 検索対象 | 任意 | LIB-GROUP | int | 0 ： 全館 1 ： NDL 2 ： 公共図書館 3 ： 大学図書館等 4 ： 専門図書館 5 ： アーカイブズ |
指定がない場合はデフォルト値「0」を補完する。 |
| 解決／未解決 | 任意 | SOLUTION | int | 0 ： 解決 1 ： 未解決 2 ： 解決／未解決 |
「2」は解決または未解決の情報が登録されているデータのみを検索する。 |
| 調査種別 | 任意 | RES-TYPE | string （UTF-8でURLエンコード） |
中間一致で検索する。 | |
| 内容種別 | 任意 | CON-TYPE | string （UTF-8でURLエンコード） |
中間一致で検索する。 | |
| 質問者区分 | 任意 | PTN-TYPE | string （UTF-8でURLエンコード） |
中間一致で検索する。 | |
| 検索結果取得位置 | 任意 | results_get_position | int | 指定がない場合はデフォルト値「1」を補完する。 | |
| 検索結果返却件数 | 任意 | results_num | int | 指定がない場合はデフォルト値「200」を補完する。 | |
| ソート条件 | 任意 | sort | int | 10 ： 最終更新日時による降順 11 ： 最終更新日時による昇順 20 ： 事例作成日による降順 21 ： 事例作成日による昇順 30 ： 管理番号による降順 31 ： 管理番号による昇順 40 ： 登録番号による降順 41 ： 登録番号による昇順 50 ： 被参照数による降順 51 ： 被参照数による昇順 |
指定がない場合はデフォルト値「10」を補完する。 |
- 定義にないパラメータは無視します。
- パラメータは大文字・小文字を区別します。(大文字・小文字を誤って指定した場合、その項目を無視します）
- 「.（半角ピリオド）」は検索キーワードとして使用できません。URLを検索したい場合は、「.（半角ピリオド）」を「%20(半角スペース)」に置き換えてAND検索をするなどの対応をお願いします（AND検索は5個まで指定可能）。
例：「crd.ndl.go.jp」→「crd%20ndl%20go%20jp」
レスポンスフィールド
| 項目名 | レファ協システムDB レファレンス事例テーブル 項目名 |
タグ名 | 項目説明 | |||
| 第1階層 | 第2階層 | 第3階層 | 4階層 | |||
| 返却結果ルートノード | （対応なし） | result_set | 【XML親要素】要素内容はなし。 | |||
| ヒット数 | （対応なし） | hit_num | リクエストされた検索条件に該当する事例数（ヒット数） | |||
| 検索開始位置 | （対応なし） | results_get_position | 検索開始位置。 ・リクエストで指定されたresults_get_positionの値と同一の値を出力 ・リクエストで指定されなかった場合は1(デフォルト：先頭位置から検索開始)を出力 | |||
| 検索結果返却件数 | （対応なし） | results_num | ||||
| 処理コード | （対応なし） | results_cd | 処理コードと、エラー内容によってはエラー位置 例：0301(2) |
|||
| 返却結果フィールド | （対応なし） | result | 要素内容はなし。検索結果が複数件になる場合、『result』タグが結果件数分表示される『QUESTION』『REG-ID』『ANSWER』『CRT-DATE』『SOLUTION』『KEYWORD』『NDC』『NDC-NOTE』『RES-TYPE』『CON-TYPE』『BIBL』『ANS-PROC』『REFERRAL』『PRE-RES』『NOTE』『PTN-TYPE』『CONTRI』『REG-DATE』『LST-DATE』『SYS-ID』『LIB-ID』『LIB-NAME』『URL』『IMAGE』『position』の親要素 | |||
| 質問 | 質問 | QUESTION | ||||
| 管理番号 | 管理番号 | REG-ID | ||||
| 回答 | 回答 | ANSWER | ||||
| 事例作成日 | 事例作成日(表示用) | CRT-DATE | ||||
| 解決/未解決 | 解決/未解決 | SOLUTION | 「解決」「未解決」の文字列を出力 | |||
| キーワード | キーワード | KEYWORD | ※登録数分タグ出力される | |||
| NDC | NDC | NDC | ※登録数分タグ出力される | |||
| NDCデコード値 | NDC | NDC-NOTE | NDCデコード値(NDC：NDC版) 例）経書(123：9版) 経書(123) ・NDC版のみで、NDCが登録されていないデータは出力しない。 ・版がない場合は「NDCデコード値(NDC)」と出力する。 ・定義されていないNDCコードが登録されており、かつ版がある場合は、「(NDC：NDC版)」と出力する。 ・定義されていないNDCコードが登録されており、かつ版がない場合は、「(NDC)」と出力する。 ・7版、8版、9版の場合も10版のデコード値を出力する。 ※登録数分タグ出力される。 |
|||
| 調査種別 | 調査種別 | RES-TYPE | ||||
| 内容種別 | 内容種別 | CON-TYPE | ||||
| 参考資料 | 参考資料－書誌的事項 参考資料－ISBN 参考資料－備考 |
BIBL | 出力形式は下記に従う。 ・書誌的事項が記載されており、備考が記載されている →『書誌的事項 （備考） 』を出力 ・書誌的事項が記載されており、備考が記載されていない →『書誌的事項』を出力 ・書誌的事項が記載されておらず、備考が記載されている →『(備考)』を出力 ※登録数分タグ出力される |
|||
| 回答プロセス | 回答プロセス | ANS-PROC | ||||
| 照会先 | 照会先 | REFERRAL | ※登録数分タグ出力される | |||
| 事前調査事項 | 事前調査事項 | PRE-RES | ||||
| 備考 | 備考 | NOTE | ||||
| 質問者区分 | 質問者区分 | PTN-TYPE | ||||
| 寄与者 | 寄与者 | CONTRI | ※登録数分タグ出力される | |||
| 登録日時 | 登録日時 | REG-DATE | ||||
| 最終更新日時 | 更新日時 | LST-DATE | ||||
| 登録番号 | システムID（登録番号） | SYS-ID | ||||
| 提供館コード | 図書館コード※ | LIB-ID | ||||
| 提供館名 | 図書館名（正式）※ | LIB-NAME | ||||
| URL | （対応なし） | URL | 一般公開用詳細表示画面のURL | |||
| 関連ファイル | （対応なし） | IMAGE | 関連ファイルの有無 関連ファイルの登録がある場合は登録数問わず「有」、 登録がない場合は「無」という文字列を出力する |
|||
| 連番 | （対応なし） | position | results_get_position（検索開始位置）からの相対的な位置（OFFSET） 。0から順に採番(0、1、2．．．)『results_get_position（検索開始位置） + position（連番）』の値が、検索結果全体から見たデータ位置を表す。 | |||
処理コード
| コード | 説明 |
| 0001 | 正常終了 |
| 0101 | 検索必須項目不正 （必須項目未設定でのリクエスト） |
| 0102 | リクエストエラー（query_logicパラメータが複数指定された） 例） ・・・?query_logic=1&query_logic=1&・・・ |
| 0103 | リクエストエラー（queryパラメータが複数指定された） |
| 0104 | リクエストエラー（NDCパラメータが複数指定された） |
| 0105 | リクエストエラー（SYS-IDパラメータが複数指定された） |
| 0106 | リクエストエラー（LIB-IDパラメータが複数指定された） |
| 0107 | リクエストエラー（CRT-DATE_fromパラメータが複数指定された） |
| 0108 | リクエストエラー（CRT-DATE_toパラメータが複数指定された） |
| 0109 | リクエストエラー（REG-DATE_fromパラメータが複数指定された） |
| 0110 | リクエストエラー（REG-DATE_toパラメータが複数指定された） |
| 0111 | リクエストエラー（LST-DATE_fromパラメータが複数指定された） |
| 0112 | リクエストエラー（LST-DATE_toパラメータが複数指定された） |
| 0113 | リクエストエラー（LIB-GROUPパラメータが複数指定された） |
| 0114 | リクエストエラー（SOLUTIONパラメータが複数指定された） |
| 0115 | リクエストエラー（CON-TYPEパラメータが複数指定された） |
| 0116 | リクエストエラー（RES-TYPEパラメータが複数指定された） |
| 0117 | リクエストエラー（PTN-TYPEパラメータが複数指定された） |
| 0118 | リクエストエラー（results_get_positionパラメータが複数指定された） |
| 0119 | リクエストエラー（results_numパラメータが複数指定された） |
| 0120 | リクエストエラー（sortパラメータが複数指定された） |
| 0201 | query_logic指定不正 (1 or 2 以外が指定された) |
| 0301 | query書式不正 (検索範囲指定不正) |
| 0302 | query書式不正 (6つ以上の項目内AND・OR) |
| 0303 | query書式不正 (6つ以上の検索条件が『.』で連結されている) |
| 0401 | NDC指定不正 (4桁以上で入力された) |
| 0402 | NDC指定不正 (NOT検索時の先頭『not_』以外の位置に数字以外が入力された) |
| 0403 | NDC指定不正 (4つ以上のNDCが『.』で連結されている) |
| 0501 | SYS-ID指定不正 (数字以外が入力された) |
| 0601 | LIB-ID指定不正 (NOT検索時の先頭『not_』以外の位置に、数字以外が入力された) |
| 0701 | CRT-DATE_from指定不正 （数字以外が入力された） |
| 0702 | CRT-DATE_from指定不正 （入力が8文字以外） |
| 0703 | CRT-DATE_to指定不正 （数字以外が入力された） |
| 0704 | CRT-DATE_to指定不正 （入力が8文字以外） |
| 0705 | CRT-DATE_from、CRT-DATE_to指定不正 (TOがFROMより過去) |
| 0706 | CRT-DATE_from指定不正 （存在しない日付が指定された 20091301,20090135 等） |
| 0707 | CRT-DATE_to指定不正 （存在しない日付が指定された 20091301,20090135 等） |
| 0801 | REG-DATE_from指定不正 （数字以外が入力された） |
| 0802 | REG-DATE_from指定不正 （入力が8文字以外） |
| 0803 | REG-DATE_to指定不正 （数字以外が入力された） |
| 0804 | REG-DATE_to指定不正 （入力が8文字以外） |
| 0805 | REG-DATE_from、REG-DATE_to指定不正 (TOがFROMより過去) |
| 0806 | REG-DATE_from指定不正 （存在しない日付が指定された 20091301,20090135 等） |
| 0807 | REG-DATE_to指定不正 （存在しない日付が指定された 20091301,20090135 等） |
| 0901 | LST-DATE_from指定不正 （数字以外が入力された） |
| 0902 | LST-DATE_from指定不正 （入力が8文字以外） |
| 0903 | LST-DATE_to指定不正 （数字以外が入力された） |
| 0904 | LST-DATE_to指定不正 （入力が8文字以外） |
| 0905 | LST-DATE_from、LST-DATE_to指定不正 (TOがFROMより過去) |
| 0906 | LST-DATE_from指定不正 （存在しない日付が指定された 20091301,20090135 等） |
| 0907 | LST-DATE_to指定不正 （存在しない日付が指定された 20091301,20090135 等） |
| 1001 | LIB-GROUP 0 or 1 or 2 or 3 or 4 or 5 以外の数字・文字が入力された |
| 1101 | SOLUTION 0 or 1 or 2 以外の数字・文字が入力された |
| 1201 | results_get_position 数字以外が入力された |
| 1202 | results_get_position 整数型最大長エラー (int型の最大値2147483647より大きい値が指定された) |
| 1203 | results_get_position 0が指定された |
| 1301 | results_num 数字以外が入力された |
| 1302 | results_num 整数型最大長エラー (int型の最大値2147483647より大きい値が指定された) |
| 1401 | sort 規定されているパターン(10,11,20,21,30,31,40,41,50,51) 以外が指定された |
| 9901 | DB接続不正 （DB接続に失敗した） |
| 9902 | 内部例外発生 |
| 9903 | GETメソッド以外でリクエストが送信された |
検索例
- 自館のデータを取得したい！（国立国会図書館）
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?LIB-ID=1110001検索結果を確認する
- 指定がないので、最終更新日の降順で200件目までのデータが取得されます。
- 自館データの被参照数トップ10を取得したい！（国立国会図書館）
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?LIB-ID=1110001&sort=50&results_num=10検索結果を確認する
- 被参照数の降順（sort=50）、返却件数10件（results_num=10）と指定しています。
- 被参照数トップ10を取得したい！（全館）
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?LST-DATE_from=20030101&sort=50&results_num=10検索結果を確認する
- LST-DATE_from=20030101は、2003年1月1日以降に更新されたデータです。日付はYYYYMMDD（年月日）で指定します。
- 質問に「さくら」を含む事例を検索したい！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=01_%e3%81%95%e3%81%8f%e3%82%89検索結果を確認する
- リクエストはUTF-8にてエンコードする必要があります。
- 「query=01_」は「質問」をあらわします。
- 「%e3%81%95%e3%81%8f%e3%82%89」は「さくら」をUTF-8でエンコードしたものです。
- 回答に「天気」と「予報」を含むデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=02_%e5%a4%a9%e6%b0%97%20%e4%ba%88%e5%a0%b1検索結果を確認する
- 「query=02_」は「回答」をあらわします。
- 「%20」はスペースをUTF-8でエンコードしたものです。このスペースは「天気」と「予報」をAND条件で結びます。
- 「%e5%a4%a9%e6%b0%97」は「天気」を、「%e4%ba%88%e5%a0%b1」は「予報」をUTF-8でエンコードしたものです。
- 回答に「天気」を含み、かつ参考資料に「事典」をを含むデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=02_%e5%a4%a9%e6%b0%97.04_%e4%ba%8b%e5%85%b8検索結果を確認する
- queryの「02_」は「回答」を、「04_」は「参考資料」をあらわします。
- ピリオド(.)で連結された項目間（ここでは回答と参考資料）を、「query_logic」で指定された条件（ANDまたはOR）で結びますが、ここでは「query_logic」が省略されているので、デフォルトの「AND条件」で結んでいます。
- 「%e5%a4%a9%e6%b0%97」は「天気」を、「%e4%ba%8b%e5%85%b8」は「事典」をUTF-8でエンコードしたものです。
- 質問あるいは回答に「中東」あるいは「中近東」を含むデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query_logic=2&query=01_%e4%b8%ad%e6%9d%b1%2c%e4%b8%ad%e8%bf%91%e6%9d%b1.02_%e4%b8%ad%e6%9d%b1%2c%e4%b8%ad%e8%bf%91%e6%9d%b1検索結果を確認する
- 「query_logic=2」はqueryのピリオド(.)で連結された項目間（ここでは質問と回答）を、「OR条件」で結びます。
- queryの「01_」は「質問」を、[02_」は「回答」をあらわします。
- 「%2c」はカンマ(,)をUTF-8でエンコードしたものです。このカンマは「中東」と「中近東」をOR検索で結びます。
- 「%e4%b8%ad%e6%9d%b1」は「中東」を、「%e4%b8%ad%e8%bf%91%e6%9d%b1」は「中近東」をUTF-8でエンコードしたものです。
- 質問に「奈良」を含むが、「奈良時代」を含まないデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=01_%e5%a5%88%e8%89%af.01not_%e5%a5%88%e8%89%af%e6%99%82%e4%bb%a3検索結果を確認する
- 「query_logic」は省略されており、デフォルトのAND条件で、「奈良」と「not奈良時代」を結んでいます。
- 「%e5%a5%88%e8%89%af」は「奈良」を、「%e5%a5%88%e8%89%af%e6%99%82%e4%bb%a3」は「奈良時代」をUTF-8でエンコードしたものです。
- NDCが「556（各種の船舶．艦艇）」あるいは「665（漁船．漁具）」のデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?NDC=556.665検索結果を確認する
- NDCは前方一致、OR検索です。
- キーワードに「金沢」を含み、かつNDCが「7(芸術)「8(言語)「9(文学)」で始まらないデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=03_%e9%87%91%e6%b2%a2&NDC=not_7.8.9検索結果を確認する
- queryの「03_」は「キーワード」をあらわします。
- NOT検索は、全体（7,8,9すべて）にかかります。個別に指定することはできません。
- 「%e9%87%91%e6%b2%a2」は「金沢」をUTF-8でエンコードしたものです。
- 回答に「crd.ndl.go.jp」を含むデータを検索！
- https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=02_crd%20ndl%20go%20jp検索結果を確認する
- queryの「02_」は「回答」をあらわします。
- 「.（半角ピリオド）」は検索のキーワードとして使用できないため、URLなどを検索する際には「.」を「%20（半角スペース）」に置き換え、AND検索をするなどで対応をお願いいたします。（AND検索は5個まで指定可能）
（参考）検索開始位置・ヒット数・返却数の関係
- リクエストパラメータ
- results_get_position
検索結果の取得開始位置 - results_num
検索結果返却件数
- results_get_position
- レスポンスフィールド
- hit_num
リクエストされた検索条件に該当する事例数（ヒット数） - results_get_position
検索結果の取得開始位置（リクエストパラメータの入力内容と同一値を出力） - results_num
検索結果返却件数- 検索によって得られたデータ数。
- リクエストパラメータresults_numで指定された件数が取得できない場合は、取得できる最大数を出力（例２参照）。
- position
results_get_positionからの相対的な位置（OFFSET）- 0から順に採番する（0、1、2......）
- 「results_get_position + position」の値が、検索結果全体から見たデータ位置を表す。
- hit_num
上記のリクエストパラメータとレスポンスフィールドの関係を図示すると次のとおりです。
- 例１：指定された検索結果返却件数を取得できる場合
- 『https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=01_%E5%9B%B3%E6%9B%B8%E9%A4%A8%E3%81%AE&results_get_position=１00&results_num=100』とリクエストした場合で、「query=01_%E5%9B%B3%E6%9B%B8%E9%A4%A8%E3%81%AE」でヒットする全体の件数が1000件であった場合。
- 「%E5%9B%B3%E6%9B%B8%E9%A4%A8%E3%81%AE」は「図書館の」をUTF-8でエンコードしたものです。
上記の例１では、100～199データ目の計100データが返却されます。
- 例２：指定された検索結果返却件数が取得できない場合
- 『https://crd.ndl.go.jp/refapi/servlet/refapi.RSearchAPI?query=TEST&results_get_position=１00&results_num=100』とリクエストした場合で、「query=01_TEST」でヒットする全体の件数が150件であった場合。
上記の例２では、100～150データ目の計51データが返却されます。