Product search

Search Amazon, Best Buy, StockX, GOAT, Target, Walmart, PetSmart and Sam's Club by keyword: the products each site shows, in one result shape, with ids ready for POST /v1/products.

At a glance

Every endpoint here answers { endpoint, url, credits, duration_ms, data } with data in one shape (SearchResults): query, page, total_results, next_page and results. Each result has position, id, title, url, brand, image, price, price_max, list_price, rating, reviews_count, in_stock and sponsored; a field the site does not show is null (price_max is only there for products sold at several prices). Send next_page back as page for more; positions continue across pages.

curl -G "https://api.scrapelyserp.com/v1/structured/bestbuy/search" \
  -H "Authorization: Bearer $SCRAPELY_API_KEY" \
  --data-urlencode "query=air fryer" \
  -d sort=price_low

import os
import requests

HEADERS = {"Authorization": f"Bearer {os.environ['SCRAPELY_API_KEY']}"}

r = requests.get(
    "https://api.scrapelyserp.com/v1/structured/bestbuy/search",
    headers=HEADERS,
    params={"query": "air fryer", "sort": "price_low"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
for r in data["data"]["results"]:
    print(r["position"], r["id"], r["title"], (r["price"] or {}).get("amount"))

const res = await fetch(`https://api.scrapelyserp.com/v1/structured/bestbuy/search?${new URLSearchParams({ query: 'air fryer', sort: 'price_low' })}`, {
  headers: { Authorization: `Bearer ${process.env.SCRAPELY_API_KEY}` },
  signal: AbortSignal.timeout(30_000),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const data = await res.json();
for (const r of data.data.results) console.log(r.position, r.id, r.title, r.price?.amount);

sort takes one set of names on every site; each site accepts only the orders it actually supports, and any other value is a free 400 that lists the ones it does.

A search with no matches is a 200 with no results. A page we could not read is 502 TARGET_FAILED and costs nothing.

Amazon

price is the price the result shows (null when it shows none, as for an item with no featured offer) and list_price the struck-through list or typical price when there is one. Sponsored placements are included, in the place Amazon shows them, with sponsored: true. id and asin are both the ASIN. brand and in_stock are always null: send the ASINs to POST /v1/products for brand, stock and the buy box. Amazon picks a list or a grid layout for each query, so a page has 16 to 60 results, and shows at most 20 pages; a keyword that matches nothing, or a page past the last, is an empty list. Prices are Amazon US prices with no ZIP code set.

Full reference → GET /v1/structured/amazon/search

Best Buy

price is the current price (the sale price when on sale) and list_price the regular price when it differs.

Full reference → GET /v1/structured/bestbuy/search

StockX

price is the lowest ask and in_stock whether anything is listed. StockX shows at most 1,000 results for a search (25 pages).

Full reference → GET /v1/structured/stockx/search

GOAT

price is the lowest price across sizes and conditions and list_price the retail price.

Full reference → GET /v1/structured/goat/search

Target

price is the current price and list_price the regular price when it differs, both for the store that serves zip (a 5-digit US ZIP code) when you send one, else for Target's default store.

Full reference → GET /v1/structured/target/search

Walmart

price is the sale price, list_price the list price when it differs, and in_stock whether it can be bought online.

Full reference → GET /v1/structured/walmart/search

PetSmart

A PetSmart product comes in sizes or flavors at different prices. When they differ, price is the lowest, price_max the highest and list_price is null; when they do not, price is the price and list_price the regular price when it differs. in_stock is whether it can be ordered online. PetSmart shows at most 100 pages for a search.

Full reference → GET /v1/structured/petsmart/search

Sam's Club

price is the current price and list_price the regular price when it differs. Brand is often null here (null means the page did not show one). Sponsored placements are left out. Sam's Club often refuses a request: the call then answers 502 TARGET_FAILED, not charged, so retry it. A keyword that lands on a category page instead of results is a failure too, never an empty list.

Full reference → GET /v1/structured/samsclub/search

Walgreens

One page only, in Walgreens's own order, with up to 72 results; there is no page or sort (a page other than 1 is refused). total_results counts every match, not just the ones returned. price is the current price and list_price the regular price when it is on sale. rating comes in half stars (4.0, 4.5), not exact; null with no reviews. in_stock is false when Walgreens says the item is out of stock or not sold online, true when it offers it for ordering, and null when it does not say. Results are those Walgreens shows for its default location, so which products appear, and their order, can differ between calls. A keyword Walgreens answers with a service page rather than products (such as prescription) is a failure (502 TARGET_FAILED, not charged), never an empty list. Prescription items are not returned.

Full reference → GET /v1/structured/walgreens/search

CVS

40 results per page, in CVS's order with no store chosen (so it can differ from what a shopper sees near a store) or lowest price first (sort=price_low; best_match is the default). price is the lowest price of the product and price_max the highest when its variants cost different amounts; list_price is the regular price when the product is on sale at a single price. in_stock is always null: CVS search does not report availability. Sponsored placements and prescription items are left out. CVS often refuses a request: the call then answers 502 TARGET_FAILED, not charged, so retry it. A keyword with no matches is an empty list only when CVS says so; any other unclear answer is a failure, never an empty list.

Full reference → GET /v1/structured/cvs/search

BJ's

100 results per page, in BJ's own order, by rating (best rated first) or by newest; there is no price order, because BJ's price sort does not follow its price range. price and list_price are always null: BJ's data gives a price range, not the price at a given club, and the current club price is not available. price_range (min and max) is that range, which is not a price: items whose price shows only after sign-in may carry values that do not reflect what a member pays (see BJ's). brand is null when BJ's names none, rating is null with no reviews, and in_stock is always null. A keyword that matches nothing still returns BJ's nearest items rather than an empty list; an answer that is not clearly a list of products or a count of zero is a failure (502 TARGET_FAILED, not charged), never an empty list. Prescription items are not returned.

Full reference → GET /v1/structured/bjs/search

TCGplayer

50 results per page, in TCGplayer's own order unless sort says otherwise. price_low and price_high order by the market price; listing_low orders by the cheapest listing (any condition, so it can be a damaged copy); best_selling is TCGplayer's own sales ranking, which the answer does not let us check; newest is by release date and name A to Z. product_line narrows to one game by its lower-case name (pokemon, yugioh, star-wars-unlimited); a name that matches nothing is an empty list. price is TCGplayer's market price, one figure per product (see TCGplayer), and null when it has none; in_stock is true when at least one listing exists. brand, list_price, rating and reviews_count are always null. An empty list means TCGplayer says there are no matches; any other unclear answer is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/tcgplayer/search

Staples

100 results per page, in Staples' own order or by price (price_low, price_high), up to page 100 (10,000 results); total_results can be larger than that. price is Staples' price for one unit (see Staples); it is null for a set of options (an id starting SS). brand is null when none is given. list_price, rating, reviews_count and in_stock are always null: search does not carry them, so ask POST /v1/products for the ids you want. A keyword that matches nothing still returns Staples' nearest item (one result; for a nonsense word we saw a single set of options with a made-up title) rather than an empty list; an empty list means Staples says there are no matches. Any other unclear answer is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/staples/search

Kohl's

120 results per page, in Kohl's own order unless sort says otherwise: newest is its New Arrivals, price_low and price_high order by price (descending is close, not exact: a product priced as a range sits by its other end), and rating is its Highest Rated order, which favours products with many good reviews over a high average. category lists one Kohl's category instead of (or together with) a keyword: send the CN= part of a Kohl's catalog link, such as Gender:Mens+Category:Bottoms+Department:Clothing; query is then optional and narrows within it. A request with neither is refused, and so is a category Kohl's does not recognize (502 TARGET_FAILED, not charged). price is the regular price, or the sale price when marked down, and never the 20% coupon price Kohl's pages lead with. A product with options at different prices has price null and a price_range; list_price is the regular price of a product on sale at one price. Sponsored placements are left out. brand and in_stock are always null (see Kohl's). A keyword that matches nothing still returns Kohl's closest items (33 for a nonsense word we tried) rather than an empty list; an empty list means Kohl's says there are no matches. A page past the last, and any other unclear answer, is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/kohls/search

Office Depot

24 results per page, in Office Depot's own order unless sort says otherwise: price_low and price_high order by price, and rating is its Customer Rating order, which favours products with many good reviews over a high average. Its New Arrival order could not be told apart from the default and is not offered. price is the price for one unit (see Office Depot). list_price and in_stock are always null: Office Depot's search results show a wrong list price and a wrong stock status, so ask POST /v1/products for the skus you want. Sponsored placements are left out, and a product Office Depot lists twice is returned once. A keyword that matches nothing does not return an empty list: Office Depot answers with 200 of its products, 24 a page, and total_results is exactly 200; nothing else in the answer marks it. A genuine search reports its true total (84 or 487, say), so a total_results of 200 whose titles share none of your words means no match. An empty list means Office Depot says there are no matches; any other unclear answer is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/officedepot/search

IKEA

100 results per page, in IKEA's own order unless sort says otherwise: price_low and price_high order by price, newest is its newest first, and rating is its best rated first. category lists one IKEA category instead of (or together with) a keyword: send its category key, such as fu003 (sofas & sectionals); query is then optional and narrows within it. A request with neither is refused, and so is a category key IKEA does not recognize (502 TARGET_FAILED, not charged). price is IKEA's public price; the IKEA Family member price is given by POST /v1/products, not here. list_price is the earlier or regular price of a marked-down product. brand and in_stock are always null (see IKEA). A keyword that matches nothing returns an empty list (total_results 0). A page past the last, and any other unclear answer, is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/ikea/search

Poshmark

Up to 100 listings per page, 48 with status=sold, in Poshmark's own order unless sort says otherwise (newest is just listed). Poshmark pages with a cursor, not a page number: send next_cursor back as cursor (asked with the same status); page is refused, next_page is always null and position counts within the page. About 5,000 listings are reachable for one query, however large total_results is (it stops at 10,000), so narrow with condition=new_with_tags, min_price and max_price (dollars) to see more. status=sold lists sold listings and costs about 5 times as much per listing; it takes sort and condition but not the price filters. price is the seller's listing price, never including fees or shipping; list_price is the original price the seller gave and null when none (never 0). in_stock is true for an available listing and false for a sold one, and poshmark.sizes has the quantity per size. poshmark.condition is new_with_tags or Poshmark's own code (uln, ug, uf, not_nwt), and null when the seller set none, which is common on used listings. rating and reviews_count are always null: Poshmark listings have none, and no sold date is reported. A keyword that matches nothing still returns loose matches (99 for a nonsense word we tried) rather than an empty list; an empty list means Poshmark's own total is 0. Any other unclear answer is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/poshmark/search

GameStop

200 results per page, in GameStop's own order unless sort says otherwise: popular is its most ordered in the last week, newest its newest releases, and price_low and price_high order by price. New, pre-owned, digital and refurbished copies are separate products; a row shows one of them, and the products endpoint lists the others as gamestop.siblings. price is the current price of the row's id; a pre-owned price can be higher than the new one. There is no list price, rating or stock: those are null. A keyword that matches no word returns an empty list, not GameStop's fuzzy near-matches.

Full reference → GET /v1/structured/gamestop/search

Dick's Sporting Goods

144 results per page, in Dick's own order unless sort says otherwise: price_low and price_high follow the highest price Dick's has on file for a product, which can be a later non-sale price, so current prices are close to ordered, not exact. brand narrows to one brand, spelled as Dick's does (Nike; nike matches nothing, an empty list). Each result is a style shown in one colour; its id is the sku of that colour and one size, and it goes straight into POST /v1/products for that sku's price and stock. price is the price in force now, and list_price is the regular price when marked down. rating and reviews_count are Dick's own and null for an unrated product. in_stock and image are always null. A keyword that matches nothing still returns Dick's closest items (2 for a nonsense word we tried) rather than an empty list. A page past the last, and any other unclear answer, is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/dicks/search

Grailed

Up to 100 listings per page, in Grailed's own order unless sort says otherwise: best_match is its popularity order, newest just listed, price_low and price_high by asking price (by sold price with status=sold). status is available (the default) or sold; sold lists the listings that sold, most recently sold first. Only the first 1,000 listings of a query can be reached (page 1 to 10), however large total_results is: narrow with department, condition, min_price and max_price (whole dollars, on the asking price), size and designer to see more. price is the asking price, also on a sold listing, where the sold price can be lower (an accepted offer): read grailed.soldPrice and grailed.soldAt there. list_price is the first price in the listing's price-drop history, null when the price never dropped. rating and reviews_count are always null: listings have none (the seller's rating is grailed.sellerRating). in_stock is true for an available listing and false for a sold one. A keyword that matches nothing returns an empty list (total_results 0). Each id is what POST /v1/products takes for Grailed.

Full reference → GET /v1/structured/grailed/search

Macy's

60 to 64 results per page, in Macy's own order unless sort says otherwise: best_selling, newest and rating (its Customers' Top Rated) are Macy's own orders, and price_low and price_high order by price. category lists one Macy's category instead of a keyword: send its category id, the number after id= in a Macy's category link (20635 is men's dress shirts); a link containing id= is accepted. Send query or category, not both. A category Macy's does not recognize is a failure (502 TARGET_FAILED, not charged), and so is a page past the last. price is the regular price, or the sale price when marked down, and never a coupon price. A product with options at different prices has price null and a price_range; list_price is the regular price of a product on sale at one price. in_stock is Macy's own flag on the product, and null for a collection of products (a master listing that groups many) because the listing gives none; brand is Macy's. Some keywords (tv, mattress) send you to a category listing instead: you get that listing. A keyword that matches nothing does not return an empty list: Macy's relaxes the query and answers about 60 of its products on page 1 (a nonsense word we tried gave 97 in total), and nothing in the answer marks it. A total_results that is small with titles that share none of your words means no match. An empty list means Macy's says there are no matches; any other unclear answer is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/macys/search

Sephora

200 results per page, in Sephora's own order unless sort says otherwise: price_low and price_high follow the lowest price shown for a product, top_rated and best_selling are Sephora's own orders and newest puts new arrivals first. Each result is a product shown in one sku (shade or size); its id is the product id with that sku and goes straight into POST /v1/products. A product with several sizes or shades has one card with a price range: price is the lowest price shown, price_max the highest when no sku is on sale, and null when one is (the card does not say which sizes are). list_price is set only when the card shows exactly one regular and one sale price. For the real price of a sku, look it up. rating and reviews_count are Sephora's own (null when unrated). in_stock is always null. A keyword that matches nothing at all returns an empty list, but a nonsense word usually returns Sephora's closest products (we saw 66 and 100), so check the titles; a product id or sku as the keyword finds nothing.

Full reference → GET /v1/structured/sephora/search

Newegg

Newegg has no keyword search here: query is refused (a free 400). The results Newegg shows beside a keyword are mostly paid placements, which are not offered, and no typeahead is offered either. What is offered is a category listing: send category (one of the keys in the table above) and page through it. 100 products per page, up to page 75 (7,500 products); a larger category is listed in Newegg's own order, by sales, and sort is not offered. Only those categories are available: the rest of Newegg's departments (home, gaming, appliances and so on) are not. total_results is the category's own total. About 4 in 100 of a category's products never appear when paging it, so a listing is close to, not exactly, the whole category. price is the price charged for that item number, after Newegg's instant rebate (the rebate itself is on POST /v1/products); list_price is Newegg's price before it, when higher. It is usually Newegg's own offer: cheaper marketplace sellers may exist for the same product (see the offers tier). Marketplace sellers' offers are mixed in with Newegg's own. rating and reviews_count are Newegg's own, shared by the offers of one product, and null when unrated; in_stock is Newegg's online stock flag, and a delisted product has no price. Each id goes straight into POST /v1/products. A page past the last, an empty answer and any other unclear answer is a failure (502 TARGET_FAILED, not charged), never an empty list.

Full reference → GET /v1/structured/newegg/search

Ulta Beauty

64 results per page, in Ulta's own order unless sort says otherwise: best_selling, newest and rating are its Best Sellers, New Arrivals and Top Rated orders, and price_low and price_high order by price (a product priced as a range sits by one of its ends). rating is a pure rating order: it lists products with five stars and few reviews first, so it is not a quality ranking. Sponsored placements are left out. Each result is a product shown in one shade or size, and its id is the product id and that sku joined by a colon: it goes straight into POST /v1/products for that sku's price and stock. price is the current price; a product whose shades or sizes cost different amounts has no price and a price_range instead, and list_price is the regular price of a product marked down at one price. rating and reviews_count are Ulta's own and null for an unrated product. in_stock is always null: search carries no stock. Ulta's search takes keywords only: there is no category browse here. A phrase that matches nothing at all is an empty list, but a nonsense phrase can still return a few unrelated products (4 for one we tried). A page past the last is an empty list with the total. An answer that is not clearly a list of products or a count of none is a failure (502 TARGET_FAILED, not charged, retry it), not an empty list.

Full reference → GET /v1/structured/ulta/search

Whatnot

Up to 50 listings per page, in Whatnot's own order unless sort says otherwise (newest is newly listed). Whatnot pages with a cursor, not a page number: send next_cursor back as cursor; page is refused, next_page is always null and position counts within the page. A page can hold fewer than 50 listings with more to come: stop when next_cursor is null. total_results stops at 10,000. format=buy_it_now or format=auction keeps one kind of listing. price is the price Whatnot lists, in dollars, never including shipping or tax; for an auction it is the listing price, not a bid (whatnot.currentBid is the highest bid, null before the first one). Sellers put placeholder prices on listings that are really announcements ("bookmark for my next show"): a price of 900,000 dollars or more is returned as null with whatnot.placeholderPrice: true, so sort=price_high begins with many null prices. Prices just under that line can still be a seller's joke price. rating and reviews_count are always null: a listing has none. whatnot.seller carries the SELLER's rating out of 5 and review count, which describe the seller across all their sales and not this item. in_stock is true for an active listing with a quantity of 1 or more, and null otherwise (search lists only listings for sale). Pictures are left out (image is null) unless you pass images=true, which makes a page about nine times as costly. A keyword that matches nothing is an empty list (total_results 0). Any answer that is not clearly a list of listings or a total of zero, including a page past the end, is a failure (502 TARGET_FAILED, not charged, retry it), never an empty list.

Full reference → GET /v1/structured/whatnot/search

Kroger

24 results per request, best match first, with no paging and no sort (page and sort are refused). total_results is Kroger's own count for the query, up to 1,000: when it is above 24, add brand (the exact name as a result's brand writes it, capital letters matter) to see another slice. Prices and stock are those of one store, the one Kroger picks for the request (the nearest to where the request is served from), reported once as kroger.store (locationId, banner, city, state); zip steers the request to an area but not to an exact store, so always read kroger.store. banner searches a sister banner (ralphs, fredmeyer…). price is the regular price of one unit, also when a multi-buy applies (kroger.multiBuy: 10 for $10.00 has price 1.00); a sale is kroger.promo, with conditional: true and the condition when it needs a purchase (buy 3 or more). list_price is always null. rating and reviews_count are Kroger's own and null when a product has none. in_stock is Kroger's pickup flag at the store; kroger.stockLevel and kroger.available are the store's own. A product sold out with no regular price has a null price. Sponsored results are left out, so a page can hold fewer than 24. A keyword that matches nothing is an empty list (total_results 0). Each id is what POST /v1/products takes for Kroger. A product lookup costs more per product than search does, so for the prices of many products, search is the cheaper way.

