Taobao 검색 API

Q: 다음 페이지 결과도 가져올 수 있나요?

네, page를 사용하면 됩니다. 1~50페이지까지 페이지당 결과 20개이며, 각 페이지는 호출 1회로 과금됩니다. 생략하면 1페이지입니다. 페이지네이션은 단순 키워드 검색에서만 동작합니다. 즉 min_price, max_price, tmall_only를 사용하지 않고 sort를 생략하거나 relevance로 설정해야 합니다. 이 방식이 더 안정적이지만, 대부분의 행에 판매량이나 상점명이 없습니다. 가격 범위를 지정하거나 sort=popular를 사용한 검색은 판매량이 포함될 수 있지만, 결과가 최대 10개 또는 20개이고 페이지를 넘길 수 없습니다. 따라서 이런 검색에서 1보다 큰 page를 보내면 과금 전에 거부됩니다. 순위는 실시간으로 바뀌므로 인접한 페이지에 일부 항목이 가끔 중복될 수 있습니다. 페이지를 합칠 때는 id로 중복을 제거하십시오.

Q: sort는 어떤 정렬 순서를 지원하나요?

relevance(기본값), popular, 그리고 가장 비싼 상품부터 보여 주는 price_desc를 지원합니다. 현재 낮은 가격순 정렬은 없습니다. 인기순이나 가격순으로 정렬하면 호출당 결과가 최대 10개이고 페이지를 넘길 수 없습니다. 더 많은 결과가 필요하면 sort 없이 단순 키워드 검색을 실행하고 page로 페이지를 넘기십시오.

Q: 가격 필터는 어떻게 동작하나요?

min_price와 max_price는 상품 가격의 범위를 지정하며, 둘 중 하나만 전달해도 됩니다. 이 필터는 상품 검색에만 적용되며 평점이나 호출 비용에는 적용되지 않습니다. price는 통화 기호 없이 반환되므로 통화는 currency에서 확인하십시오.

POST

API 상태

24시간 상태: 98%
24시간 평균 소요 시간: 10.54 s

양호 / 정상
사용 가능
제한적
대부분 작동 중단

양호

최근 24시간

최근 30일

키워드로 Taobao와 Tmall 상품 정보를 검색합니다. 가격과 발송지, 그리고 제공되는 경우 판매량, 평점, 상점, 쿠폰 또는 할인 정보를 받을 수 있습니다. 일반 키워드 검색이 가장 안정적이며 page로 페이지당 20개씩 넘길 수 있지만, 대부분의 행에 판매량과 상점 이름이 없습니다. 가격 범위, popular, price_desc, tmall_only는 페이지를 넘길 수 없으며, 이 중 뒤의 세 가지는 요청당 결과가 10개로 제한됩니다. 재고, 정품 여부, 배송은 확인되지 않습니다.

Taobao 검색은 keyword로 Taobao와 Tmall의 상품 정보를 찾아 각 상품의 제목, 가격과 통화, 판매량, 평점, 출고지, 상점명, 대표 이미지, 재고를 반환합니다. 카테고리에서 무엇이 어떤 가격에 팔리는지 파악할 때 사용하며, 상품 리서치, 경쟁사 가격 추적, 카테고리 분석에 활용할 수 있습니다.

min_price와 max_price로 가격 범위를 좁히고, sort(관련도, 인기순, 높은 가격순)로 정렬하고, tmall_only로 Tmall 상품 정보만 남길 수 있습니다. tmall_only에는 불리언 true 또는 false를 넣어야 하며, 문자열을 넣으면 과금 전에 거부됩니다. 플랫폼마다 평점 최댓값이 다르므로 rating 값을 비교하기 전에 같은 행의 rating_scale을 확인하십시오.

요금은 요청 1,000개당 $13.5(호출당 $0.0135)입니다. 실패한 호출과 빈 결과에는 과금하지 않습니다. 동기 방식입니다. 오래 걸리는 작업은 요청 본문에 "mode": "async"를 추가하고 job_id를 받아 폴링하세요.

