Search Commonplace listings
catalog_search_listingsSearch live Commonplace inventory by words, category, place (deliver_to alone returns some listings near it, not every one), or any mix. Results are active and buyable. outcome: ok; none; none_within_limits (every match is in hidden); out_of_budget (matches only outside the price range; examples ignore deliver_to); undeliverable (none reaches deliver_to; examples say how far). With deliver_to, each result carries delivery (known, deliverable, driving distance_miles, fee_usd, total_usd). Candidates come from the words or categories plus the catalogue's proximity ranking, not the whole catalogue: to be thorough, also search category_hint and its department. Up to 40 are checked per call, roughly nearest first; with max_distance_miles, one already well past it in a straight line is not checked but counted in too_far (distance_is_straight_line: a lower bound, not a drive). delivery_checked, candidates_considered and candidates_unchecked (could be inside the limits, never checked) say how far it got; next_offset, passed back as offset, checks the rest. cheapest and most_expensive spend all 40 checks and return the best (results_not_shown counts the rest; a limit up to 40 returns them); any sort orders only what was checked. farthest_checked_miles, the longest drive measured, can pass the radius. hidden counts every candidate left out, once each, by reason, with its nearest or cheapest examples. When no title matches, the category the words point to is browsed (no_title_matched) or the outcome is none; matched_on names looser words that matched. more_available: candidates_unchecked (see next_offset), or more_matches_unread: more listings match than one search reads, which offset cannot reach; narrow the words, category or price.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | best_match is relevance order and says nothing about price. With deliver_to, cheapest orders by the delivered total and nearest by driving distance (nearest needs deliver_to). | |
| limit | No | How many listings to return (default 5, at most 40). | |
| query | No | What to look for, e.g. "peloton bike+" or "sectional sofa". Words match titles loosely, with only a few everyday synonyms (couch and sofa, fridge and refrigerator) ("hot tub" misses a listing titled Jacuzzi: search its category), though "+" and "plus" count as the same. Optional when category is given: without words, the search browses the category. | |
| offset | No | With deliver_to: a previous call's next_offset, with the same other arguments, to check the candidates it did not reach (hidden then counts only that call's checks). Use it rather than price bands to be thorough: min_price_usd compares the price before delivery, so bands can miss a listing. | |
| category | No | Only these categories: a slug from catalog_list_categories, listing_resolve_category or a result's category_slug, or several separated by commas (sofas,sectionals,general-furniture). A department (furniture) or parent (peloton) covers every category beneath it, and a category covers the older slugs its listings are stored under (peloton-bike returns peloton-bike-2nd-gen listings). With words too, only this category is searched, and words matching nothing in it return none. | |
| deliver_to | No | Where it would be delivered: a 5-digit ZIP or "City, ST". Keeps only items that can be delivered there, which can be far away. To find items near a place, give the place here with max_distance_miles. | |
| max_price_usd | No | Highest price, inclusive, in US dollars: buyer_price_usd, or with deliver_to the total with delivery. A listing whose buyer price alone is over it is not a candidate at all. For "under $1,200", pass 1199.99. | |
| min_price_usd | No | Lowest buyer_price_usd, inclusive, in US dollars. Always compared with buyer_price_usd, with or without deliver_to. | |
| hidden_examples | No | How many listings each hidden reason shows (default 10 for too_far, 20 for the others); counts are always complete. | |
| max_distance_miles | No | With deliver_to: only items within this many driving miles of it. |