amazon/
best-sellers

공개된 Amazon 베스트셀러 URL에서 상품을 수집하여 제목, 판매자 정보, 가격, 공개된 평판 지표, 미디어를 정규화된 레코드로 반환합니다.

Amazon Best Sellers API

카테고리 URL 입력
상품 레코드
결과당 0.15 크레딧
결과당 0.15 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Amazon Best Sellers

Amazon 베스트셀러 페이지는 공개된 상품을 카테고리별 목록으로 보여 주며, 노출되는 경우 상품 제목, 판매자 정보, 가격, 평점, 리뷰 수, 판매 수, 미디어, 원본 링크, 관측 시각을 확인할 수 있습니다. SocQ는 선택한 목록 URL을 정규화된 상품 레코드로 변환하므로 카테고리 조사, 상품 구성 비교, 반복 가능한 커머스 데이터 워크플로에 활용할 수 있습니다.

Amazon Best Sellers API 주요 기능

  • 지역별 카테고리 URL 수집지원되는 Amazon 마켓플레이스의 공개 베스트셀러 또는 카테고리 목록 URL을 하나 이상 제출하면, 하나의 비동기 작업으로 한꺼번에 수집합니다.
  • 정규화된 상품 식별 정보확인 가능한 ID, 제목, 설명, 원본 URL, 플랫폼·리소스 라벨, 수집 타임스탬프를 담은 일관된 상품 레코드를 받습니다.
  • 커머스·평판 정보페이지 마크업을 파싱하지 않고도, 확인 가능한 판매자 정보, 가격, 평점, 리뷰 수, 판매 수를 명시적인 필드로 사용할 수 있습니다.
  • 바로 쓸 수 있는 미디어 포함 상품 레코드각 상품에 포함된 정규화된 미디어 객체를 카탈로그, 검수 큐, 보강 파이프라인, 후속 이미지 분석에 활용할 수 있습니다.

Amazon Best Sellers API 매개변수

매개변수필수설명
urls필수지원되는 마켓플레이스 호스트 또는 서브도메인의 Amazon 참조(URL) 목록으로, 필수 값입니다. 각 경로에는 /zgbs/ 또는 /gp/bestsellers/가 포함되어야 합니다. 호스트 이름을 파싱할 수 있는 모든 스킴과 프로토콜 상대 참조를 허용합니다.
results_limit선택1~2,000 범위의 정수이며 선택 항목입니다. 기본값은 100이고, 제출한 모든 URL에 걸쳐 저장되는 고유 상품 레코드의 총 개수를 제한합니다.

Amazon Best Sellers API 사용 방법

알고 있는 공개 베스트셀러 URL을 제출하고, 비동기 작업을 모니터링한 뒤, 정규화된 상품 레코드를 페이지 단위로 읽습니다.

  1. 지원되는 마켓플레이스 호스트의 공개 Amazon 베스트셀러 또는 카테고리 목록 URL을 하나 이상 준비합니다.
  2. urls와 1~2,000 범위의 선택 항목 results_limit을 /v1/amazon/best-sellers로 전송하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패를 반환할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽고, has_more가 true인 동안 next_cursor로 다음 결과를 요청합니다.
curl -X POST "https://api.socq.ai/v1/amazon/best-sellers" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.amazon.com/Best-Sellers-Books/zgbs/books"],"results_limit":3}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Amazon Best Sellers API 추천 활용 사례

  • 카테고리 상품 구성 스냅샷: 선택한 베스트셀러 페이지를 원본 링크와 수집 시각이 포함된, 범위가 정해진 상품 목록으로 만들어 조사용 데이터셋으로 활용합니다.
  • 가격·평판 비교: 페이지 마크업이 일정하지 않아도 후처리에서 스크래핑할 필요 없이, 반환된 상품의 가격, 평점, 리뷰 수, 판매 수를 비교합니다.
  • 상품 발굴 정보 보강: 카테고리 페이지에서 찾은 후보 목록에 제목, 판매자 정보, 설명, 미디어, 공개 상품 URL을 추가합니다.