AI 프롬프트

EveryInfra Taobao 검색 엔드포인트(taobao/search)를 사용하는 데이터 수집 스크립트 작성을 도와주세요.

엔드포인트 사용 방법:
- 요청: Authorization: Bearer <API 키> 헤더와 함께 POST https://api.everyinfra.com/api/v1/social로 보냅니다. 키는 EVERYINFRA_API_KEY 환경 변수에서 읽고, 절대 하드코딩하지 마세요.
- 요청 본문에서 platform은 taobao, action은 search로 설정하고, 파라미터는 params 안에 넣습니다.
- 필수 파라미터:
- keyword: search 액션에서 사용할 Taobao 또는 Tmall 상품 검색어를 지정합니다. 스토어 이름으로 정확히 일치하는 검색은 수행하지 않습니다.
- 선택 파라미터:
- max_price: min_price와 함께 search 액션의 최대 상품 가격 필터를 설정합니다. SKU 재고 한도를 제어하지 않습니다. 소수 값은 정수로 올림될 수 있습니다. 가격 범위를 지정한 검색은 페이지네이션을 지원하지 않습니다.
- min_price: search 액션의 최소 상품 가격 필터를 설정합니다. 리뷰 점수 필터나 API 요금 파라미터가 아니며, shop, product_detail, reviews, questions에는 적용되지 않습니다. 소수 값은 정수로 내림될 수 있습니다. 가격 범위를 지정한 검색은 페이지네이션을 지원하지 않습니다.
- page: 상품 검색의 페이지 번호로, 1~50 사이 값이며 페이지당 결과는 20개입니다. 1페이지는 생략하면 되며, 각 페이지는 API 호출 1회로 과금됩니다. 단순 키워드 검색만 페이지네이션을 지원합니다(min_price, max_price, tmall_only 없이, sort는 생략하거나 relevance).
- sort: 상품 검색에는 relevance(기본값), popular, price_desc를 사용합니다. 기본값과 relevance 검색은 최대 20개 결과를 받을 수 있고, popular와 price_desc는 최대 10개이며 페이지네이션을 지원하지 않습니다. 해당 한도를 초과하는 요청은 과금 전에 거부되며, price_asc는 지원하지 않습니다. (허용 값: popular / price_desc / relevance)
- tmall_only: boolean true로 설정하면 상품 검색을 Tmall 상품으로만 필터링하며, 요청 결과는 최대 10개로 제한되고 페이지를 넘길 수 없습니다. JSON boolean만 전달하세요. "false" 같은 문자열이나 이 한도를 초과하는 요청은 과금 전에 거부됩니다.
- limit: 이 호출에서 반환할 최대 행 수로, 1~20 사이의 정수입니다. 생략하면 기본값이 적용되며, 실제 반환되는 행은 이보다 적을 수 있습니다. 더 큰 값을 지정하면 과금 전에 422를 반환합니다. (기본값: 20)
- 레코드 목록을 반환합니다. 각 레코드의 주요 필드: id, url, title, price (통화 기호 없는 숫자 가격이며, currency를 참고하세요), currency, sold_count (판매 수량입니다), rating, rating_scale, location, shop_name (상점 이름입니다), image_url, stock (재고입니다); 전체 필드 41개, 전체 목록은 https://api.everyinfra.com/api/v1/social/catalog?platform=taobao.
- 요청 본문 예시:
{
"platform": "taobao",
"action": "search",
"params": {
"keyword": "便携咖啡秤"
}
}
- 요금: 요청 1,000개당 $13.5. 실패하거나 빈 결과에는 과금하지 않습니다.
- 대상이 수십~수백 개라면 요청 본문에 "mode": "async"를 추가하세요. job_id를 즉시 받은 뒤 GET https://api.everyinfra.com/api/v1/jobs/{job_id}를 폴링해 결과를 가져옵니다.
- 422가 반환되면 오류에 제시된 파라미터 이름과 허용 값을 참고해 요청을 수정하고, 429 또는 503이 반환되면 Retry-After만큼 기다린 뒤 다시 시도합니다.

