Marketplace API Filters

모든 마켓플레이스 검색이 공유하는 필터 어휘 — 이름, 단위, 그리고 어느 마켓플레이스가 무엇을 받는지.

검색은 어디서나 같은 방식으로 좁혀집니다. 개념마다 이름 하나, 단위 하나이며, 마켓플레이스는 필터를 지원하거나 그 이름을 밝히며 거부하거나 둘 중 하나입니다.

모든 필터는 선택이며, 필터링에 추가 비용은 없습니다 — Amazon의 brands와 facets만 2유닛입니다 (아래 참고).

어휘

파라미터	타입	의미
`priceMin`	number	돌려줄 최저 가격, 십진 주단위 (`40`, `10.5`)
`priceMax`	number	돌려줄 최고 가격, 같은 단위
`brands`	string list	마켓플레이스가 표기하는 그대로의 브랜드명: `brands=Nike,Adidas`
`ratingMin`	number	마켓플레이스의 0–5 척도에서 최저 평균 별점
`condition`	enum	`new` · `used` · `refurbished`
`freeShipping`	boolean	마켓플레이스가 무료배송으로 표기한 리스팅만
`inStock`	boolean	마켓플레이스가 지금 구매 가능하다고 보고한 리스팅만
`sort`	enum	결과 정렬 — 아래 참고
`categoryId`	string	마켓플레이스 자체의 카테고리 id — 아래 참고
`facets`	list	결과에 딸린 필터 레일에서 고른 조건: `facets=Sock Rise:Ankle,Color:Black`

priceMin/priceMax는 응답이 보고하는 것과 같은 단위입니다. Money.amount가 십진 주단위이므로 priceMin=40과 돌아온 {"currency":"USD","amount":40}은 같은 것을 뜻합니다. 보조 단위를 요구하는 마켓플레이스는 내부에서 변환합니다. 센트를 보실 일은 없습니다.

리스트는 쿼리 문자열에서는 쉼표로 구분하고, JSON 본문에서는 진짜 배열입니다. 둘은 같은 요청입니다.

?brands=Nike,Adidas          {"brands": ["Nike", "Adidas"]}

불리언은 true/false/1/0을 받습니다. freeShipping=false는 정말로 false를 뜻합니다.

어디가 무엇을 받는가

	amazon	shopify	walmart	aliexpress
`priceMin` / `priceMax`	✅	✅	✅	✅
`categoryId`	✅	✅	✅	✅
`sort`	✅	—	✅	✅
`brands`	✅ (2유닛)	—	✅	—
`ratingMin`	⚠️ `4`만	✅	✅	—
`condition`	—	⚠️ `refurbished` 없음	—	—
`inStock`	—	✅	—	—
`facets`	✅ (2유닛)	—	✅	—

freeShipping은 공통 어휘에 속하지만, 현재 제공 중인 마켓플레이스 중 이를 받는 곳은 없습니다.

대시는 해당 파라미터 이름을 밝히는 400을 뜻하며, 조용한 무시가 아닙니다.

빈칸은 우리의 사정이 아니라 마켓플레이스의 사정입니다. 필터가 없는 곳은 마켓플레이스에 그런 기능이 없기 때문입니다. AliExpress 검색에는 평점 세분화가 없고, Shopify에는 리퍼비시 등급이라는 것이 없어서 condition=refurbished는 used로 뭉뚱그리지 않고 거부되며(서로 다른 주장입니다), 정렬은 아예 제공하지 않습니다.

Amazon의 평점 레일에는 "4 Stars & Up" 하나의 기준만 있습니다. 그래서 ratingMin=4만 받고 나머지는 400입니다. ratingMin=3 요청에 4점 이상 결과를 조용히 돌려주지 않기 위해서입니다.

`categoryId`

공통 카테고리 분류는 존재하지 않으므로, id는 마켓플레이스 자신의 것입니다. Amazon은 browse 노드 (679416011), Walmart는 cat_id(4171), AliExpress는 카테고리 id(200000345), Shopify는 Standard Product Taxonomy id(aa-1-13-8)입니다.

id는 어디서 오는가. 직접 물어보세요. categories가 마켓플레이스 자체 분류의 한 단계를 나열하고, browse는 그것이 돌려준 값을 받습니다. categoryId 없이 호출해 최상위를 받고 아래로 내려가거나, Product.category[]에 있는 id에서 출발하세요.

엔드포인트 문서가 밝히는 두 가지 주의점이 있습니다. 하나의 id가 모든 오퍼레이션에서 통하지는 않으며 (Walmart의 search는 맨 cat_id를 받지만 browse는 categories가 돌려주는 언더스코어 체인을 요구합니다), 일부 단계는 탐색 전용이라 "browsable": false로 표시됩니다.

search에서 categoryId는 키워드 질의를 대체하는 것이 아니라 좁히며, query는 여전히 필수입니다.

키워드 없이 카테고리를 나열하려면 browse 오퍼레이션을 쓰세요. 거기서는 categoryId가 필수이고 query는 거부됩니다. Shopify를 제외한 모든 마켓플레이스에 있으며, search와 같은 필터를 받습니다. 호출 전에 알아 둘 만한 search와의 차이가 둘 있습니다.

id의 종류가 다를 수 있습니다. Walmart의 browse는 search가 받는 맨 cat_id가 아니라 언더스코어로 이어진 체인(3944_133251_1095191_1230614_1230478)을 요구합니다.
잘못된 id가 늘 오류인 것은 아닙니다. AliExpress는 빈 items를 돌려줍니다 — 알 수 없는 카테고리와 비어 있는 카테고리를 구분하지 않습니다.

