도서 검색 API
도서 검색 API는 모든 도서 서비스에 대한 검색 결과를 외부 개발자 및 사용자에게 XML 형식으로 전달하는 API 서비스입니다. 다음 도서 서비스에서 제공되는 모든 도서에 대한 서지 정보 및 리뷰 본문검색 서비스를 제공할 수 있게 해 줍니다.
요청 변수 (Request Parameters) #
- 공통 인증 변수: 모든 API 서비스 요청시 공통적으로 넣어야 할 변수는 아래와 같습니다.
인증 파라미터 #
- 인증에 사용되는 공통 파라미터를 설명합니다.
| 요청 변수 | 값 | 설명 |
| apikey | 40 byte hexadecimal string (필수) | 모든 오픈 API 호출에 공통으로 사용되는 인증키 입니다. Daum 회원이면, apikey를 발급 받을 수 있습니다. 오픈 API는 검색, UCC, 디앤샵 API로 구분됩니다. 나중에 다른 API가 추가될 수 도 있습니다. 각 API별로 Daum 회원은 하나의 apikey 만을 발급받을 수 있습니다. 그리고, 이 apikey로는 허가된 API만 호출 할 수 있습니다. 예) apikey=4125603e35da5d8820b07dc7b19050dbc838336b |
| apid | 20 byte hexadecimal string | 오픈 API를 이용하여 어플리케이션 이나 웹 사이트를 작성한 개발자 분들은 프로그램 등록을 할 수 있습니다. apid 는 등록된 프로그램에 대해서 오픈 API 인증 시스템에서 제공한 프로그램 아이디 입니다. 일부 오픈 API는 apid 파라미터를 필수로 요구하는 경우가 있습니다. 등록된 프로그램은 이 DNA 사이트를 통해서 홍보되며, 개발자 본인의 의사에 따라 다른 사용자가 다운받아 설치할 수 있게 됩니다. 예) apid=ba8c53ab7970189d93a7 |
서명 인증 파라미터 #
- 서명된 오픈 API는 인증키가 다른 사용자에 의해서 도용 되는 것을 보호해 줍니다.
- 서명은 필수적인 파라미터가 아닙니다. 그러나, 일부 오픈 API는 반드시 서명을 요구합니다.
- 서명에 사용되는 파라미터를 설명합니다.
| 이름 | 값 | 설명 |
| ts | YYYYMMDDhhmmss | 오픈 API를 호출하는 시간. UTC Time 으로 변환되서 전달되어야 합니다. 서명 값(sig)을 전달할 때 반드시 포함되어야 합니다. 예, ts=20060501153010 |
| nonce | 16 byte hexadecimal string | 랜덤한 8byte binary 값. ts 와 함께 서명의 재 사용여부를 확인하는데 사용됩니다. 서명 값(sig)을 전달할 때 반드시 포함되어야 합니다. 예, nonce=bd149ae021feb132 |
| sigalg | "hmacsha1" | 서명에 사용하는 알고리즘 이름. "hmacsha1" 으로 고정되어 있습니다. 실제 사용하는 알고리즘은 RFC 2014 에 정의되어 있는 HMACSHA-1 입니다. 서명 값(sig)을 전달할 때 반드시 포함되어야 합니다. |
| sig | 40 byte hexadecimal string | 오픈 API 호출 URL 전체에 대해서 서명키로 서명한 값. 예) sig=b45de8a31aed6e58b831dd72087bb4ed71fcaf98 |
- 서명 값 만들기 & 소스 예제 코드 : HowToSign
- 서비스 인증 변수: 본 서비스에서 사용되는 변수는 아래와 같습니다.
| 요청 변수 | 값 | 설명 |
| q | string (필수) | 검색을 원하는 질의 |
| target | string : meta(기본값), content(추후지원예정), review(추후지원예정) | 검색할 대상 정보. meta는 서지, content는 본문, review는 리뷰를 검색합니다. 지금 서비스에서는 meta만 지원하며 content, review는 추후 지원 예정입니다 |
| cate_id | integer (Optional) | 검색 범위 카테고리를 지정. 카테고리 정보는 아래와 같습니다. 전체 카테고리를 검색하려면 이 파라미터를 사용하지 않으면 됩니다. * 소설 : 1 * 시/에세이/기행 : 3 * 인문 : 5 * 가>족/생활/요리 : 7 * 건강/의학 : 9 * 여행/취미 : 11 * 경영/경제 : 13 * 자기계발 : 15 * 사회/정치/법 : 17 * 역사/풍속/신화 : 19 * 종교 : 21 * 예술/대중문화 : 23 * 학습지/참고서 : 25 * 외국어 : 27 * 자연과학/>공학 : 29 * 수험서 : 31 * 컴퓨터/인터넷 : 33 * 잡지 : 35 * 사전 : 37 * 청소년 : 38 * 유아 : 41 * 아동 : 42 * 어린이영어 : 45 * 만화 : 47 * 기타 : 100 * 외국 : 101 * 일본 : 102 |
| result | integer : 기본값 10, 최소 1, 최대 20 | 한 페이지에 출력될 결과수 |
| pageno | integer : 기본값 1, 최소 1, 최대 500 | 검색 결과 페이지 번호 |
| sort | string : poplular(기본값), accu, date | 검색 결과의 정렬순서 * popular : 판매량순 * accu : 정확도순 * date : 최신자료순 |
| output | string : xml (기본값), rss, json | 출력방식 * xml 방식으로 제공 가능합니다. * rss 방식으로 제공 가능합니다. * json 방식으로 제공 가능합니다. |
- 상세검색 파라미터(Optional)
| 파라미터 | 값 | 설명 |
| book_nm | string | 서명에서 검색 |
| isbn | integer | ISBN번호에서 검색 |
| author | string | 저자명에서 검색 |
| pub_nm | string | 출판사명에서 검색 |
| translator | string | 역자명에서 검색 |
출력 방식 (Response Method) #
- RSS방식으로 제공 가능합니다.
- JSON방식으로 제공 가능합니다.
- XML방식으로 제공 가능합니다.
출력 결과 (Response Elements) #
- 출력 결과
| 출력 변수 | 값 | 설명 |
| title | string | 검색 제목 |
| link | string | 서비스 URL |
| lastBuildDate | string | 검색 시간 |
| totalCount | integer | 전체 검색 결과의 수 |
| sort | string | 검색 결과의 정렬순 |
| result | integer | 한 페이지에 보여질 결과 수 |
| target | string | 검색 대상 |
| pageno | integer | 검색 결과의 페이지 번호 |
| elapsed_time | integer | 검색에 걸린 시간 |
| q | string | 검색어 |
| item | - | 개별 검색 결과 정보(아래에 설명) |
- item
| 출력 변수 | 값 | 설명 |
| title | string | 책 제목 |
| link | string | 책에 대한 페이지 link url |
| cover_s_url | string | 표지 이미지(small) |
| cover_l_url | string | 표지 이미지(large) |
| description | string | 책에 대한 설명 |
| author | string | 저자 |
| translator | string | 역자 |
| pub_nm | string | 출판사 |
| pub_date | string | 출판일 |
| category | string | 카테고리 정보 |
| isbn | string | ISBN 번호 |
| sale_yn | string | 판매 가능 여부 |
| list_price | string | 원가격 |
| sale_price | string | 판매가격 |
| status_des | string | 책의 현재 상태(정상,품절,절판 등) |
| barcode | string | 교보문고 바코드 정보 |
| ebook_barcode | string | 교보문고 전자 책 바코드 정보 |
출력 결과 샘플 페이지 #
- xml 출력 결과
<?xml version="1.0" encoding="utf-8"?> <channel> <title><![CDATA[Daum Open API - book Search query : '공주']]></title> <link><![CDATA[http://apis.daum.net/search/book]]></link> <lastBuildDate>Thu, 16 Nov 06 16:57:07 +0900</lastBuildDate> <totalCount>973</totalCount> <sort>popular</sort> <result>10</result> <target>meta</target> <pageno>1</pageno> <elapsed_time>14.997959137</elapsed_time> <q>공주</q> <item> <title><![CDATA[<B>종이봉지공주</B>(비룡소 그림동화 049)]]></title> <link><![CDATA[http://book.daum.net/bookdetail/book.do?bookid=KOR9788949110479]]></link> <cover_s_url><![CDATA[http://photo-book.hanmail.net/images/book/medium/479/m9788949110479.jpg]]></cover_s_url> <cover_l_url><![CDATA[http://photo-book.hanmail.net/images/book/large/479/l9788949110479.jpg]]></cover_l_url> <description><![CDATA[멋진 왕자와 결혼해서 행복하게 살아갈 꿈에 부풀어 있던 <B>공주는</B> 갑자기 들이닥쳐 궁을 모두 불태우고 왕 자를 잡아간 용을 찾아갑니다. 꾀를 내어 용을 잠재우고 왕자를 구하지만 은혜도 모르고 철없는 그에게 실 ]]></description> <author><![CDATA[로버트 문치]]></author> <translator><![CDATA[김태희]]></translator> <pub_nm><![CDATA[비룡소]]></pub_nm> <pub_date><![CDATA[Tue, 22 Dec 98 00:00:00 +0900]]></pub_date> <category><![CDATA[유아]]></category> <isbn><![CDATA[8949110474]]></isbn> <sale_yn><![CDATA[Y]]></sale_yn> <list_price><![CDATA[6500]]></list_price> <sale_price><![CDATA[5200]]></sale_price> <status_des><![CDATA[정상]]></status_des> <barcode><![CDATA[9788949110479]]></barcode> <ebook_barcode><![CDATA[4808949110479]]></ebook_barcode> </item> </channel>
- rss 출력 결과
<?xml version="1.0" encoding="utf-8"?> <rss version="2.0"> <channel> <title><![CDATA[Daum Open API - book Search query : '공주']]></title> <link><![CDATA[http://apis.daum.net/search/book]]></link> <description><![CDATA[Daum Open API book Search result]]></description> <lastBuildDate>Thu, 16 Nov 06 16:52:07 +0900</lastBuildDate> <generator>Daum Open API :: Search - book</generator> <totalCount>973</totalCount> <sort>popular</sort> <result>10</result> <range>all</range> <pageno>1</pageno> <q>공주</q> <item> <title><![CDATA[<B>종이봉지공주</B>(비룡소 그림동화 049)]]></title> <description><![CDATA[<img src="http://photo-book.hanmail.net/images/book/medium/479/m9788949110479.jpg"> 멋진 왕자와 결혼해서 행복하게 살아갈 꿈에 부풀어 있던 <B>공주는</B> 갑자기 들이닥쳐 궁을 모두 불태우고 왕 자를 잡아간 용을 찾아갑니다. 꾀를 내어 용을 잠재우고 왕자를 구하지만 은혜도 모르고 철없는 그에게 실]]></description> <link><![CDATA[http://book.daum.net/bookdetail/book.do?bookid=KOR9788949110479]]></link> <author><![CDATA[로버트 문치]]></author> <pub_date><![CDATA[Tue, 22 Dec 98 00:00:00 +0900]]></pub_date> <category><![CDATA[유아]]></category> <imageSmall><![CDATA[http://photo-book.hanmail.net/images/book/medium/479/m9788949110479.jpg]]></imageSmall> <image><![CDATA[http://photo-book.hanmail.net/images/book/large/479/l9788949110479.jpg]]></image> <translator><![CDATA[김태희]]></translator> <pub_nm><![CDATA[비룡소]]></pub_nm> <isbn><![CDATA[8949110474]]></isbn> <sale_yn><![CDATA[Y]]></sale_yn> <list_price><![CDATA[6500]]></list_price> <sale_price><![CDATA[5200]]></sale_price> <status_des><![CDATA[정상]]></status_des> <barcode><![CDATA[9788949110479]]></barcode> <ebook_barcode><![CDATA[4808949110479]]></ebook_barcode> </item> </channel> </rss>
- json 출력 결과
{"channel":{
"title":"Daum Open API - book Search query : '\uacf5\uc8fc'",
"link":"http:\/\/apis.daum.net\/search\/book",
"lastBuildDate":"Fri, 17 Nov 06 09:55:34 +0900",
"totalCount":973,
"sort":"popular",
"result":10,
"target":"meta",
"pageno":1,
"elapsed_time":13.7410164,
"q":"\uacf5\uc8fc",
"item":[{
"title":"\ud638\ub3d9\uc655\uc790\uc640 <B>\ub099\ub791\uacf5\uc8fc<\/B>(\ub9cc\ud654\ub85c \ubcf4\ub294 \uc6b0\ub9ac\ub098\ub77c \uc0bc\ud55c\uc9c0 2)",
"link":"http:\/\/book.daum.net\/bookdetail\/book.do?bookid=KOR9788959190881",
"cover_s_url":"http:\/\/photo-book.hanmail.net\/images\/book\/medium\/881\/m9788959190881.jpg",
"cover_l_url":"http:\/\/photo-book.hanmail.net\/images\/book\/large\/881\/l9788959190881.jpg",
"description":"\u300e\uc6b0\ub9ac\ub098\ub77c \uc0bc\ud55c\uc9c0\u300f\uc2dc\ub9ac\uc988 \uc81c2\uad8c\u300a\ud638\ub3d9\uc655\uc790\uc640 <B>\ub099\ub791\uacf5\uc8fc\u300b<\/B>. \ubcf8 \uc2dc\ub9ac\uc98c \uc6b0\ub9ac\ub098\ub77c \uc5ed\uc0ac \uc911 \uac00\uc7a5 \uadf9\uc801\uc774\uace0 \uc9c4\ucde8\uc801\uc774\uc5c8\ub358 \uc0bc\uad6d\uc2dc\ub300\ub97c \ubc30\uacbd\uc73c\ub85c \ud55c \uc5ed\uc0ac \ub9cc\ud654\uc785\ub2c8\ub2e4. \uac00\uc7a5 \ud070 \ud2b9\uc9d5\uc740 \ud654\uc790\uc778 \ud560\uc544\ubc84\uc9c0\uac00 \uc190\uc790\ub4e4\uc5d0\uac8c \uc61b\ub0a0",
"author":"\ub958\uae30\uc6b4",
"translator":"",
"pub_nm":"\uc560\ub2c8\ubd81\uc2a4",
"pub_date":"Tue, 01 Aug 06 00:00:00 +0900",
"category":"\uc544\ub3d9",
"isbn":"8959190888",
"sale_yn":"Y",
"list_price":"8900",
"sale_price":"8010",
"status_des":"\uc815\uc0c1",
"barcode":"9788959190881",
"ebook_barcode":""}]
}
}
오류 메시지 #
- 공통 오류 메시지는 다음과 같습니다.
오류는 다음과 같은 XML로 전달됩니다.
<?xml version="1.0" encoding="UTF-8"?>
<apierror>
<code></code>
<message></message>
<dcode></code>
<dmessage></dmessage>
</apierror>
오류 XML의 각 항목은 아래와 같은 값을 가집니다.
| 오류 코드 (code|dcode) | 오류(message) | 상세 오류(dmessage) | 설명 |
| 10 | | invalid request | 오픈 API 호출이 공통 호출 규약에 맞지 않은 경우에 전달된다. | |
| 10 | 11 | invalid request | apikey missing | apikey 파라미터가 없음 |
| 10 | 12 | invalid request | Missing auth parameter 'ts'. | ts 파라미터가 없음 |
| 10 | 13 | invalid request | Missing auth parameter 'nonce'. | nonce 파라미터가 없음 |
| 10 | 14 | invalid request | Missing auth parameter 'sigalg'. | sigalg 파라미터가 없음 |
| 10 | 15 | invalid request | Missing auth parameter 'sig'. | sig 파라미터가 없음 |
| 10 | 18 | invalid request | Missing parameter 'apid'. | apid 파라미터가 없음 |
| 20 | | unknown ap instance | 프로그램 인증 실패. | |
| 20 | 21 | unknown ap instance | invalid apikey | 유효하지 않은 apikey |
| 20 | 22 | unknown ap instance | unregistered apikey | 등록되지 않은 apikey |
| 20 | 23 | unknown ap instance | unregistered apid | 등록되지 않은 apid |
| 20 | 24 | unknown ap instance | Signature sigkey is not valid. | 유효하지 않은 서명키 |
| 20 | 25 | unknown ap instance | invalid apid | 유효하지 않은 apid |
| 20 | 26 | unknown ap instance | SignatureKey is not issued to this apikey. | apikey 해당하지 않는 서명키 |
| 20 | 27 | unknown ap instance | ts, nonce are reused. | ts,nonce 재사용 오류 |
| 20 | 28 | unknown ap instance | Unsupported Sign Algorithm. | 지원하지 않는 서명 알고리즘 |
| 30 | | unknown daumuser | apikey 소유자의 Daum 인증 실패. | |
| 40 | | access denied | 서비스 접근 거부 | |
| 40 | 41 | access denied | valid api call but traffic overed | 하루 api 호출 traffic 초과 |
| 40 | 42 | access denied | apikey does not match api category | 이 apikey 로 호출할 수 있는 api 가 아님 |
| 40 | 43 | access denied | unsigned call | 서명되지 않은 호출 |
| 40 | 44 | access denied | unregistered ip | 등록되지 않은 IP 주소 |
| 40 | 45 | access denied | apid doesnot use api | 프로그램이 이 api를 사용하고 있지 않음 |
| 404 | no such api | 해당 오픈 API 서비스가 없음 | |
| 500 | system error | 오픈 API 서비스 내부 시스템 에러. | |
| 504 | service timeout | 오픈 API 서비스 연결 실패. 서비스 시스템 과부하 또는 장애로 인한 서비스 연결 실패. | |
| 100 | | service api runtime error | 오픈 API 서비스 실행 오류. 101~299 값을 가지며, 각 API 에서 정의함. |
- 이 서비스의 오류 메시지는 다음과 같습니다.
| 오류 코드(dcode) | 오류 설명(dmessage) |
| 100 | 제공되지 않는 검색 대상을 검색하려 할 때 발생(target 파라미터) |
| 101 | 검색 할 쿼리 파라미터가 null일 경우 발생 |
| 102 | 파라미터 이상 등으로 검색이 불가능할 경우 발생 |
| 103 | 지원하지 않는 출력 포멧을 요청 (xml,rss,json이 아닐 경우) |
트래픽 제한 #
- 오픈 API는 하나의 apikey에 대해서 하루 5,000 회의 호출 만을 허용합니다.
- 트래픽 제어는 보안을 위한 측면이 크며, 증가 추이에 따라 트래픽 허용 수를 늘리는 정책을 사용할 예정입니다.
- 상용 서비스를 위해 또는 사용자 증가로 인하여 허용 traffic 수를 늘리고자 할때에는 어플리케이션 등록을 마치고, 해당 apid에 대해 별도로 traffic 을 조정할 수 있습니다.