코드를 작성하기 전에 필요한 대상과 수량, 필드, 원하는 출력 형식을 먼저 물어봐 주세요. 그런 다음 계획과 대략적인 비용을 저와 확인해 주세요.

요청 파라미터

이름	위치	타입	필수	기본값	설명
`Authorization`	header	`string`	예	-	Bearer 뒤에 API 키를 붙여 입력합니다. API 키는 콘솔에서 생성하며, URL이나 코드 저장소에 절대 넣지 마세요.
`platform`	body	`string`	예	`taobao`	플랫폼 식별자이며 고정값입니다.
`action`	body	`string`	예	`search`	기능 식별자이며 고정값입니다.
`keyword`	body.params	`string`	예	-	search 액션에서 사용할 Taobao 또는 Tmall 상품 검색어를 지정합니다. 스토어 이름으로 정확히 일치하는 검색은 수행하지 않습니다.
`max_price`	body.params	`number`	아니요	-	min_price와 함께 search 액션의 최대 상품 가격 필터를 설정합니다. SKU 재고 한도를 제어하지 않습니다. 소수 값은 정수로 올림될 수 있습니다. 가격 범위를 지정한 검색은 페이지네이션을 지원하지 않습니다.
`min_price`	body.params	`number`	아니요	-	search 액션의 최소 상품 가격 필터를 설정합니다. 리뷰 점수 필터나 API 요금 파라미터가 아니며, shop, product_detail, reviews, questions에는 적용되지 않습니다. 소수 값은 정수로 내림될 수 있습니다. 가격 범위를 지정한 검색은 페이지네이션을 지원하지 않습니다.
`page`	body.params	`integer`	아니요	-	상품 검색의 페이지 번호로, 1~50 사이 값이며 페이지당 결과는 20개입니다. 1페이지는 생략하면 되며, 각 페이지는 API 호출 1회로 과금됩니다. 단순 키워드 검색만 페이지네이션을 지원합니다(min_price, max_price, tmall_only 없이, sort는 생략하거나 relevance). 이 방식이 더 안정적인 검색 방법이지만, 대부분의 행에는 판매량이나 상점 이름이 없습니다. 이 필터 중 하나와 함께 1보다 큰 페이지를 요청하면 과금 전에 거부되므로, 페이지네이션하려면 해당 필터를 제거하세요. limit은 해당 페이지에서 받을 결과 수만 지정하므로 페이지네이션 시에는 20으로 유지하세요. 순위가 실시간으로 바뀌므로 인접한 페이지에 일부 항목이 중복될 수 있습니다. 페이지를 합칠 때는 id로 중복을 제거하세요.
`sort`	body.params	`string (enum)`	아니요	-	상품 검색에는 relevance(기본값), popular, price_desc를 사용합니다. 기본값과 relevance 검색은 최대 20개 결과를 받을 수 있고, popular와 price_desc는 최대 10개이며 페이지네이션을 지원하지 않습니다. 해당 한도를 초과하는 요청은 과금 전에 거부되며, price_asc는 지원하지 않습니다. reviews와 questions는 sort를 받지 않습니다. shop은 오류 없이 받지만 현재는 효과가 없습니다.허용 값`popularprice_descrelevance`
`tmall_only`	body.params	`boolean`	아니요	-	boolean true로 설정하면 상품 검색을 Tmall 상품으로만 필터링하며, 요청 결과는 최대 10개로 제한되고 페이지를 넘길 수 없습니다. JSON boolean만 전달하세요. "false" 같은 문자열이나 이 한도를 초과하는 요청은 과금 전에 거부됩니다.
`limit`	body.params	`integer (1–20)`	아니요	`20`	이 호출에서 반환할 최대 행 수로, 1~20 사이의 정수입니다. 생략하면 기본값이 적용되며, 실제 반환되는 행은 이보다 적을 수 있습니다. 더 큰 값을 지정하면 과금 전에 422를 반환합니다.

