Market Data

Listings

Retrieve active merchant offers with optional geography and packaging filters.

post/listings

Request

  • Base URL: https://external-api.wine-labs.com
  • URL: https://external-api.wine-labs.com/listings
  • Auth: none declared

Request body

querystring

Free-text wine description. Required when lwin is not provided.

lwinstring

Direct LWIN lookup. Required when query is not provided.

user_idstring uuid required

Account identifier issued during onboarding; used for authentication and quota tracking.

currencystring

ISO currency code used for price conversion.

regionstring

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_merchantsboolean

Filter to merchants designated as trusted partners.

continentsstring[]

Restrict listings to the provided continents.

countriesstring[]

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_formatsstring[]

Filter by internal format labels (alias: formats). Allowed values: bottle, half-bottle, magnum, double-magnum.

vintagesstring[]

Filter to specific vintages.

min_offer_volumenumber

Minimum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.

max_offer_volumenumber

Maximum pack size filter (1–99). When absent and an 18-digit LWIN is provided, inferred from the LWIN case-size segment.

limitnumber

Page size (1–20).

offsetnumber

Pagination offset (>= 0).

Response

Response highlights:

  • lwin: resolved LWIN used for the search.
  • limit, offset, count, has_more: pagination metadata.
  • results[]: array of merchant offers including pricing, merchant contact details, formats, and analytics flags.

Notes:

  • 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.
object required

Changes

No recorded changes to this operation across all 1 revision of this API.