Amazon Best Sellers API 활용 팁

  • 경로에 /zgbs/ 또는 /gp/bestsellers/가 포함된, 지원되는 지역별 Amazon 호스트의 URL을 사용하세요. 관련 없는 Amazon 경로는 작업 생성 전에 거부됩니다.
  • results_limit은 제출한 URL마다가 아니라 작업 전체에 적용되므로, 필요한 전체 배치 크기에 맞춰 설정하세요.
  • 작업 결과는 커서 기반 페이지네이션이 적용된 별도의 결과 뷰로 반환되므로, has_more가 false가 될 때까지 next_cursor를 따라가세요.
  • ID, 설명, 판매자 데이터, 가격, 평점, 수치, 미디어, URL, 게시 시각은 null일 수 있는 값으로 취급하고, 누락된 값을 0이나 빈 객체로 바꾸지 마세요.
  • 각 레코드와 함께 collected_at을 저장하고, 특정 시점 비교가 필요하면 실행을 따로 예약하세요. 이 엔드포인트는 연속 피드를 만들지 않습니다.

Amazon Best Sellers API 외에 Amazon의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Amazon Product Details API — 알고 있는 Amazon URL에서 상품 상세를 수집하며, 제목, 설명, 판매자, 가격, 평점, 리뷰 수, 판매량, 미디어 필드를 포함합니다.
  • Amazon Product Search API — 지원되는 Amazon 스토어에서 상품 검색어로 검색하고, 가져올 수 있는 경우 정규화된 상품, 판매자, 가격, 평점, 리뷰, 판매량, 미디어, 출처 필드를 반환합니다.
  • Amazon Reviews API — 지원되는 Amazon URL에서 공개 상품 리뷰를 수집하며, 본문, 평점, 작성자 정보, 상품 참조, 타임스탬프, 미디어를 포함합니다.
  • Amazon Seller Info API — 알고 있는 판매자 URL에서 공개 Amazon 판매자 프로필 정보, 소개, 웹사이트, 평점, 피드백, 위치, 출처, 수집 시각 필드를 수집합니다.
  • Amazon Storefront API — 스토어 URL로 아마존 크리에이터 스토어를 읽어 프로필, 연결된 SNS 계정, 상품 수가 포함된 아이디어 리스트, 큐레이션 게시물, 가격이 표시된 트렌딩 상품을 반환합니다.

다른 플랫폼 둘러보기

Amazon 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Amazon Best Sellers API — 자주 묻는 질문

Amazon Best Sellers API는 공개된 Amazon 베스트셀러 또는 카테고리 목록 URL에서 상품을 수집해 정규화된 SocQ 상품 레코드로 제공하는 프로그래밍 인터페이스입니다.

urls 배열은 파싱된 호스트 이름이 지원되는 Amazon 마켓플레이스 또는 서브도메인이고 경로에 /zgbs/ 또는 /gp/bestsellers/가 포함된 참조를 받습니다. 호스트 이름이 있는 모든 스킴과 프로토콜 상대 참조를 허용합니다.

안정적인 상품 응답에는 순위 필드가 포함되지 않습니다. 정규화된 레코드는 확인 가능한 경우 상품 식별 정보, 콘텐츠, 판매자, 가격, 평점, 리뷰 수와 판매 수, 미디어, URL, 타임스탬프를 중심으로 구성됩니다.

results_limit의 기본값은 100이며 1~2,000 범위의 정수를 받고, 모든 입력 URL에 걸쳐 작업에 저장되는 고유 레코드의 총 개수를 제한합니다. URL마다 따로 적용되는 한도가 아닙니다.

/v1/tasks/{task_id}를 폴링해 성공 후 data.results.items를 읽고, has_more가 true인 동안 반환된 next_cursor로 계속 요청합니다. 결과 페이지 한도는 수집량이 아니라 조회 페이지네이션을 제어합니다.

공개 여부, 페이지 내용, 공급자 출력, 정규화, 중복 제거, 작업 전체에 적용되는 results_limit이 모두 최종 결과 수를 줄일 수 있습니다. 작업이 성공해도 상품 레코드가 없을 수도 있습니다.

정상적으로 반환된 표준 상품 레코드 1건당 0.15 SocQ 크레딧이 차감됩니다. 작업은 results_limit(생략 시 100)을 기준으로 크레딧을 미리 확보한 뒤 실제 반환된 건수에 맞춰 정산하고 사용하지 않은 예약 크레딧을 환불하며, 빈 결과에는 결과 요금이 없습니다.