코드 샘플

bash

curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "taobao",
  "action": "search",
  "params": {
    "keyword": "便携咖啡秤"
  }
}'

OpenAPI 정의(JSON)샘플 코드는 EVERYINFRA_API_KEY 환경 변수에서 키를 읽으므로, 복사한 코드에는 API 키가 포함되지 않습니다.

응답 예시

실제 응답

October 24, 2026 at 18:28(UTC)에 위 코드 샘플의 파라미터로 이 API를 호출해 수집한 응답입니다. results와 count는 해당 호출의 실제 응답이며, 개인정보(이름, 핸들, 아바타, 프로필 링크, 연락처)는 제거했습니다(목록은 처음 2개만 표시). id, billing, quota는 호출할 때마다 달라지므로 형태만 표시합니다.

json

{
  "id": "req_…",
  "platform": "taobao",
  "action": "search",
  "results": [
    {
      "id": "•••",
      "url": "https://item.taobao.com/item.htm?id=1036557039587",
      "title": "手冲电子称豆盘咖啡称重展示盘咖啡豆粉秤豆碟茶叶茶则茶器便携",
      "price": 59.8,
      "currency": "CNY",
      "location": "浙江 杭州",
      "shop_name": "好货严选工厂",
      "image_url": "https://g.search.alicdn.com/img/bao/uploaded/i4/i2/2206584264218/O1CN01sCMEZhb10YE1chua_!!2206584264218-0-C2M.jpg",
      "stock": 438,
      "shop_id": "2206584264218",
      "sold_text": "1000+",
      "original_price": 59.8,
      "discount_type": "特价秒杀",
      "seller_credit_level": 20,
      "seller_positive_rate": 100,
      "shop_score_description": 4.74,
      "shop_score_service": 4.8,
      "shop_score_delivery": 4.82,
      "subtitle": "",
      "search_rank": 1,
      "images": [
        "https://img.alicdn.com/imgextra/i4/3937219703/O1CN01VRbcrW2LY2B5R9Jq9_!!3937219703-0-C2M.jpg",
        "https://img.alicdn.com/imgextra/i3/3937219703/O1CN01Bs0puN2LY2B58j8Nm_!!3937219703-0-C2M.jpg",
        "https://img.alicdn.com/imgextra/i4/3937219703/O1CN010vTDpb2LY2B5NXjqG_!!3937219703-0-C2M.jpg"
      ],
      "discount_rate": 100,
      "spu_id": "8995243647",
      "platform": "taobao"
    },
    {
      "id": "•••",
      "url": "https://item.taobao.com/item.htm?id=803310769271",
      "title": "Bincoo咖啡电子秤意式专用咖啡豆称重智能手冲迷你便携秤咖啡器具",
      "price": 88,
      "currency": "CNY",
      "shop_name": "bincoo旗舰店",
      "image_url": "https://g.search1.alicdn.com/img/bao/uploaded/i4/i3/4249388314/O1CN013agzRw2BHrr0rcgBA_!!0-item_pic.jpg",
      "stock": 1267,
      "shop_id": "4249388314",
      "sold_text": "1000+",
      "original_price": 128,
      "discount_type": "优惠价",
      "seller_credit_level": 16,
      "seller_positive_rate": 100,
      "shop_score_description": 4.9,
      "shop_score_service": 4.92,
      "shop_score_delivery": 4.93,
      "subtitle": "",
      "search_rank": 2,
      "images": [
        "https://img.alicdn.com/imgextra/i1/4249388314/O1CN01ZKqJQV2BHrqxP8GFJ_!!4249388314.jpg",
        "https://img.alicdn.com/imgextra/i2/4249388314/O1CN01tX38az2BHrqz5tjuQ_!!4249388314.jpg",
        "https://img.alicdn.com/imgextra/i1/4249388314/O1CN01Jddc8c2BHrqyzT1fk_!!4249388314.jpg"
      ],
      "discount_rate": 68.75,
      "spu_id": "7410827142",
      "platform": "taobao"
    }
  ],
  "count": 10,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}