Full reference → GET /v1/structured/kroger/search

The Home Depot

Up to 40 products per page, in Home Depot's own order unless sort says otherwise: price_low and price_high order by price, and rating is its best rated first. Prices and stock are those of one store: send store (a store number such as 7222) or postal_code (a Canadian postal code, which picks the store nearest to it), and read homedepot.store for the store that was priced; with neither, the default store is used (Fort Saskatchewan, AB). A store number that does not exist, or a postal code with no store near it, is a free 404, never an empty list. price is the price in Canadian dollars at that store; list_price is the earlier price of a marked-down product and null otherwise. rating and reviews_count are Home Depot's own, and null for a product with no reviews (never 0). in_stock is true when the product is in stock in the store or online, false when it is out of stock in both, and null when Home Depot gives neither; the unit counts for the store and for online are in homedepot.stockAtStore and homedepot.stockOnline. A keyword Home Depot cannot match is not an empty list: it answers with one loosely matching product (total_results 1), so check the title. total_results is 0 only when Home Depot says so (then the list is empty). A page past the last, and any other unclear answer, is a failure (502 TARGET_FAILED, not charged), never an empty list. Each id is what POST /v1/products takes for Home Depot.

Full reference → GET /v1/structured/homedepot/search

Wayfair

Up to 100 results per request (size, 48 by default), Wayfair's own order unless sort says otherwise: price_low and price_high by price, top_rated by review rating; sale=true keeps marked-down products. Results are always returned: a keyword that matches nothing gets Wayfair's popular products, so an empty list never means "no match" and total_results is always null (Wayfair's own total changes from request to request). Only the first 1,920 results of a query can be reached (page × size at most 1,920). Sponsored products are included, flagged sponsored, and can move between pages. price is the price on the card, list_price the struck-through price (null when there is none). rating and reviews_count are Wayfair's own and null for a product with no reviews. in_stock is true or false only when Wayfair says so, otherwise null: wayfair.stock_status is in_stock, low_stock (in stock, but low) or out_of_stock, and wayfair.stock_message is the card's text ("Low Stock", "13 Left in Stock"). Prices are for one fixed delivery area. There is no POST /v1/products for Wayfair: the id is the sku, and no sku lookup is available.

Full reference → GET /v1/structured/wayfair/search

Reverb

Up to 50 listings per page, in Reverb's own order unless sort says otherwise: best_match is its relevance order, newest just published, price_low and price_high by listed price. status is available (the default) or sold. Only the first 2,500 listings of a query can be reached (page 1 to 50), however large total_results is: narrow with condition, min_price and max_price (whole dollars) and category (a category slug such as electric-guitars; with a category the query is optional). price is the listed price, also on a sold listing, where it is the last price the listing carried: Reverb gives no sold price and no sold date. list_price is the price before a price drop, null when the price never dropped. rating and reviews_count are always null: listings have none, and the shop's rating is only on a product lookup. in_stock is true for an available listing and false for a sold one. A keyword that matches nothing returns an empty list (total_results 0). Each id is what POST /v1/products takes for Reverb.

Full reference → GET /v1/structured/reverb/search