상품 검색

검색어로 상품 목록을 페이지 단위로 조회합니다. 검색 카테고리, 정렬 방식, 상세 정보 포함 여부를 지정할 수 있습니다.

개요

상품 검색 API는 검색어로 상품 목록을 페이지 단위로 조회합니다. 검색 카테고리, 정렬 방식, 상세 정보 포함 여부를 지정할 수 있습니다.

검색어 자동 교정

입력한 검색어로 결과가 없는 경우, 검색 엔진이 검색어를 자동으로 교정(맞춤법 수정·유사어 치환 등)하여 결과를 반환할 수 있습니다. 이 경우 응답 데이터는 요청한 검색어가 아닌 교정된 검색어 기준입니다.

베루나르 베르베르 검색 결과 없음
베르나르 베르베르 교정된 검색어 기준으로 결과 반환

Endpoint

GET https://apis.yes24.com/v1/goods/itemList

Query Parameters

파라미터타입필수기본값설명
query string 필수 - 검색어
category string 선택 ALL 검색 카테고리(ALL, BOOK, FOREIGN, EBOOK, MUSIC, DVD). 전시 카테고리 코드(숫자)는 사용 불가
sort string 선택 DEFAULT 정렬 방식(DEFAULT, RELATION, RECENT, REG_DTS)
page integer 선택 1 페이지 번호
pageSize integer 선택 20 페이지 크기(최대 100)
detail string 선택 N 상세 정보 포함 여부(Y 또는 N)

Request Example

Shell
curl -X GET "https://apis.yes24.com/v1/goods/itemList?query=클린코드&pageSize=20" -H "X-Api-Key: yk_live_YOUR_API_KEY"

Response Example