응답 필드

비즈니스 데이터는 results에 담깁니다. 아래 표는 레코드에 포함될 수 있는 필드를 나열하며, 플랫폼에 표시되지 않는 값을 임의로 만들어 넣지 않습니다.

필드	의미
`id`	플랫폼에서 레코드의 고유 ID입니다. 한 플랫폼 안에서만 고유하며, 플랫폼이 다르면 ID가 중복될 수 있습니다.
`url`	플랫폼에서 해당 레코드로 연결되는 링크입니다.
`title`	제목입니다. 플랫폼에 제목이 없으면 null입니다(예: 텍스트 전용 게시물).
`price`	통화 기호 없는 숫자 가격이며, currency를 참고하세요. product_detail에서는 가격(각 skus 행의 price 포함)이 대부분 미국 달러에서 환산된 값이라 Taobao 페이지 가격과 약 1–4% 차이가 날 수 있습니다. 기준은 페이지 가격입니다.
`currency`	가격의 통화 코드입니다(예: CNY, USD). price는 있는데 currency가 null이면 통화를 추정하지 마세요.
`sold_count`	판매 수량입니다.
`rating`	평점입니다. 척도는 플랫폼마다 다릅니다. 같은 행의 rating_scale이 최댓값을 나타냅니다(보통 5이며, Booking, Douban, iQIYI, NAVER는 10). 플랫폼 간에 비교하기 전에 rating_scale로 환산하세요. 그렇지 않으면 비교 결과가 뒤바뀔 수 있습니다.
`rating_scale`	같은 행에 있는 rating의 최댓값입니다. 5점 척도는 5, 10점 척도는 10입니다. 행에 rating이 있을 때만 포함됩니다.
`location`	위치 설명을 그대로 전달하며, 형식은 플랫폼마다 다릅니다.
`shop_name`	상점 이름입니다.
`image_url`	이미지 링크입니다. 이미지가 여러 개인 기능은 image_urls 배열을 반환할 수 있습니다.
`stock`	재고입니다.
`shop_id`	상점 ID입니다.
`sold_text`	표시된 판매량으로, 예를 들면 100k+입니다(search). + 또는 10k 단위가 붙은 수치는 반올림된 표시이며 정확한 판매량이 아닙니다.
`original_price`	원래 가격(취소선 가격)입니다. shop에서는 유일한 가격으로, 상품 정보에 표시된 취소선 가격이지 판매 가격이 아니며 판매 가격보다 훨씬 높을 수 있습니다. 판매 가격은 product_detail을 사용하세요.
`coupon_price`	쿠폰 적용 후 가격입니다. 쿠폰이 적용되면 price보다 낮고, 그렇지 않으면 포함되지 않습니다.
`discount_type`	표기 그대로의 할인 또는 캠페인 유형입니다(예: 타임 세일).
`is_tmall`	상점이 일반 Taobao 상점이 아니라 Tmall 상점인지 여부입니다. 두 유형은 입점 요건과 구매자 보장이 다릅니다.
`brand`	브랜드입니다.
`category_id`	카테고리 ID입니다.
`seller_credit_level`	판매자 신용 등급입니다(숫자이며 높을수록 좋음).
`seller_positive_rate`	판매자 긍정 평가 비율로, 백분율 값입니다(search). 100은 100%를 의미합니다.
`shop_score_description`	상품 설명 일치도에 대한 상점 평점(5점 만점)입니다.
`shop_score_service`	서비스에 대한 상점 평점(5점 만점)입니다.
`shop_score_delivery`	배송에 대한 상점 평점(5점 만점)입니다.
`subtitle`	상품 부제목으로, 짧은 셀링 포인트 문구입니다(search).
`search_rank`	이 검색 결과 내 순위로, 1부터 시작합니다(search). 페이지를 넘겨도 이어서 세므로 3페이지는 41부터 시작합니다.
`free_shipping`	무료 배송 여부입니다.
`selling_points`	셀링 포인트 태그입니다.
`review_tags`	리뷰 태그입니다. 각 항목에는 tag(라벨)와 count(언급 횟수, 없을 수 있음)가 있습니다.
`images`	이미지 링크입니다. product_detail에서는 상품 사진, reviews에서는 구매자가 올린 사진입니다(리뷰에 사진이 없으면 생략됩니다).
`discount_rate`	플랫폼 자체의 의미를 따름
`spu_id`	플랫폼 자체의 의미를 따름
`category_path`	카테고리 경로(브레드크럼)입니다.
`review_count`	리뷰 수로, 상품 및 업체 관련 기능에 해당합니다. null은 비공개라는 뜻이며, 0이 아닙니다.
`latest_review`	플랫폼 자체의 의미를 따름
`seller_type`	판매자 유형 코드입니다(product_detail).
`shop_opened_at`	표기 그대로의 상점 개설 시점입니다(product_detail).
`shop_age_years`	플랫폼 자체의 의미를 따름
`shop_item_count`	상점에서 판매 중인 상품 수입니다(product_detail, search, shop).
`shop_score_vs_industry`	플랫폼 자체의 의미를 따름
`platform`	출처 플랫폼 식별자로, 요청의 platform과 같습니다(예: xiaohongshu, tiktok).

