API Documentation
Explore authentication requirements, request payloads, and response structures for every Wine Labs API endpoint.
Filter by Section
Matching
Resolve free-text wine queries into LWIN codes and Wine Labs IDs for downstream workflows.
/match_to_lwinMatch To LWINResolve a single wine search query to LWIN codes, a Wine Labs ID and a normalized display label.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Account identifier issued during onboarding; used for authentication and quota tracking. |
| query | string | Optional | None | Wine name, producer, vintage, or other descriptive text to resolve. Required when `lwin` and `wl_id` are not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` and `wl_id` are not provided. |
| wl_id | string | Optional | None | Wine Labs wine identifier. Required when `query` and `lwin` are not provided. |
Response Highlights
- `lwin7`: base 7-digit LWIN code when a match is found.
- `lwin`: longest available LWIN including vintage or format detail.
- `display_name`: normalized wine name suitable for customer-facing views.
- `wl_id`: the Wine Labs ID, the canonical identifier covering 813K+ wines and spirits.
- Returns null values for all fields when the query cannot be matched.
- Usage limit: up to 30,000 matched rows per rolling 30 days across matching endpoints.
Wine Intelligence
Canonical wine profiles, classification, and reference data resolved from LWIN or free text.
/wine_infoWine InfoRetrieve canonical wine metadata including varietal, colour, and region details.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for authentication and rate limiting. |
| query | string | Optional | None | Free-text wine description. Required when `lwin` and `wl_id` are not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` and `wl_id` are not provided. |
| wl_id | string | Optional | None | Wine Labs wine identifier. Required when `query` and `lwin` are not provided. |
Response Highlights
- `lwin`: resolved LWIN echoed from the resolver.
- `result`: canonical wine profile containing name, varietal, colour, wine or spirit classification, and regional hierarchy.
- `result.avg_beg_drink_window` / `result.avg_end_drink_window`: average drinking-window years for the resolved vintage, or null when no vintage/window is available.
- `result.is_kosher`: true only with recorded evidence for the resolved wine or vintage; null means unknown, not non-kosher. A vintage-specific request never inherits another vintage or producer-wide claim. Passover suitability and mevushal status are separate attributes.
- At least one of `query`, `lwin`, or `wl_id` must be supplied.
- Returns `result = null` when the resolver cannot map the wine to Wine Labs metadata.
/commodity_codesCommodity CodesClassify wine, sparkling wine, grape must, other fermented beverages, and spirits into high-level HS and market-specific commodity code guidance.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for authentication and rate limiting. |
| query | string | Optional | None | Free-text product or wine description. Used with Wine Labs matching when provided. |
| lwin | string | Optional | None | Direct LWIN lookup for known wines. |
| wl_id | string | Optional | None | Wine Labs wine identifier for known wines. |
| vintage | string | Optional | None | Optional vintage used when enriching known wine attributes. |
| product_type / commodity_type / hs_code_6 | string | Optional | None | Optional classification hints when the product is not supplied as a known wine. |
| container_size_ml, abv, color, origin_country, destination_country | number/string | Optional | None | Optional product attributes that improve jurisdiction-specific guidance. |
Response Highlights
- `hs_code_6`: resolved six-digit HS classification and display label.
- `commodity_type`: Wine Labs high-level commodity category.
- `jurisdiction_codes`: available resolved market codes, when they can be derived safely.
- `country_code_systems[]`: market-by-market code systems, candidate patterns, and any attributes still needed for authority lookup.
- At least one product identifier or classification hint is required.
- Market-specific codes may be returned as candidate patterns when official authority lookup or additional product attributes are still required.
Market Data
Pricing snapshots and merchant availability for resolved wines.
/price_statsPrice StatsRetrieve the latest aggregated pricing statistics for a wine in a target region.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Optional | None | Free-text wine description. Required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` is not provided. |
| region | string | Optional | world | Target region alias. Supported values: world, europe, north america, south america, africa, asia, oceania. |
| currency | string | Optional | USD | Optional output currency (uppercased) used for price conversion. |
| user_id | string (UUID) | Required | None | Account identifier issued during onboarding; used for authentication and quota tracking. |
Response Highlights
- `vintage`: vintage tied to the returned snapshot.
- `region`: normalized region label from the request.
- `lwin`: resolved LWIN when present.
- `results[]`: array of pricing metrics (created_at, date, median_value, min, p25, p75, max, count, count_outliers, winelabs_price).
- `results[].market_price_confidence`: high, medium, low, or null. Retail listing evidence only: high requires at least 20 listings and (p75 - p25) / median <= 0.25; medium requires at least 5 and <= 0.50; otherwise low. Missing or invalid evidence returns null. This describes listing depth and price agreement, not statistical probability, freshness, or independent seller count.
- Returns an empty `results` array when no recent pricing is available for the selected wine and region.
- Usage limit: up to 150,000 requests per rolling 30 days across Market Data endpoints.
/historical_price_statsHistorical Price StatsRetrieve the historical time series of aggregated pricing statistics for a wine — one row per date (roughly the last 14 months) instead of the single latest snapshot returned by `/price_stats`.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Optional | None | Free-text wine description. Required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` is not provided. |
| region | string | Optional | world | Target region alias. Supported values: world, europe, north america, south america, africa, asia, oceania. |
| currency | string | Optional | USD | Optional output currency (uppercased) used for price conversion. |
| user_id | string (UUID) | Required | None | Account identifier issued during onboarding; used for authentication and quota tracking. |
Response Highlights
- `vintage`: vintage tied to the returned series.
- `region`: normalized region label from the request.
- `lwin`: resolved LWIN when present.
- `results[]`: time series ordered by date — one entry per date (created_at, date, median_value, average, min, p25, p75, max, count, count_outliers, winelabs_price), covering roughly the last 14 months.
- Same request shape as `/price_stats`; `/price_stats` returns the latest snapshot while `/historical_price_stats` returns the full dated history.
- Returns an empty `results` array when no historical pricing is available for the selected wine and region.
- Usage limit: up to 150,000 requests per rolling 30 days across Market Data endpoints.
/listingsListingsRetrieve active merchant offers with optional geography and packaging filters.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Optional | None | Free-text wine description. Required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` is not provided. |
| user_id | string (UUID) | Required | None | Account identifier issued during onboarding; used for authentication and quota tracking. |
| currency | string | Optional | USD | ISO currency code used for price conversion. |
| region | string | Optional | world | Continent-level geography filter. Supported values: world, europe, north america, south america, africa, asia, oceania, australia (alias for oceania). Maps to a continent filter when explicit `continents` / `countries` are not provided. |
| only_trusted_merchants | boolean | Optional | false | Filter to merchants designated as trusted partners. |
| continents | array<string> | Optional | [] | Restrict listings to the provided continents. |
| countries | array<string> | Optional | [] | Restrict listings to the provided countries. Accepts full names (e.g. "France") or ISO alpha-2/alpha-3 codes (e.g. "FR", "FRA"). Note: use "UK" or "GB" for the United Kingdom. |
| standardized_formats | array<string> | Optional | [] | Filter by internal format labels (alias: `formats`). Allowed values: bottle, half-bottle, magnum, double-magnum. |
| vintages | array<string> | Optional | [] | Filter to specific vintages. |
| min_offer_volume | number | Optional | None | Minimum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment. |
| max_offer_volume | number | Optional | None | Maximum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment. |
| limit | number | Optional | 20 | Page size (1–20). |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
Response Highlights
- `lwin`: resolved LWIN used for the search.
- `limit`, `offset`, `count`, `has_more`: pagination metadata.
- `results[]`: array of merchant offers including pricing, merchant names and websites, formats, and analytics flags. Street addresses and phone numbers are not returned.
- Either `query` or `lwin` must be supplied.
- Extended LWINs auto-infer filters when explicit values are absent: 16+ digits can set `standardized_formats`; 18 digits can set `min_offer_volume` / `max_offer_volume`.
- Use `has_more` with `offset` to iterate through additional listings.
- Usage limit: up to 150,000 requests per rolling 30 days across Market Data endpoints.
/pricing_flow_pricePricing Flow PriceExecute your configured pricing flow (lowest priority when unspecified) using existing authorizations and credits; configure flows via Pricing Flow Builder.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier for pricing flows. |
| query | string | Optional | None | Free-text wine description; required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup; required when `query` is not provided. |
| vintage | string | Optional | None | Optional vintage to guide resolution and routing. |
| format | string | Optional | None | Bottle format hint used to route pricing logic. |
| condition | string | Optional | None | Bottle condition hint forwarded to the flow. |
| pack_size | number | Optional | None | Pack size (alias `packSize`) used for packaging adjustments. |
| currency | string | Optional | USD | Target currency for FX conversion; does not filter pricing sources. |
| flow_id | string | Optional | None | Specific pricing flow to run; defaults to the lowest-priority flow when omitted. |
Response Highlights
- `flow_id`: pricing flow identifier executed for the request.
- `price`, `bottle_price`, `adjusted_price`, `currency`: returned pricing with packaging adjustments when applicable.
- `data_source`, `aggregation`: source and aggregation used to derive the price.
- `applied_modifiers`, `path`: modifiers and routing path applied within the flow.
- `resolved_lwin`, `resolved_vintage`: resolved wine context.
- `confidence_score`, `record_count`: diagnostics for the derived price.
- `format_detected`, `case_size_detected`: detected packaging cues from the request.
- `trace`: per-node execution details including router matches and intermediate prices.
- Provide either `query` or `lwin` to resolve the wine; flows return 404 when no wine or price can be derived.
- Currency input only converts returned values; it never filters underlying records.
- When `flow_id` is provided that specific flow is used; otherwise the user's lowest-priority pricing flow runs.
/shop_detailsShop DetailsRetrieve detailed information about a retailer/shop by ID, or search for shops by name.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for authentication and rate limiting. |
| retailer_id | number | Optional | None | The retailer ID to look up. Required when not using search mode. |
| query | string | Optional | None | Search query for shop names (minimum 3 characters). When provided, activates search mode. |
| limit | number | Optional | 10 | Maximum results returned in search mode. |
| offset | number | Optional | 0 | Pagination offset for search mode. |
Response Highlights
- `retailer_id`: unique retailer identifier.
- `shop_type`: type of shop (merchant, grocery, wine_shop).
- `shop_name`: name of the shop/retailer.
- `shop_country`: country where the shop is located.
- `shop_state`: state/region where the shop is located.
- `offers_count`: number of wine offers available from this retailer.
- `shop_price_rating`: price competitiveness rating (higher = better prices).
- `shop_diversity_rating`: inventory diversity rating (higher = more diverse selection).
- In search mode: returns `results[]` array of shop details.
- Either `retailer_id` or `query` must be provided.
/restaurant_detailsRestaurant DetailsFind a restaurant by name and get its `restaurant_id`, or look up one restaurant by `restaurant_id`. Use the id with Restaurant Listings to pull that restaurant's wine list.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for authentication and rate limiting. |
| restaurant_id | number | Optional | None | Restaurant identifier to look up. Returns one restaurant with full details. Required when `query` is not provided. |
| query | string | Optional | None | Restaurant name to search for (minimum 3 characters, for example `French Laundry`). Activates search mode. Required when `restaurant_id` is not provided. |
| city | string | Optional | None | Narrows a `query` to restaurants whose address contains this city. |
| state | string | Optional | None | Narrows a `query` by state or region. |
| country | string | Optional | None | Narrows a `query` by country (`US`, `USA` and `United States` are treated the same). |
| michelin_stars | number | Optional | None | Narrows a `query` to restaurants with exactly this many Michelin stars. |
| limit | number | Optional | 10 | Maximum results returned in search mode (1-20). |
| offset | number | Optional | 0 | Pagination offset for search mode (0-200). |
Response Highlights
- Search mode returns `results[]`, each with only:
- `restaurant_id`: identifier to pass to Restaurant Listings or back to this endpoint.
- `has_wine_list`: whether Wine Labs holds a wine list for this restaurant.
- Lookup by `restaurant_id` returns one object with `restaurant_id`, `restaurant_name`, `restaurant_country`, `restaurant_state`, `restaurant_website`, `restaurant_lat`, `restaurant_lng`, `offers_count`, `michelin_stars`, `has_wine_list`, `winelist_last_checked_at`. Street addresses and phone numbers are not returned.
- Either `restaurant_id` or `query` must be provided. `city`, `state`, `country` and `michelin_stars` only narrow a `query`; they cannot be used on their own.
- Search results are ordered by the number of wine list offers we hold, then Michelin stars, then name.
- Uses the general details rate limits (a fraction of your market data quota).
/restaurant_listingsRestaurant ListingsRestaurant wine list offers, scoped to one restaurant (`restaurant_id`), one wine (`lwin` or `wl_id`), or a geography (city, state, or coordinates), with optional distance sorting from a coordinate pair.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for authentication and rate limiting. |
| restaurant_id | number | Optional | None | Return the wine list of one restaurant. Get the id from Restaurant Details. Sufficient on its own. |
| lwin | string | Optional | None | LWIN of one wine. Returns the restaurants that list that wine. An LWIN11 also filters the vintage. Sufficient on its own. |
| wl_id | string | Optional | None | Wine Labs wine identifier. Same behaviour as `lwin`. Sufficient on its own. |
| city | string | Optional | None | City name used to match restaurant addresses (for example, `New York` or `Paris`). |
| state | string | Optional | None | State filter for restaurant location. Accepts a 2-letter abbreviation or recognized full state name (for example, `CA` or `California`). |
| lat | number | Optional | None | Latitude of the search origin point. Must be provided together with `lng`. |
| lng | number | Optional | None | Longitude of the search origin point. Must be provided together with `lat`. |
| max_distance_miles | number | Optional | 50 | Maximum search radius in miles when `lat`/`lng` are provided. |
| max_results | number | Optional | 20 | Page size (1-20). Use `offset` to page through a longer list. |
| offset | number | Optional | 0 | Pagination offset. The response sets `has_more` when another page exists. |
| vintage | array<string> | Optional | None | Optional vintage filter (e.g., ["2015", "2016"]). |
| format | array<string> | Optional | None | Optional bottle format filter (e.g., ["750ml", "1500ml"]). |
| country | array<string> | Optional | None | Optional country filter for restaurant location. |
| continent | array<string> | Optional | None | Optional continent filter for restaurant location. |
| currency | string | Optional | USD | Output currency for wine price conversion. |
| include_unmatched | boolean | Optional | true | Set to `false` to drop list lines we could not match to a Wine Labs wine. |
Response Highlights
- `city`, `state`, `lat`, `lng`: echoed filters when provided.
- `currency`: applied currency for prices.
- `has_more`: whether another page exists at `offset + max_results`.
- `results[]`: array of restaurant listings, each containing:
- `restaurant_id`, `restaurant_name`, `restaurant_country`, `restaurant_state`: restaurant identification. Street addresses and phone numbers are not returned.
- `distance_miles`: distance from search origin when coordinates are provided.
- `wine_name`, `wine_vintage`, `wine_price`, `wine_format`: wine listing details as printed on the list.
- `wine_list_file_url`, `last_check_at`: the source wine list and when we last read it.
- `is_outlier`: set when the price is far from the market for that wine.
- Requires `markets` authorization. Uses the same rate limits as other market data endpoints.
- At least one of `restaurant_id`, `lwin`, `wl_id`, `city`, `state`, or a full `lat`/`lng` pair is required.
- Typical flow: call Restaurant Details with a name to get `restaurant_id`, then call this endpoint with that id.
- `lat` and `lng` must be supplied together. When coordinates are provided, results are filtered and sorted by distance.
Auctions & Exchange
Self-serve and custom transaction datasets for auctions and exchange venues.
Auctions and exchange endpoints are available on self-serve plans, with custom access available for bespoke scopes, limits, and integrations.
Use the API pricing page for instant checkout, or contact us if you need a custom venue mix or higher-throughput package.
/auctionsAuctionsAccess historical auction results from the supported self-serve auction dataset or your custom authorized scopes.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for plan-based authentication and quota tracking. |
| auction_provider_ids | array<number> | Optional | [] | Filter results to specific auction providers. |
| query | string | Optional | None | Free-text wine description; optional when providing identifiers. |
| lwin | string | Optional | None | Direct LWIN filter. |
| vintage | string | Optional | None | Vintage filter. |
| lot_id | string | Optional | None | Internal Wine Labs lot identifier. |
| auction_lot_id | string | Optional | None | Provider-specific lot identifier. |
| auction_id | string | number | Optional | None | Auction event identifier. |
| sold_date_from | date (YYYY-MM-DD) | Optional | None | Inclusive lower bound for sold date. |
| sold_date_to | date (YYYY-MM-DD) | Optional | None | Inclusive upper bound for sold date. |
| limit | number | Optional | 10 | Page size (1–100). |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
| sort_by | string | Optional | sold_date | Sort options: sold_date, auction_date, hammer_price_usd, realised_price_usd, bottle_price_usd, auction_id. |
| sort_direction | string | Optional | desc | Sort direction: asc or desc. |
Response Highlights
- `limit`, `offset`, `count`, `total_available`: pagination metadata.
- `results[]`: auction lots with provider info, hammer prices (native and USD), bottle price, currency, and resolved wine identifiers.
- Self-serve auction plans include every supported auction house. Sotheby’s, Interenchères and Heritage Auctions results cover sales held in the last 365 days.
- Usage limits depend on your active auction subscription and renew each billing cycle.
- Custom plans are available when you need bespoke scopes, limits, or integration support.
/exchange/orderbookExchange OrderbookRetrieve current bids and offers from the supported self-serve exchange venues or your custom authorized sources.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for plan-based authentication and quota tracking. |
| query | string | Optional | None | Free-text wine description; optional when identifiers are provided. |
| lwin | string | Optional | None | Direct LWIN filter. |
| vintage | string | Optional | None | Vintage filter. |
| sources | array<string> | Optional | [] | Restrict results to specific exchange sources. |
| bid_ask | string | Optional | None | Use "BID" or "ASK" to return only bids or asks. |
| format | string | Optional | None | Bottle format filter. |
| condition | string | Optional | None | Condition filter. |
| packaging | string | Optional | None | Packaging filter. |
| duty_code | string | Optional | None | Duty status filter (e.g., IB, DP). |
| currency_code | string | Optional | None | Optional target currency for FX conversion; does not filter order book rows by currency. |
| limit | number | Optional | 10 | Page size (1–100). |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
| sort_by | string | Optional | price | Sort options: price, source, bid_ask, volume, currency_code. |
| sort_direction | string | Optional | asc | Sort direction: asc or desc. |
Response Highlights
- `limit`, `offset`, `count`, `total_available`: pagination metadata.
- `results[]`: order book entries with provider identifiers, wine details, side (bid/ask), volume, price, currency, condition, packaging, duty status, and display name.
- Currency inputs convert returned prices only; they never filter which orders are returned.
- Self-serve exchange plans include `bordeaux_index`, `winebourse`, `cru_world_wine`, `cultx`, `cult_wines`, `vinovest`, `bbx`, and `arvest_wine`.
- Transactions API includes auctions, exchange trades, and exchange order book under one shared allowance. All exchanges except Liv-ex are included. Legacy Exchange Endpoints subscriptions retain their original split allowances.
- Custom plans are available if you need additional venues, custom scopes, or higher throughput.
/exchange/tradesExchange TradesRetrieve historical executed trades from the supported self-serve exchange venues or your custom authorized sources.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for plan-based authentication and quota tracking. |
| query | string | Optional | None | Free-text wine description; optional when identifiers are provided. |
| lwin | string | Optional | None | Direct LWIN filter. |
| vintage | string | Optional | None | Vintage filter. |
| sources | array<string> | Optional | [] | Restrict results to specific exchange sources. |
| format | string | Optional | None | Bottle format filter. |
| condition | string | Optional | None | Condition filter. |
| packaging | string | Optional | None | Packaging filter. |
| duty_code | string | Optional | None | Duty status filter (e.g., IB, DP). |
| currency_code | string | Optional | None | Optional target currency for FX conversion; does not filter trades by currency. |
| traded_at_from | ISO 8601 datetime | Optional | None | Inclusive lower bound for trade timestamp. |
| traded_at_to | ISO 8601 datetime | Optional | None | Inclusive upper bound for trade timestamp. |
| limit | number | Optional | 100 | Page size (1–100). |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
| sort_by | string | Optional | traded_at | Sort options: traded_at, price, source, volume. |
| sort_direction | string | Optional | desc | Sort direction: asc or desc. |
Response Highlights
- `limit`, `offset`, `count`, `total_available`: pagination metadata.
- `results[]`: executed trades with trade identifiers, provider context, wine identifiers, price, currency, volume, condition, packaging, duty status, and execution timestamp.
- Self-serve exchange plans include `bordeaux_index`, `winebourse`, `cru_world_wine`, `cultx`, `cult_wines`, `vinovest`, `bbx`, and `arvest_wine`.
- Transactions API includes auctions, exchange trades, and exchange order book under one shared allowance. All exchanges except Liv-ex are included. Legacy Exchange Endpoints subscriptions retain their original split allowances.
- Use `traded_at_from` and `traded_at_to` to constrain the time horizon of results.
- Custom plans are available if you need additional venues, custom scopes, or higher throughput.
/transactionsTransactionsRetrieve historical transaction data across the auction and exchange scopes available to your self-serve or custom access package.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier used for plan-based authentication and quota tracking. |
| auction_provider_ids | array<number> | Optional | [] | Optional auction-provider filter for transaction feeds that include auction venues. |
| query | string | Optional | None | Free-text wine description; optional when identifiers are provided. |
| lwin | string | Optional | None | Direct LWIN filter. |
| lwins | array<string> | Optional | [] | Batch list of LWIN values when requesting multiple wines in one call. |
| vintage | string | Optional | None | Vintage filter. |
| queries | array<string> | Optional | [] | Batch list of free-text wine queries when requesting multiple wines in one call. |
| sources | array<string> | Optional | [] | Restrict results to specific exchange sources. |
| format | string | Optional | None | Bottle format filter. |
| condition | string | Optional | None | Condition filter. |
| packaging | string | Optional | None | Packaging filter. |
| duty_code | string | Optional | None | Duty status filter (e.g., IB, DP). |
| currency_code | string | Optional | None | Optional target currency for FX conversion; does not filter trades by currency. |
| traded_at_from | ISO 8601 datetime | Optional | None | Inclusive lower bound for trade timestamp. |
| traded_at_to | ISO 8601 datetime | Optional | None | Inclusive upper bound for trade timestamp. |
| limit | number | Optional | 100 | Page size (1–100). |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
| sort_by | string | Optional | traded_at | Sort options: traded_at, price, source, volume. |
| sort_direction | string | Optional | desc | Sort direction: asc or desc. |
Response Highlights
- `limit`, `offset`, `count`, `total_available`: pagination metadata.
- `results[]`: executed trades with trade identifiers, provider context, wine identifiers, price, currency, volume, condition, packaging, duty status, and execution timestamp.
- Transactions access follows the same self-serve and custom authorization rules as the auctions and exchange endpoints above.
- Transactions API shares one monthly allowance across auctions, exchange trades, and exchange order book. The combined /transactions endpoint counts once per wine, without billing its internal auction and trade calls again. Batch requests count per wine. All auction houses and exchanges except Liv-ex are included. Sotheby’s, Interenchères and Heritage Auctions results cover sales held in the last 365 days.
- Use `query`/`lwin` for a single wine request, or `queries`/`lwins` for multi-wine batch style requests.
- Use `traded_at_from` and `traded_at_to` to constrain the time horizon of results.
Market Insights
Authorized historical pricing and alerting for market participants.
Market insights endpoints require a custom contract and explicit authorization from Wine Labs.
Contact us to configure access to specific venues, providers, and data scopes before integrating.
/price_historyPrice HistoryReturn aggregated price history for a resolved wine with client-friendly caching and currency conversion.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Optional | None | Free-text wine description. Required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` is not provided. |
| user_id | string (UUID) | Required | None | Authorized user identifier (accepts `user_id` or `userId`) required for market_insights access. |
| region | string | Optional | world | Region alias. Supported values: world, europe, north america, south america, africa, asia, oceania, uk, united kingdom, continental europe. |
| vintage | string | Optional | ALL | Vintage filter; use ALL to include every vintage. |
| currency | string | Optional | USD | Output currency (uppercased) for price conversion. |
| start_date | string (YYYY-MM-DD) | Optional | None | Inclusive start date filter; rejected when the format is invalid or if it is later than `end_date`. |
| end_date | string (YYYY-MM-DD) | Optional | None | Inclusive end date filter; validated against `start_date` and forwarded to the SQL query. |
| limit | number | Optional | 10 | Rows per page (clamped 1–100), ordered by newest date first. |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
Response Highlights
- `history[]`: reverse-chronological price history data with converted prices.
- `regions`: static list of available region aliases for selection.
- Requires market_insights authorization plus either `query` or `lwin`; unresolved wines return 404.
- `start_date`/`end_date` are parsed and logged with the request metadata, and rejected when invalid or when `start_date` is later than `end_date`.
/trade_signalsTrade SignalsReturn price movement alerts for a wine with optional geography, format, and change-type filters.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| query | string | Optional | None | Free-text wine description. Required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup. Required when `query` is not provided. |
| userId | string (UUID) | Required | None | Authorized user identifier required for market_insights access. |
| region | string | Optional | world | Continent-level geography filter; overrides `continents` when provided. Supported values: world, europe, north america, south america, africa, asia, oceania. |
| currency | string | Optional | USD | Output currency (uppercased) for price conversion. |
| onlyTrustedMerchants | boolean | Optional | false | Filter results to trusted merchants only. |
| continents | array<string> | Optional | None | Geographic filter applied when `region` is not set. |
| countries | array<string> | Optional | None | Restrict results to the provided countries. Accepts full names (e.g. "France") or ISO alpha-2/alpha-3 codes (e.g. "FR", "FRA"). Note: use "UK" or "GB" for the United Kingdom. |
| formats | array<string> | Optional | None | Standardized format filters (e.g., bottle sizes). |
| vintages | array<string> | Optional | None | Filter to specific vintages. |
| changeTypes | array<string> | Optional | ["removed"] | Types of changes to surface (e.g., removed, increased, decreased). |
| since | string | Optional | None | Lower bound timestamp for detected changes. |
| lastOnly | boolean | Optional | true | Return only the latest signal per location when true. |
| limit | number | Optional | 10 | Rows per page (clamped 1–10). |
| offset | number | Optional | 0 | Pagination offset (>= 0). |
| minPercentChange | number | Optional | 3 | Minimum percent change threshold; defaults to 3 when unset or non-finite. |
Response Highlights
- `data[]`: trade signal entries with merchant and location metadata.
- Requires market_insights authorization plus either `query` or `lwin`; unresolved wines return 404.
Custom Feed
Aggregated reporting for custom uploads using existing authentication and credits.
/custom_feed/transactionsCustom TransactionsFetch aggregated custom transactions using existing authentication and credits.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier for the custom feed dataset. |
| agg_level | string | Optional | vintage | Aggregation level; allowed values: vintage, format, volume. |
| currency | string | Optional | None | Optional target currency for FX conversion only; it does not filter the results. |
| page_limit | number | Optional | 50 (max 500) | Rows per page; clamped between 1 and 500. |
| page_offset | number | Optional | 0 | Pagination offset (>= 0). |
| query | string | Optional | None | Free-text wine description used when resolving without `lwin`. |
| lwin | string | Optional | None | Direct LWIN filter; optional when `query` is provided. |
| wine_search | string | Optional | None | Search string applied to stored wine names. |
| sort_col | string | Optional | None | Optional sort column for the aggregation. |
| vintages | array<string> | Optional | None | Filter to specific vintages. |
| formats | array<number> | Optional | None | Filter to bottle formats by milliliter value. |
| volumes | array<number> | Optional | None | Filter to specific volumes. |
Response Highlights
- `limit`, `offset`, `count`: pagination metadata echoed from the service.
- `results[]`: aggregated custom transaction rows.
- `results[]` fields include `id`, `created_at`, `upload_id`, `wine_name`, `vintage`, `format`, `volume`, `raw_format`, `bottle_price`, `price`, `matching_attempted`, `offer_type`, `condition`, `packaging`, `quantity`, `ordered_at`, `source_id`, `user_id`, `currency_code`, `expiration_date`, `source_name`, `email_address`.
- Currency input converts returned prices only; it never filters the underlying custom rows.
/custom_feed/price_listCustom Price ListFetch aggregated custom offers/price lists using existing authentication and credits.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier for the custom feed dataset. |
| agg_level | string | Optional | vintage | Aggregation level; allowed values: vintage, format, volume. |
| currency | string | Optional | None | Optional target currency for FX conversion only; it does not filter the results. |
| page_limit | number | Optional | 50 (max 500) | Rows per page; clamped between 1 and 500. |
| page_offset | number | Optional | 0 | Pagination offset (>= 0). |
| query | string | Optional | None | Free-text wine description used when resolving without `lwin`. |
| lwin | string | Optional | None | Direct LWIN filter; optional when `query` is provided. |
| wine_search | string | Optional | None | Search string applied to stored wine names. |
| sort_col | string | Optional | None | Optional sort column for the aggregation. |
| vintages | array<string> | Optional | None | Filter to specific vintages. |
| formats | array<number> | Optional | None | Filter to bottle formats by milliliter value. |
| volumes | array<number> | Optional | None | Filter to specific volumes. |
Response Highlights
- `limit`, `offset`, `count`: pagination metadata echoed from the service.
- `results[]`: aggregated custom price list rows.
- `results[]` fields include `id`, `created_at`, `upload_id`, `wine_name`, `vintage`, `format`, `volume`, `raw_format`, `bottle_price`, `price`, `matching_attempted`, `source_id`, `user_id`, `currency_code`, `expiration_date`, `source_name`, `email_address`.
- Currency input converts returned prices only; it never filters the underlying custom rows.
/pricing_flow_pricePricing Flow PriceExecute the user’s pricing flow (lowest priority when unspecified) using existing authorizations and credits; configure flows via Pricing Flow Builder.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | string (UUID) | Required | None | Authorized user identifier for pricing flows. |
| query | string | Optional | None | Free-text wine description; required when `lwin` is not provided. |
| lwin | string | Optional | None | Direct LWIN lookup; required when `query` is not provided. |
| vintage | string | Optional | None | Optional vintage to guide resolution and routing. |
| format | string | Optional | None | Bottle format hint used to route pricing logic. |
| condition | string | Optional | None | Bottle condition hint forwarded to the flow. |
| pack_size | number | Optional | None | Pack size (alias `packSize`) used for packaging adjustments. |
| currency | string | Optional | USD | Target currency for FX conversion; does not filter pricing sources. |
| flow_id | string | Optional | None | Specific pricing flow to run; defaults to the lowest-priority flow when omitted. |
Response Highlights
- `flow_id`: pricing flow identifier executed for the request.
- `price`, `bottle_price`, `adjusted_price`, `currency`: returned pricing with packaging adjustments when applicable.
- `data_source`, `aggregation`: source and aggregation used to derive the price.
- `applied_modifiers`, `path`: modifiers and routing path applied within the flow.
- `resolved_lwin`, `resolved_vintage`: resolved wine context.
- `confidence_score`, `record_count`: diagnostics for the derived price.
- `format_detected`, `case_size_detected`: detected packaging cues from the request.
- `trace`: per-node execution details including router matches and intermediate prices.
- Provide either `query` or `lwin` to resolve the wine; flows return 404 when no wine or price can be derived.
- Currency input only converts returned values; it never filters underlying records.
- When `flow_id` is provided that specific flow is used; otherwise the user’s lowest-priority pricing flow runs.
Product feedback
Report a problem with Wine Labs or suggest an improvement. Agents can send feedback directly from any HTTP client.
https://winelabs.ai/api/feedbackSubmit product feedbackSend JSON to the Wine Labs feedback inbox. No API key or credits are required. Describe what happened and what you expected. Omit personal details, credentials and chat transcripts.
{
"type": "bug",
"description": "Selecting EUR still displays prices in USD."
}Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| type | string | Required | None | Choose bug, feature, improvement, or general. |
| description | string | Required | None | A nonblank report of up to 2,000 characters. |
Response Highlights
- HTTP 201 confirms receipt. Save data.id as the feedback reference.
- Send each report once. If you receive HTTP 429, wait 15 minutes before trying again.