Search
16개 Amazon 마켓플레이스 중 어디에서든 키워드로 Amazon을 검색하며, 가격·평점·브랜드·카테고리 필터를 지원합니다.
GET | POST /v1/amazon/search파라미터는 GET의 쿼리 문자열로도, POST의 JSON 본문으로도 보낼 수 있습니다. 둘은 같습니다.
요청
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks&priceMax=30" \
-H "x-api-key: $APINOA_API_KEY"파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
query | string | 예 | Keywords to search for. Required here; to search by picture use image-search. |
brands | string list | Brand names as Amazon spells them, e.g. brands=Nike,Adidas. A call that uses brands costs 2 units instead of 1. Not available on amazon.fr (region=FR). | |
categoryId | string | Narrow to one category, by the marketplace's own id. Opaque and per-marketplace; take it from Product.category[].id or from a result's facets. | |
facets | string | object list | Narrowings taken from a result's facets, e.g. facets=Color:Black. A call that uses facets costs 2 units instead of 1. Not available on amazon.fr (region=FR). | |
include | string list | Expansions that cost more than the default answer, e.g. include=facets. | |
page | integer | 1-based page number; each page is charged separately. There is no pageSize (Amazon fixes the count per page by keyword, 13-47 in practice) and no cursor — paging is by number. | |
priceMax | number ≥ 0 | Highest price to return, in decimal major units. | |
priceMin | number ≥ 0 | Lowest price to return, in decimal major units. | |
ratingMin | number | 4 only. Amazon's rating filter offers exactly one threshold, "4 Stars & Up"; any other value is a 400 rather than a silently different search. Not available on amazon.fr (region=FR). | |
region | enum | Which Amazon marketplace to query, by buyer country: US, CA, MX, BR, FR, IT, ES, NL, SE, TR, AE, SA, IN, JP, SG, AU. Defaults to US. Prices come back in that marketplace's own currency (JP in JPY, FR in EUR). US CA MX BR FR IT ES NL SE TR AE SA IN JP SG AU | |
sort | enum | Result ordering: best_match, price_asc, price_desc, newly_listed or avg_review. Defaults to best_match, Amazon's own relevance ordering. best_match price_asc price_desc newly_listed avg_review |
같은 파라미터와 모든 응답 타입은 OpenAPI 문서에도 있습니다.
응답
data에 SearchResult를 돌려줍니다. 실제 응답을 줄인 것입니다. 배열은 앞쪽 항목만 남기고 긴 텍스트는 잘랐습니다.
{
"success": true,
"data": {
"marketplace": "amazon",
"query": "wool socks",
"page": {
"index": 1,
"size": 48,
"total": 13179
},
"items": [
{
"marketplace": "amazon",
"id": "B07F3FFTMK",
"title": "Alvada Mens Merino Wool Crew Socks Thermal and Warm Socks for Winter Work Hiking Running 3 Pairs",
"attributes": [],
"price": {
"currency": "USD",
"amount": 13.49
},
"url": "https://www.amazon.com/dp/B07F3FFTMK",
"imageUrl": "https://m.media-amazon.com/images/I/91aOC3G1W6L.jpg",
"variantCount": 24,
"listPrice": {
"currency": "USD",
"amount": 14.99
},
"unitPrice": {
"price": {
"currency": "USD",
"amount": 4.5
},
"unit": "count"
},
"rating": {
"average": 4.5,
"count": 37581
},
"salesLabel": "10K+ bought in past month",
"salesCount": 10000,
"delivery": {
"estimate": "Non-members get FREE delivery Thu, Oct 29 on $35 of items shipped by Amazon",
"free": true,
"minimumOrder": {
"currency": "USD",
"amount": 35
},
"minDays": 5,
"maxDays": 5
},
"shippingOptions": [
{
"estimate": "Non-members get FREE delivery Thu, Oct 29 on $35 of items shipped by Amazon",
"free": true,
"minimumOrder": {
"currency": "USD",
"amount": 35
},
"minDays": 5,
"maxDays": 5
},
{
"estimate": "Join Prime to get FREE delivery Tomorrow, Oct 25",
"free": true,
"minDays": 1,
"maxDays": 1,
"ext": {
"membership": "Prime"
}
}
],
"badges": [
"Overall Pick",
"Amazon's Choice"
],
"promotions": []
}
]
}
}에러
| 상태 | 코드 | 의미 |
|---|---|---|
| 400 | INVALID_PARAMS | 파라미터가 없거나, 알 수 없거나, 범위를 벗어났습니다. 메시지에 이름이 나옵니다. |
| 401 | UNAUTHORIZED | x-api-key 헤더가 없거나, 폐기되었거나 알 수 없는 키입니다. |
| 402 | INSUFFICIENT_BALANCE | 잔액이 이 호출 비용에 모자랍니다. 대시보드에서 충전하세요. |
| 429 | MARKETPLACE_SATURATED | 동시 호출이 너무 많습니다. Retry-After 초만큼 기다린 뒤 다시 시도하세요. |
| 502 | UPSTREAM_ERROR | 플랫폼이 쓸 수 없는 응답을 보냈습니다. 간격을 두고 다시 시도하세요. |
모든 코드는 Errors에 있습니다. 실패한 호출은 과금되지 않습니다.
가격
가격 호출당 $0.001, 추가 호출마다 $0.001 — 최대 1번 더, 합계 최대 $0.002. brands와 레일 facet만 하나를 더합니다. 둘 중 하나를 쓰면 2단위입니다. 다른 필터는 추가 비용이 없습니다. 정가 기준이며, 하루 1,000회를 넘으면 단가가 내려갑니다.
참고
region이 마켓플레이스를 정합니다.region=JP는 amazon.co.jp를 검색하고 가격을 엔화로 표시합니다. 16개국 목록은 Amazon 페이지에 있습니다. 생략하면 amazon.com입니다.- 페이지네이션은
page로 합니다. Amazon은 페이지 크기를 키워드에 따라 정하므로(실제로 13~47개)pageSize와cursor는 없습니다. ratingMin은4이거나, 아니면 400입니다. Amazon이 제공하는 평점 기준은 "4 Stars & Up" 단 하나입니다. 다른 값은 다른 검색으로 응답하지 않고 거부됩니다.brands와facets는 2단위입니다. 다른 필터는 추가 비용이 없습니다. Filters를 참고하세요.- 지원하지 않음:
condition,freeShipping,inStock.