Costco

Costco Search API

Search Costco by keyword or item number and get structured product rows as JSON: online price and original price, rating and review count, member-only and stock flags, promotions and facets. Pass warehouse_id to add that warehouse's in-store price, stock status and price code to every result. Costs 1 credit per request.

POST/api/v1/costco/search

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your Scavio API key (e.g. Bearer sk_live_your_key).

Body

application/json

querystringrequired

Keywords or a Costco item number, 1-200 characters.

Example: olive oil

countryenum<string>default:us

Costco site. us and ca support every parameter; uk, au, mx, jp, kr and tw support keyword, sort and paging only.

Example: uk

us — costco.com, United States.
ca — costco.ca, Canada.
uk — United Kingdom.
au — Australia.
mx — Mexico.
jp — Japan.
kr — South Korea.
tw — Taiwan.

warehouse_idstring

Costco warehouse number from the Warehouses endpoint. Adds that warehouse's in-store price, stock status and price code to every result. Omit for online prices only. us and ca only.

Example: 1062

sort_byenum<string>default:best_match

Result order. Costco broadens matching under any sort other than best_match. newest is not available on uk, au, mx, jp, kr or tw.

Example: price_low

best_match — Costco's relevance ranking.
price_low — Price, lowest first.
price_high — Price, highest first.
top_rated — Highest average rating first.
newest — Newest items first (us and ca).

brandsarray<string>

Only these brands, up to 20 names, e.g. ["Kirkland Signature"]. us and ca only.

Example: ["Kirkland Signature"]

min_pricenumber

Minimum online price, inclusive, 0 or greater. us and ca only.

Example: 10

max_pricenumber

Maximum online price, inclusive, 0 or greater. us and ca only.

Example: 50

min_ratingnumber

Minimum average star rating, 1-5. us and ca only.

Example: 4

on_saleboolean

Only items with an active discount. us and ca only.

Example: true

in_stockboolean

Hide out-of-stock items. us and ca only.

Example: true

in_warehouseboolean

Only items sold and in stock at warehouse_id. Requires warehouse_id.

Example: true

pageintegerdefault:1

Results page, 1-based, 1-500.

Example: 2

page_sizeintegerdefault:24

Results per page, 1-120 (up to 100 on uk, au, mx, jp, kr and tw).

Example: 48

Request

from scavio import ScavioClient

client = ScavioClient(api_key="sk_live_your_key")

# warehouse_id adds the in-store price and price code to every row
results = client.costco.search("olive oil", warehouse_id="1062", page_size=5)

for item in results["data"]["results"]:
    store = item.get("warehouse") or {}
    print(item["item_number"], item["title"], item["price"], store.get("price"))

Response

"country": "us",

"query": "olive oil",

"category": null,

"redirected_to_category": null,

"corrected_query": null,

"warehouse_id": "1062",

"total_results": 106,

"page": 1,

"page_size": 5,

"total_pages": 22,

"count": 5,

"response_time": 3357

}

from scavio import ScavioClient client = ScavioClient(api_key="sk_live_your_key") # warehouse_id adds the in-store price and price code to every row results = client.costco.search("olive oil", warehouse_id="1062", page_size=5) for item in results["data"]["results"]: store = item.get("warehouse") or {} print(item["item_number"], item["title"], item["price"], store.get("price"))