위의 타입 있는 필터들은 모든 마켓플레이스가 공통으로 가진 것들입니다. 실제로 사이트가 제공하는 것의 아주 일부에 불과합니다. Walmart에서 양말을 검색하면 25개의 필터 그룹이 그려지고, 그중 넷만 타입 있는 파라미터에 대응됩니다. 나머지 스물하나 — Sock Rise, Sleeve Length, Fabric Material, Weather Suitability — 는 그 질의에 특유한 것입니다. 노트북을 검색하면 Screen Size와 RAM으로 바뀝니다.

레일은 질의별이므로 선언되는 것이 아니라 발견되는 것입니다. 검색 응답이 그것을 싣고 옵니다.

{
  "items": [ "…" ],
  "facets": [
    { "id": "sock_rise", "name": "Sock Rise", "kind": "select",
      "values": [ { "value": "Ankle", "name": "Ankle", "count": 412 } ] },
    { "id": "brand", "name": "Brand", "kind": "select", "maps_to": "brands",
      "values": [ { "value": "Hanes", "name": "Hanes" } ] },
    { "id": "price", "name": "Price", "kind": "range", "maps_to": "priceMin", "min": 0, "max": 45 }
  ]
}

값은 facets로 되돌려 보냅니다.

curl "https://gateway.apinoa.com/v1/walmart/search?query=socks&facets=sock_rise:Ankle,color:Black" \
  -H "x-api-key: $APINOA_API_KEY"

maps_to는 같은 개념을 다루는 타입 있는 필터가 있을 때 그 이름을 알려줍니다. 타입 있는 파라미터를 우선하세요 — 그것은 모든 마켓플레이스에서 같은 것을 뜻하지만 facets는 그렇지 않습니다.

어디에 레일이 있는가

	발견	적용	비고
walmart	✅	✅	양쪽 모두 무료
amazon	✅ `include=facets`	✅	발견은 1유닛, 적용은 2유닛 — 아래 참고
shopify	`[]`	—	Shopify 검색에는 필터 레일이 없음
aliexpress	—	—	레일 없음

facets가 없다는 것은 레일이 돌아오지 않았다는 뜻입니다. 비어 있다는 것은 이 질의에 레일이 없다는 뜻입니다. Shopify는 []로 답합니다.

Amazon: 발견은 1유닛, 적용은 2유닛

서로 다른 두 가지이며, 추가 비용이 드는 것은 하나뿐입니다.

include=facets는 1유닛으로, 그것을 쓰지 않은 검색과 같습니다.

brands와 facets는 2유닛입니다. cost.search는 1..2입니다. Amazon의 나머지는 모두 여전히 1유닛입니다.

레일에 없는 라벨은 그 이름을 밝히는 400이 되며, 레일이 실제로 제공한 값의 예시가 함께 옵니다. Amazon은 레일을 잘라서 내보내므로 일치하지 않는 라벨은 정말로 모호합니다. 필터링하지 않은 결과를 돌려주면 그 사실이 가려지고, 아무것도 돌려주지 않으면 그것은 추측이 됩니다.

정렬

값	의미	amazon	walmart	aliexpress
`best_match`	마켓플레이스 자체의 관련도	✅	✅	—
`price_asc`	가격 낮은 순	✅	✅	✅
`price_desc`	가격 높은 순	✅	✅	✅
`newly_listed`	최근 등록 순	✅	✅	—
`best_seller`	판매량 순	—	✅	✅
`avg_review`	평균 평점 순	✅	—	—

이름은 우리 것이고, 각 마켓플레이스의 코드는 내부에 있습니다. 마켓플레이스가 할 수 없는 값은 400입니다.

예시

# under $40, four stars and up
curl "https://gateway.apinoa.com/v1/amazon/search?query=running+shoes&priceMax=40&ratingMin=4" \
  -H "x-api-key: $APINOA_API_KEY"

# Nike only, rated 4+, cheapest first
curl "https://gateway.apinoa.com/v1/walmart/search?query=running+shoes&brands=Nike&ratingMin=4&sort=price_asc" \
  -H "x-api-key: $APINOA_API_KEY"

# in stock, $20-$60, rated 4+
curl "https://gateway.apinoa.com/v1/shopify/search?query=wool+socks&priceMin=20&priceMax=60&ratingMin=4&inStock=true" \
  -H "x-api-key: $APINOA_API_KEY"

알아 둘 한 가지

가격 조건은 리스팅을 거릅니다. 그런데 어떤 리스팅은 하나의 가격이 아니라 가격 범위를 가집니다. 변형이 $28–$50인 상품은 $50짜리 변형 덕분에 priceMin=40 요청을 만족하지만, 카드에는 "부터" 가격인 $28이 표시됩니다.

그래서 돌아온 행 가운데 몇 개는 요청한 구간 바로 바깥에 있을 수 있습니다. 측정 결과 90–95%가 구간 안에 들어옵니다. 엄격한 경계가 필요하다면 돌아온 price를 직접 거르세요 — 마켓플레이스가 이렇게 동작하며, 우리는 행을 감추는 대신 그들이 돌려준 것을 그대로 보고합니다.

Filters

어휘

어디가 무엇을 받는가

`categoryId`

facets — 마켓플레이스 자체의 필터 레일

어디에 레일이 있는가

Amazon: 발견은 1유닛, 적용은 2유닛

정렬

예시

알아 둘 한 가지

이 페이지 내용