Spectrum Wine public discovery APIs
These read-only HTTPS endpoints provide public website discovery data. They require no sign-in. Request JSON with GET; use reasonable request rates and backoff when a service is unavailable.
All callers are subject to request and capacity limits, including automated agents. HTTP 429 means slow down. HTTP 503 can mean temporary overload or unavailable data. Respect Retry-After when present and use backoff; do not launch concurrent retries. Encoded request URLs longer than 4096 characters receive HTTP 414.
API catalog · OpenAPI specification
Retail inventory search
GET /api/catalog/search searches public retail inventory. For example, available Burgundy at or below $100. It does not search auctions or change a cart.
Combine q, producer, country, region, subregion, section, and inclusive vintageMin/Max, priceMin/Max, scoreMin/Max. All filters combine with AND. Geography labels match exactly, with spelling aliases. Search words match accent-insensitive word prefixes; each text field accepts 1–8 searchable words of 2–80 characters. One-letter fragments, such as the d in d’Yquem, are ignored. Producer searches words in the public product name; it is not a verified producer taxonomy. Scores filter the lower bound of the highest published critic score, preserving published ranges in the response.
Availability defaults to inStock=1. Use inStock=0 to include unavailable products too. Price filters accept USD with up to two decimal places; returned price.amount is integer US cents. Only public products with visible prices and simple product selection are included. Hidden-price, configurable/custom-selection and known contradictory-geography records are omitted; consult the website for those products.
Responses contain products, total, observedAt, maxAgeSeconds and nextCursor. The complete validated website snapshot must be less than five minutes old; unavailable or expired data returns HTTP 503 rather than starting a catalog scan or presenting stale data. Results do not reserve stock or guarantee final checkout prices. Prices and stock may change after observation.
Results use increasing product ID order. Set limit from 1 to 25 (default 10), then reuse the same filters and limit with cursor=nextCursor until it is null. Pagination is a live view; later pages may reflect a newer observation. Unknown/repeated parameters and invalid ranges or cursors return HTTP 400. An overly broad word-prefix lookup returns HTTP 422; use more specific words or filters. The shared rate/capacity and origin protections apply.
Current auction search
GET /api/auctions/search searches the current auction only. For example, current-auction Burgundy with an effective bid at or below 100. The service selects the current auction from SCORE’s active operator status 99/97 and checks native public lot/session state. There is no caller auction selector, historical fallback or past-auction search.
Use q, producer, country, region, subregion, and inclusive vintageMin/Max, scoreMin/Max, bidMin/Max, estimateMin/Max. All filters combine with AND. Words are accent-insensitive prefixes; one-letter fragments are ignored. Producer matches public lot-heading words. Scores use the published lower rating bound.
The response identifies the selected auction and returns public lots, total, observedAt, catalogVersion and nextCursor. Bid/estimate numbers use the auction’s own currency units per whole lot, unlike retail API prices in US cents. The upstream public contract supplies no ISO currency code, so currencyCode is null. No currency conversion or final transaction total is provided. Follow each lot’s url for complete condition, images and terms; session openness does not establish bidding eligibility.
Set limit from 1 to 25 (default 10). Reuse the exact filters and limit with cursor=nextCursor. Cursors are bound to the current auction and catalog version; HTTP 409 requires restarting the search. If none is operator-open, HTTP 200 explicitly reports status=no_current_auction, auction=null and empty results. Source failure returns 503, not a historical auction or fabricated empty success.
The combined discovery limits apply. Auction search additionally allows one source request in flight per Node process, a process burst of 4 with 0.5 requests/second refill, and a per-client burst of 2 with 0.25 requests/second refill. There is no source request queue. Respect Retry-After on 429/503.
Search options
GET /api/search/options returns geography labels in options.country, options.region and options.subregion, plus an unavailable array of sources that failed to load. HTTP 200 can contain partial results; inspect that array.
Optional country and region filters accept labels (up to 160 characters). Both auction and retail sources are enabled by default; auction=0 or retail=0 disables a source. With scope=custom, only sources explicitly set to 1 are enabled.
Labels default to the original source spelling so existing customer forms and saved-search mappings remain compatible. Agents can request labels=canonical for normalized display aliases, including United States and common French region spellings. Canonical filtering includes every matching source option ID; unknown parents never broaden the selection.
Example: auction search options. Responses are not cached by the client.
Auction highlights
GET /api/auction-highlights?auctionId={id}&offset=0 requires a positive integer auctionId. The optional nonnegative integer offset defaults to zero. Both must be JavaScript safe integers.
The JSON response contains lots (up to 12 public lot records), total and nextOffset. Request the next offset until it is null. HTTP 400 means invalid parameters; HTTP 503 means highlights are temporarily unavailable. Error responses contain an error message.
Successful highlight responses allow 30 seconds of public caching and 60 seconds of stale-while-revalidate. An empty result does not establish auction closure, bidding eligibility or a completed sale.