FAQ

다음 페이지 결과도 가져올 수 있나요?

네, page를 사용하면 됩니다. 1~50페이지까지 페이지당 결과 20개이며, 각 페이지는 호출 1회로 과금됩니다. 생략하면 1페이지입니다. 페이지네이션은 단순 키워드 검색에서만 동작합니다. 즉 min_price, max_price, tmall_only를 사용하지 않고 sort를 생략하거나 relevance로 설정해야 합니다. 이 방식이 더 안정적이지만, 대부분의 행에 판매량이나 상점명이 없습니다. 가격 범위를 지정하거나 sort=popular를 사용한 검색은 판매량이 포함될 수 있지만, 결과가 최대 10개 또는 20개이고 페이지를 넘길 수 없습니다. 따라서 이런 검색에서 1보다 큰 page를 보내면 과금 전에 거부됩니다. 순위는 실시간으로 바뀌므로 인접한 페이지에 일부 항목이 가끔 중복될 수 있습니다. 페이지를 합칠 때는 id로 중복을 제거하십시오.

`sort`는 어떤 정렬 순서를 지원하나요?

relevance(기본값), popular, 그리고 가장 비싼 상품부터 보여 주는 price_desc를 지원합니다. 현재 낮은 가격순 정렬은 없습니다. 인기순이나 가격순으로 정렬하면 호출당 결과가 최대 10개이고 페이지를 넘길 수 없습니다. 더 많은 결과가 필요하면 sort 없이 단순 키워드 검색을 실행하고 page로 페이지를 넘기십시오.

가격 필터는 어떻게 동작하나요?

min_price와 max_price는 상품 가격의 범위를 지정하며, 둘 중 하나만 전달해도 됩니다. 이 필터는 상품 검색에만 적용되며 평점이나 호출 비용에는 적용되지 않습니다. price는 통화 기호 없이 반환되므로 통화는 currency에서 확인하십시오.

오류 및 과금

401: 키가 없거나 유효하지 않습니다.
402: 잔액이 부족합니다. 먼저 충전하세요.
422: 파라미터 이름 또는 값이 올바르지 않습니다. 오류에 제시된 제안을 참고해 수정하세요. 과금되지 않습니다.
429: 분당 요청 속도 제한에 도달했습니다. Retry-After만큼 기다린 뒤 다시 시도하세요.
503: 처리를 완료하지 못했습니다. 보류된 금액은 잔액으로 반환됩니다. 결과가 불확실하면 재시도하기 전에 먼저 확인하세요.
200 빈 결과: 데이터가 없습니다. 과금되지 않습니다.

오류