GoodsSimpleInfo — 기본 필드만 반환합니다.
JSON
{
  "success": true,
  "message": "성공",
  "errorCode": null,
  "data": {
    "meta": {
      "apiTitle": "상품 검색",
      "apiLink": "https://apis.yes24.com/v1/goods/itemList?query=클린코드&pageSize=20",
      "logoUrl": "https://image.yes24.com/sysimage/apis/openapi/images/logoN4.svg",
      "pubDate": "2026-07-14T09:16:14+09:00",
      "query": "?query=클린코드&pageSize=20",
      "version": "v1"
    },
    "items": [
      {
        "sortOrder": 1,
        "itemId": 12345678,
        "title": "클린 코드",
        "author": "로버트 C. 마틴",
        "goodsType": "국내도서",
        "goodsSortNm": "국내도서",
        "adultYn": "N",
        "publisher": "인사이트",
        "isbn10": "8966260950",
        "isbn13": "9788966260959",
        "shopPrice": 33000,
        "salePrice": 29700,
        "publishDate": "2013-12-24",
        "itemStatus": "판매중",
        "cover": "https://image.yes24.com/goods/12345678/L",
        "link": "https://www.yes24.com/product/goods/12345678",
        "addOnLink": "",
        "upDown": null,
        "contentDetail": {
          "bookIntroduction": "소프트웨어 장인 정신을 담은 도서입니다. 깨끗한 코드를 작성하는 방법을 알려줍니다.",
          "bookSummary": null,
          "tableOfContents": "1장 깨끗한 코드\n2장 의미 있는 이름\n3장 함수\n..."
        }
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "totalCount": 100
  }
}

Response Fields

detail 파라미터 값에 따라 반환 필드가 달라집니다. N+Y 공통   Y only detail=Y 전용
필드 타입 N Y 설명
success boolean ✓ ✓ 요청 성공 여부
message string ✓ ✓ 응답 메시지
errorCode string | null ✓ ✓ 오류 코드(성공 시 null)
data.meta.apiTitle string ✓ ✓ 호출한 API 제목
data.meta.apiLink string ✓ ✓ 요청 URL
data.meta.logoUrl string ✓ ✓ 예스24 로고 URL
data.meta.pubDate string ✓ ✓ 응답 일시(ISO 8601)
data.meta.query string ✓ ✓ 요청 QueryString
data.meta.version string ✓ ✓ API 버전
data.items array ✓ ✓ 상품 목록
data.currentPage integer ✓ ✓ 현재 페이지 번호
data.pageSize integer ✓ ✓ 페이지 크기
data.totalCount integer ✓ ✓ 전체 데이터 수
data.items[].sortOrder integer ✓ ✓ 목록 내 순서
data.items[].itemId integer ✓ ✓ 예스24 상품 번호
data.items[].title string ✓ ✓ 상품 제목
data.items[].author string ✓ ✓ 저자 또는 아티스트명
data.items[].goodsType string ✓ ✓ 상품 유형
data.items[].goodsSortNm string ✓ ✓ 관리 분류
data.items[].adultYn string ✓ ✓ 성인물 여부(Y/N)
data.items[].publisher string ✓ ✓ 출판사
data.items[].isbn10 string ✓ ✓ ISBN10
data.items[].isbn13 string ✓ ✓ ISBN13
data.items[].shopPrice decimal ✓ ✓ 정가
data.items[].salePrice decimal ✓ ✓ 판매가
data.items[].publishDate string ✓ ✓ 출간일
data.items[].itemStatus string ✓ ✓ 판매 상태
data.items[].cover string ✓ ✓ 커버 이미지 URL
data.items[].link string ✓ ✓ 예스24 원본 상품 상세 URL
data.items[].addOnLink string ✓ ✓ 애드온 클릭 URL. 애드온 미신청 상태에서는 공란
data.items[].upDown integer? ✓ ✓ 베스트셀러 등락 값(null 가능)
data.items[].contentDetail object? ✓ ✓ 상품 소개/요약/목차
data.items[].contentDetail.bookIntroduction string? ✓ ✓ 책 소개
data.items[].contentDetail.bookSummary string? ✓ ✓ 줄거리
data.items[].contentDetail.tableOfContents string? ✓ ✓ 목차
data.items[].subTitle string - ✓ 부제목
data.items[].originalTitle string? - ✓ 원제
data.items[].originalTranslation string? - ✓ 번역서 여부
data.items[].yesPoint integer? - ✓ YES 포인트
data.items[].salePoint integer? - ✓ 판매지수
data.items[].fixedBookPriceYn string - ✓ 도서정가제 여부(Y/N)
data.items[].pages integer? - ✓ 페이지 수
data.items[].weight integer? - ✓ 무게(g)
data.items[].width integer? - ✓ 가로(mm)
data.items[].length integer? - ✓ 세로(mm)
data.items[].height integer? - ✓ 높이(mm)
data.items[].itemFormat string? - ✓ 판형
data.items[].starScore double - ✓ 리뷰 평점
data.items[].mobileLink string - ✓ 모바일 상품 링크
data.items[].eBookLink string? - ✓ 연결된 eBook 링크(없으면 null)
data.items[].ebookId integer? - ✓ 연결된 eBook 상품번호(없으면 null)
data.items[].series array - ✓ 시리즈 목록
data.items[].series[].seriesId integer - ✓ 시리즈 번호
data.items[].series[].seriesName string - ✓ 시리즈명

오류 코드

HTTP오류 코드설명
401 AUTH_001 API Key 값이 없습니다.
401 AUTH_002 유효하지 않은 API Key입니다.
400 PARAM_003 query 파라미터를 입력하세요.
400 PARAM_005 유효하지 않은 sort 값입니다: '{sort}'. 사용 가능: DEFAULT, RELATION, RECENT, REG_DTS
400 PARAM_006 pageSize는 1에서 100 사이의 값이어야 합니다.
400 PARAM_008 category 값이 올바르지 않습니다. 사용 가능: ALL, BOOK, FOREIGN, EBOOK, MUSIC, DVD
404 SEARCH_001 검색 결과가 없습니다.
404 SEARCH_002 검색 결과를 제공할 수 없습니다.
503 UPSTREAM_UNAVAILABLE 외부 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도해주세요.