[통합] 알라딘 API 총정리

박정빈·2026년 4월 19일

알라딘 API

목록 보기

1/5

API 키 발급 및 URL 등록하기
이용 매뉴얼
이용 안내

요청 (Request)

1. 알라딘 상품 검색 API 명세서 (ItemSearch API)

알라딘의 방대한 도서, 음반, DVD 등 상품 데이터를 키워드를 통해 검색할 수 있는 API입니다.

1. 기본 정보

요청 URL: http://www.aladin.co.kr/ttb/api/ItemSearch.aspx
응답 형식: XML, JSON (기본값: XML)
제한 사항:
- 한 페이지에 최대 50개 출력 가능
- 검색 결과는 최대 200개까지만 제공

요청 샘플 (URL)

[http://www.aladin.co.kr/ttb/api/ItemSearch.aspx?ttbkey=]
(http://www.aladin.co.kr/ttb/api/ItemSearch.aspx?ttbkey=)
[TTBKey]&Query=aladdin&QueryType=Title&MaxResults=10
&start=1&SearchTarget=Book&output=xml&Version=20131101

2. 상품 검색 API 요청(Request) 파라미터

구분	요청변수	변수종류	필수여부	설명
필수	TTBKey	문자열	Y	알라딘에서 부여받은 TTBKey 값
	Query	문자열	Y	검색어 (제목, 저자 등)
옵션	QueryType	문자열	N	검색어 종류 - `Keyword`: 제목+저자 (기본값) - `Title`: 제목 검색 - `Author`: 저자 검색 - `Publisher`: 출판사 검색
	SearchTarget	문자열	N	검색 대상 Mall - `Book`: 도서 (기본값) - `Foreign`: 외국도서 - `Music`: 음반 - `DVD`: DVD - `Used`: 중고샵 - `eBook`: 전자책 - `All`: 전체
	Start	양의 정수	N	검색결과 시작 페이지 (기본값: `1`)
	MaxResults	양의 정수	N	페이지당 출력 개수 (1~100, 기본값: `10`)
	Sort	문자열	N	정렬 순서 - `Accuracy`: 관련도 (기본값) - `PublishTime`: 출간일 - `Title`: 제목 - `SalesPoint`: 판매량 - `CustomerRating`: 고객평점 - `MyReviewCount`: 마이리뷰 개수
	Cover	문자열	N	표지 이미지 크기 - `Big`: 200px - `MidBig`: 150px - `Mid`: 85px (기본값) - `Small`: 75px - `Mini`: 65px - `None`: 없음
	CategoryId	양의 정수	N	특정 분야(카테고리)로 검색 제한 (기본값: `0`)
	Output	문자열	N	출력 방법: `XML`(기본값), `JS`(JSON 방식)
	Partner	문자열	N	제휴사 파트너 코드
	includeKey	양의 정수	N	`1` 설정 시 링크에 TTBKey 포함 (기본값: `0`)
	InputEncoding	문자열	N	검색어 인코딩 (기본값: `utf-8`)
	Version	정수형 날짜	N	API 버전 설정 (최신: `20131101`)
	outofStockfilter	양의 정수	N	품절/절판 상품 필터링 (`1`이면 제외)
	RecentPublishFilter	양의 정수	N	최근 출간일 제한 필터 (0~60개월 사이)
	OptResult	문자열	N	부가 정보 요청 (Array 형태, 쉼표 구분) 예: `OptResult=ebookList,usedList`

3. OptResult 상세 옵션 (상품 검색 전용)

검색 시 추가 정보를 포함하고 싶을 때 OptResult 파라미터에 사용 가능한 값입니다.

ebookList: 해당 종이책의 전자책(eBook) 정보
usedList: 해당 상품에 등록된 알라딘/판매자 중고상품 정보
fileFormatList: 전자책의 파일 포맷(ePub, PDF 등) 및 용량

2. 알라딘 상품 리스트 API 명세서 (ItemList API)

신간 리스트, 베스트셀러, 편집자 추천 리스트 등 알라딘에서 제공하는 다양한 상품 리스트를 조회하는 API입니다.

1. 기본 정보

요청 URL: http://www.aladin.co.kr/ttb/api/ItemList.aspx
응답 형식: XML, JSON (기본값: XML)
조회 제한:
- 한 페이지당 최대 50개 출력 가능
- 총 결과는 최대 200개까지만 조회 가능

요청 샘플 (URL)

[http://www.aladin.co.kr/ttb/api/ItemList.aspx?ttbkey=]
(http://www.aladin.co.kr/ttb/api/ItemList.aspx?ttbkey=)
[TTBKey]&QueryType=ItemNewAll&MaxResults=10&
start=1&SearchTarget=Book&output=xml&Version=20131101

2. 상품 리스트 API 요청(Request) 파라미터

구분	요청변수	변수종류	필수여부	설명
필수	TTBKey	문자열	Y	알라딘에서 부여받은 TTBKey 값
	QueryType	문자열	Y	리스트 종류 - `ItemNewAll`: 신간 전체 리스트 - `ItemNewSpecial`: 주목할 만한 신간 리스트 - `ItemEditorChoice`: 편집자 추천 (분야 지정 필수) - `Bestseller`: 베스트셀러 - `BlogBest`: 블로거 베스트셀러
옵션	SearchTarget	문자열	N	조회 대상 Mall - `Book`(기본값), `Foreign`, `Music`, `DVD`, `Used`, `eBook`, `All`
	SubSearchTarget	문자열	N	`SearchTarget=Used`일 때 상세 지정 (`Book`, `Music`, `DVD`)
	Start	양의 정수	N	검색결과 시작 페이지 (기본값: `1`)
	MaxResults	양의 정수	N	페이지당 출력 개수 (1~100, 기본값: `10`)
	Cover	문자열	N	표지 크기 선택 - `Big`: 200px - `MidBig`: 150px - `Mid`: 85px (기본값) - `Small`: 75px - `Mini`: 65px - `None`: 없음
	CategoryId	양의 정수	N	특정 분야(카테고리)로 리스트 제한 (기본값: `0`)
	Output	문자열	N	출력 방법: `XML`(기본값), `JS`(JSON 방식)
	Partner	문자열	N	제휴사 파트너 코드
	includeKey	양의 정수	N	`1` 설정 시 링크에 TTBKey 포함 (기본값: `0`)
	InputEncoding	문자열	N	검색어 인코딩 설정 (기본값: `utf-8`)
	Version	정수형 날짜	N	API 버전 설정 (최신: `20131101`)
	outofStockfilter	양의 정수	N	품절/절판 상품 필터링 (`1`이면 제외)
	Year, Month, Week	정수	N	`QueryType=Bestseller`인 경우 특정 주간 조회 예: `Year=2022&Month=5&Week=3`
	OptResult	문자열	N	부가 정보 요청 (Array 형태, 쉼표 구분) 예: `OptResult=ebookList,usedList`

3. OptResult 상세 옵션 (상품 리스트 전용)

리스트 조회 시 추가 정보를 포함하고 싶을 때 OptResult 파라미터에 사용 가능한 값입니다.

ebookList: 해당 종이책의 전자책(eBook) 정보
usedList: 해당 상품에 등록된 중고상품 정보
fileFormatList: 전자책의 파일 포맷 및 용량 정보

3. 알라딘 상품 조회 API 명세서 (ItemLookUp API)

알라딘에 등록된 특정 상품(도서, 음반, DVD 등)의 상세 정보를 조회하기 위한 API입니다. 검색 결과값은 기본 검색 API와 동일한 구조를 가지며, 요청 시 추가 옵션에 따라 부가적인 정보를 함께 받아볼 수 있습니다.

1. 기본 정보

요청 URL: http://www.aladin.co.kr/ttb/api/ItemLookUp.aspx
응답 형식: XML, JSON (기본값: XML)
응답 결과: 검색 응답 결과값 스펙에 부가 정보가 추가된 형태

요청 샘플 (URL)

[http://www.aladin.co.kr/ttb/api/ItemLookUp.aspx?ttbkey=]
(http://www.aladin.co.kr/ttb/api/ItemLookUp.aspx?ttbkey=)
[TTBKey]&itemIdType=ISBN&ItemId=[도서의ISBN]
&output=xml&Version=20131101&OptResult=ebookList,usedList,reviewList

2. 상품 조회 API 요청(Request) 파라미터

구분	요청변수	변수종류	필수여부	설명
필수	TTBKey	문자열	Y	알라딘에서 부여받은 TTBKey 값
	ItemId	문자열/숫자	Y	상품을 구분 짓는 유일한 값 (ItemIdType에 따라 ISBN 또는 알라딘 고유 ID 입력)
옵션	ItemIdType	문자열	N	`ISBN`: ISBN 10자리 (기본값) `ISBN13`: ISBN 13자리 (권장) `ItemId`: 알라딘 고유의 상품 ID
	Cover	문자열	N	표지 크기 선택 - `Big`: 큰 크기 - `MidBig`: 중간 큰 크기 - `Mid`: 중간 크기 (기본값) - `Small`: 작은 크기 - `Mini`: 매우 작은 크기 - `None`: 없음
	Output	문자열	N	출력 방법 선택 - `XML`: REST XML 형식 (기본값) - `JS`: JSON 방식
	Partner	문자열	N	제휴사 파트너 코드 (제휴사 유효성 체크용)
	Version	정수형 날짜	N	검색 API 버전 설정 - 기본값: `20070901` - 최신버전: `20131101`
	includeKey	양의 정수	N	`1`인 경우 결과 내 상품 링크에 TTBKey 포함 (기본값: `0`)
	offCode	문자열	N	중고상품 보유 매장 검색 API에서 얻은 중고매장 코드
	OptResult	문자열	N	부가 정보 요청 (Array 형태, 쉼표로 구분) 예: `OptResult=ebookList,usedList,reviewList`

3. OptResult 상세 옵션 (상품 조회 전용)

OptResult 파라미터에 포함하여 더 상세한 정보를 받아올 수 있는 항목들입니다.

ebookList: 해당 종이책의 전자책 정보
usedList: 해당 상품에 등록된 중고상품 정보
fileFormatList: 전자책의 포맷 및 용량
c2binfo: 중고 C2B(알라딘 매입) 여부 및 매입가 조회
packing: 판형 정보, 포장 관련 정보
b2bSupply: 전자책 B2B 납품 가능 여부
subbarcode: 부가기호
cardReviewImgList: 카드리뷰 일부 이미지 경로
ratingInfo: 상품 별점 평점, 100자평 개수, 마이리뷰 개수
bestSellerRank: 상품의 주간 베스트셀러 순위
previewImgList: 미리보기 이미지 경로 (추가 요청 시 제공 가능)
eventList: 관련 이벤트 정보 (추가 요청 시 제공 가능)
authors: 저자/아티스트 상세 정보 목록 (추가 요청 시 제공 가능)
reviewList: 상품에 등록된 리뷰 목록 (추가 요청 시 제공 가능)
fulldescription: 상품 설명 및 출판사 소개 (DVD는 줄거리 포함)
fulldescription2: 출판사(제작사) 제공 상품 상세 소개
Toc: 상품의 목차 (추가 요청 시 제공 가능)
Story: 줄거리 (추가 요청 시 제공 가능)
categoryIdList: 전체 분야 카테고리 목록 (추가 요청 시 제공 가능)
mdrecommend: 편집장의 선택 (추가 요청 시 제공 가능)
phraseList: 책속에서 (최대 3개 노출, 추가 요청 시 제공 가능)

응답 (Response)

본 명세서는 알라딘의 상품 검색, 리스트 조회, 상품 상세 조회 API의 결과를 통합한 것입니다. 상품 조회 API의 경우 OptResult 파라미터 설정에 따라 더 상세한 부가정보(item 및 subInfo 하위 항목)가 포함됩니다.

1. 공통 응답 필드 (Root Level)

결과 전체에 대한 요약 및 메타데이터입니다.

필드명	설명	자료형
`version`	API 버전 (정수형 날짜)	정수
`title`	API 결과의 제목	문자열
`link`	관련 알라딘 페이지 URL	문자열(URL)
`pubDate`	API 출력일	문자형 날짜
`totalResults`	총 검색 결과 수	정수
`startIndex`	시작 페이지 (Page수)	정수
`itemsPerPage`	한 페이지당 출력 상품 수	정수
`query`	조회에 사용된 쿼리	문자열
`searchCategoryId`	분야 조회 시 해당 분야 ID	정수
`searchCategoryName`	분야 조회 시 해당 분야명	문자열

2. 상품 정보 (item)

개별 상품의 기본 정보입니다. (※ 표시는 상품 조회 API 전용/협의 항목)

필드명	설명	자료형
`title`	상품명	문자열
`link`	상품 상세 페이지 링크	문자열(URL)
`author`	저자 / 아티스트	문자열
`pubDate`	출간일 / 출시일	날짜
`description`	상품 설명 (요약)	문자열
`isbn`	ISBN 10자리	문자열
`isbn13`	ISBN 13자리	문자열
`priceSales`	판매가	정수
`priceStandard`	정가	정수
`mallType`	몰 타입 (BOOK, MUSIC, DVD, FOREIGN, EBOOK, USED)	문자열
`stockStatus`	재고 상태 (품절, 절판 등 / 정상 시 공백)	문자열
`mileage`	마일리지 적립액	정수
`cover`	표지 이미지 URL	문자열(URL)
`publisher`	출판사 / 제작사	문자열
`salesPoint`	판매지수	정수
`adult`	성인 등급 여부 (true/false)	Boolean
`customerReviewRank`	회원 리뷰 평점 (0~10점)	정수
`bestRank`	베스트셀러 순위 (베스트셀러 조회 시)	정수
`fullDescription` ※	상품 상세 설명 (책소개)	문자열
`fullDescription2`※	출판사 제공 상품 소개	문자열
`categoryIdList` ※	전체 분야 정보 (categoryId, categoryName 포함 리스트)	리스트
`seriesInfo`	시리즈 정보 (seriesId, seriesName, seriesLink)	객체

3. 부가 정보 (subInfo)

subInfo 노드 하위에 포함되는 상세 데이터들입니다.

3-1. 서지 및 콘텐츠 정보

필드명	설명	자료형
`subTitle`	부제	문자열
`originalTitle`	원제	문자열
`itemPage`	상품 쪽수	숫자
`toc`	목차	문자열
`story`	줄거리 (도서/DVD)	문자열
`taxFree`	비과세 여부 (true 시 비과세)	Boolean
`subbarcode`	부가기호	문자열

3-2. 평점 및 리뷰 (ratingInfo / reviewList)

필드명	설명	자료형
`ratingInfo`	평점 정보 (ratingScore, ratingCount, commentReviewCount, myReviewCount)	객체
`reviewList`	리뷰 목록 (reviewRank, writer, title, link)	리스트

3-3. 작가 상세 정보 (authors)

필드명	설명	자료형
`authorId`	작가 고유 ID	정수
`authorName`	작가명	문자열

박정빈

다음 포스트

[통합] 알라딘 API 총정리

알라딘 API

요청 (Request)

1. 알라딘 상품 검색 API 명세서 (ItemSearch API)

1. 기본 정보

요청 샘플 (URL)

2. 상품 검색 API 요청(Request) 파라미터

3. OptResult 상세 옵션 (상품 검색 전용)

2. 알라딘 상품 리스트 API 명세서 (ItemList API)

1. 기본 정보

요청 샘플 (URL)

2. 상품 리스트 API 요청(Request) 파라미터

3. OptResult 상세 옵션 (상품 리스트 전용)

3. 알라딘 상품 조회 API 명세서 (ItemLookUp API)

1. 기본 정보

요청 샘플 (URL)

2. 상품 조회 API 요청(Request) 파라미터

3. OptResult 상세 옵션 (상품 조회 전용)

응답 (Response)

1. 공통 응답 필드 (Root Level)

2. 상품 정보 (item)

3. 부가 정보 (subInfo)

3-1. 서지 및 콘텐츠 정보

3-2. 평점 및 리뷰 (ratingInfo / reviewList)

3-3. 작가 상세 정보 (authors)

[요청] 상품 검색 API 명세서

0개의 댓글