Market Data

Restaurant Listings

Restaurant 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.

post/restaurant_listings

Request

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

Request body

user_idstring uuid required

Authorized user identifier used for authentication and rate limiting.

restaurant_idnumber

Return the wine list of one restaurant. Get the id from Restaurant Details. Sufficient on its own.

lwinstring

LWIN of one wine. Returns the restaurants that list that wine. An LWIN11 also filters the vintage. Sufficient on its own.

wl_idstring

Wine Labs wine identifier. Same behaviour as lwin. Sufficient on its own.

citystring

City name used to match restaurant addresses (for example, New York or Paris).

statestring

State filter for restaurant location. Accepts a 2-letter abbreviation or recognized full state name (for example, CA or California).

latnumber

Latitude of the search origin point. Must be provided together with lng.

lngnumber

Longitude of the search origin point. Must be provided together with lat.

max_distance_milesnumber

Maximum search radius in miles when lat/lng are provided.

max_resultsnumber

Page size (1-20). Use offset to page through a longer list.

offsetnumber

Pagination offset. The response sets has_more when another page exists.

vintagestring[]

Optional vintage filter (e.g., ["2015", "2016"]).

formatstring[]

Optional bottle format filter (e.g., ["750ml", "1500ml"]).

countrystring[]

Optional country filter for restaurant location.

continentstring[]

Optional continent filter for restaurant location.

currencystring

Output currency for wine price conversion.

include_unmatchedboolean

Set to false to drop list lines we could not match to a Wine Labs wine.

Response

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_address, restaurant_country, restaurant_state: restaurant identification.
  • 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.

Notes:

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

Changes

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