OpenAPI 안내(최종 수정일 : 2007.9.1)
- OpenAPI는 상품검색API(이하 검색API)와 하나의 상품을 열람하는API(이하 상품API)로 나눠집니다.
- 상품API는 하나의 상품만을 열람하므로 검색API의 결과보다 자세한 부가 정보가 더해진 결과가 나옵니다.
- 검색API와 상품API의 결과는 모두 XML형식(기본값), JSON형식(JSON-CallBack방식포함), 확장RSS(OpenSearch)형식으로 받으실 수 있습니다.
- 요청방식은 GET방식과 POST방식에 상관없이 요청 가능합니다.
- OpenAPI는 1일 5000회로 제한됩니다. 5000회 이상을 원하시는 분은 ttb@aladin.co.kr으로 연락바랍니다.
- 분류 ID값은 알라딘 모든 분야 카테고리 엑셀문서를 참고하십시오.
요청 방법
- 요청 URL : http://www.aladin.co.kr/ttb/api/ItemSearch.aspx
- 요청 URL샘플 : http://www.aladin.co.kr/ttb/api/ItemSearch.aspx?ttbkey=[TTBKey]
&Query=aladdin&QueryType=Title&MaxResults=10&start=1&SearchTarget=Book&output=xml&Version=20070901 - 결과샘플
XML형식 : http://www.aladin.co.kr/ttb/api/test/ItemSearch.xml
OpenSearch형식 : http://www.aladin.co.kr/ttb/api/test/ItemSearchOS.xml
javascript형식 : http://www.aladin.co.kr/ttb/api/test/ItemSearch.js
검색 요청(Request) 파라미터 스펙
| 구분 | 요청변수 | 변수종류 | 설명 |
| 필수 | TTBKey | 문자열 | 부여받은 TTBKey값 |
| Query | 문자열 | 검색어 | |
| 옵션 (옵션 조정 변수가 없을 경우에는 기본값으로 검색) |
QueryType | Title(기본값) : 제목검색 Author : 저자검색 Publisher : 출판사검색 |
검색어 종류 |
| SearchTarget | Book(기본값) : 도서 Music : 음반 DVD : DVD Beauty : 화장품 Gift : 기프트 |
검색 대상 Mall | |
| Start | 1이상, 양의 정수(기본값:1) | 검색결과 시작페이지 | |
| MaxResults | 1이상 100이하, 양의 정수(기본값:10) | 검색결과 한 페이지당 최대 출력 개수 | |
| Sort | PublishTime(기본값) : 출간일 Title : 제목 SalesPoint : 판매량 CustomerRating 고객평점 MyReviewCount :마이리뷰갯수 |
정렬순서 | |
| Cover | Big : 큰 크기 Mid(기본값) : 중간 크기 Small : 작은 크기 Mini : 매우 작은 크기 None : 없음 |
표지크기 | |
| CategoryId | 양의정수 - 분야의 고유 번호(기본값:0, 전체) (참고 : 알라딘 모든 분야 카테고리) |
특정 분야로 검색결과를 제한함 | |
| Output | XML(기본값) : REST XML형식 OS : 확장RSS(OpenSearch방식) JS : JSON방식 |
출력방법 | |
| Partner | 문자 | 파트너코드. 제휴사의 경우 파트너코드 입력으로 제휴사 유효성 체크. | |
| Omitkey | 양의정수(기본값:0) | Omitkey가 1인경우 결과링크값에 TTBKey가 제외됨. | |
| InputEncoding | 문자열(인코딩의 영문이름 - 기본값:utf-8) | 검색어의 인코딩 값을 설정. "utf-8"이나 "euc-kr"과 같은 인코딩의 영문이름. | |
| Version | 정수형 날짜 (기본값: 20070901) |
검색API의 Version(날짜형식)을 설정. | |
| CallBack | javascript function이름 | 호출후 불려질 javascript function의 이름을 지정. output이 js인 경우에 한해 작동됨. |
검색 응답(Reponse) 결과값 스펙
| 필드명 | 설명 | 자료형 |
| title | 조회결과의 제목 | 문자열 |
| link | 조회결과를 확인할 수 있는 Html페이지의 링크 | 문자열(URL) |
| language | 검색결과의 언어. 무조건 "ko"가 입력됨 | 문자열 |
| copyright | API제공자의 Copyright | 문자열 |
| pubDate | 조회시간(GMT기준시) | 날짜 |
| totalResults | 총 검색 결과 개수 | 정수형 |
| startIndex | 현재 페이지 | 정수형 |
| itemsPerPage | 한 페이지당 출력 결과 개수 | 정수형 |
| query | 요청 쿼리 | 문자열 |
| version | 현재 검색API의 Version | 정수형 날짜 |
| searchCategoryId | 특정 분야로 검색을 제한한 경우 분야의 고유번호 출력 | 정수형 |
| searchCategoryName | 특정 분야로 검색을 제한한 경우 분야의 이름 출력 | 문자열 |
| item < itemId | 해당 아이템의 고유한 값 | 숫자 |
| item < category (출력형식 OS에서만 해당) |
'알라딘'이 출력 | 문자열 |
| item < content:encoded (출력형식 OS에서만 해당) |
바로 사용할 수 있는 HTML이 포함된 간략한 상품 설명 | 문자열 |
| item < description | OS 출력형식: HTML이 없는 상품설명 기타 출력형식: HTML이 포함된 간략한 상품 설명 |
문자열 |
| item < pubDate item < dc:date |
도서 출간일(GMT기준) | 날짜 |
| item < dc:creator (출력형식 OS에서만 해당) |
'aladdin'이 출력 | 문자열 |
| item < priceStandard | 상품 정가 | 숫자(통화) |
| item < priceSales | 알라딘에서 판매하는 판매가(수시로 변동 가능) | 숫자(통화) |
| item < stockStatus | 상품의 재고 상태. 재고 보유 상태에서는 특별한 문자도 들어가있지 않으며 품절,절판 등의 특별한 상태일때만 문자열이 출력 |
문자열 |
| item < mileage | 상품 구입시 지급되는 마일리지 | 숫자(통화) |
| item < cover | 상품 표지 URL | 문자열(URL) |
| item < categoryId | 상품 대표 분야의 고유번호(알라딘은 복수 분류체계,그 중 대표 분류 하나)(참고 : 알라딘 모든 분야 카테고리) | 숫자 |
| item < categoryName | 대표 분류의 상위 분류들(분류 히스토리, "<"를 기준으로 나누어져 있음) | 문자열 |
| item < publisher | 상품의 출판사(제작사) | 문자열 |
| item < customerReviewRank | 상품에 대해 고객이 부여한 별점(10점만점) | 숫자 |
요청 방법
- 요청 URL : http://www.aladin.co.kr/ttb/api/ItemLookUp.aspx
- 요청 URL샘플 : http://www.aladin.co.kr/ttb/api/ItemLookUp.aspx?ttbkey=[TTBKey]&itemIdype=ISBN&ItemId=[도서의ISBN]&output=xml
- "상품 조회 응답(Reponse) 결과값"의 스펙은 "검색 응답(Reponse) 결과값"과 동일한 결과에 단순히 부가정보가 추가되어지는 것임.
- 도서의 경우 <bookinfo>, 음반의 경우 <musicinfo>, DVD의 경우 <dvdinfo>의 항목이 추가결과로 나옴. (화장품과 Gift몰상품은 특별한 부가정보 없이 검색결과와 같은 항목만 출력)
상품 조회 요청(Request) 파라미터
| 구분 | 요청변수 | 변수종류 | 설명 |
| 필수 | TTBKey | 문자열 | 부여받은 TTBKey값 |
| ItemId | 문자열/숫자 | 상품을 구분짓는 유일한 값 (ItemIdType으로 정수값과 ISBN중에 택일) |
|
| 옵션 (옵션 조정 변수가 없을 경우에는 기본값으로 조회) |
ItemIdType | ISBN(기본값) ItemId |
조회용 파라미터인 ItemId가 ISBN으로 입력되었는지, 알라딘고유의"ItemId"값으로 입력되었는지 선택 |
| Cover | Big : 큰 크기 Mid(기본값) : 중간 크기 Small : 작은 크기 Mini : 매우 작은 크기 None : 없음 |
표지크기 | |
| Output | XML(기본값) : REST XML형식 OS : 확장RSS(OpenSearch방식) JS : JSON방식 |
출력방법 | |
| Partner | 문자 | 파트너코드. 제휴사의 경우 파트너코드 입력으로 제휴사 유효성 체크. | |
| Omitkey | 양의정수(기본값:0) | Omitkey가 1인경우 결과링크값에 TTBKey가 제외됨. | |
| Version | 정수형 날짜 (기본값: 20070901) |
검색API의 Version(날짜형식)을 설정. | |
| CallBack | javascript function이름 | 호출후 불려질 javascript function의 이름을 지정. output이 js인 경우에 한해 작동됨. |
상품 조회 응답(Reponse) 결과값 스펙
| 필드명 | 설명 | 자료형 |
| bookinfo < subTitle | 부제 | 문자열 |
| bookinfo < originalTitle | 원제 | 문자열 |
| bookinfo < itemPage | 상품의 쪽수 | 숫자 |
| bookinfo < toc | 목차 | 문자열 |
| bookinfo < letslookimg | Let's Look(미리보기) 이미지 경로 | 문자열(URL) |
| musicinfo < catno | 음반 고유의 번호 | 문자열 |
| musicinfo < recommendationComment | 추천글 | 문자열 |
| dvdinfo < specialFeature | Special Feature | 문자열 |
| dvdinfo < disc | Disc장수 | 숫자 |
| dvdinfo < playtime | 상영시간 | 문자열 |
| dvdinfo < language | 언어 | 문자열 |
| dvdinfo < caption | 자막 | 문자열 |
| dvdinfo < screenrate | 화면비율 | 문자열 |
| dvdinfo < recordingtype | 오디오 | 문자열 |
| dvdinfo < areacode | 지역코드 | 숫자 |
| (musicinfo, dvdinfo) < authors | 참여 아티스트들의 이름 | 문자열 |
| (musicinfo, dvdinfo) < authors < author << authorType | 참여아티스트의 역할 | 문자열(영문) |
| (musicinfo, dvdinfo) < authors < author << authorid | 참여아티스트의 고유번호 | 숫자 |
| (musicinfo, dvdinfo) < authors < author << desc | authorType에대한 한글 설명 | 문자열(한글) |
예제 파일
- 아래 파일은 aladdin OpenAPI를 이용한 간단한 프로그램들입니다.
- C#의 경우는 Full Library를 제공하고, 기타 언어는 간단한 예제를 포함하고 있습니다.
- 개선사항이나 기타 문제점 발견시 ttb@aladin.co.kr로 연락바랍니다.
| 개발언어 | 다운로드 링크 | 테스트환경 |
| C# | [Down] | Microsoft.Net Framework 2.0/mono 1.2.5 |
| php | [Down] | PHP 5.2.4RC1 + Apache 2.2.5.0 |
| java | [Down] | java 1.6.0 |
| python | [Down] | python 2.5 |
| ruby | [Down] | ruby 1.8.6 |
| Power Shell | [Down] | Power Shell 1.0 |
