Our API allows you to plug Wine?Searcher data directly into your website or application. Typical API consumers are wine apps, websites, blogs, market research companies and those specializing in wine investments, valuations and insurance. For any wine currently available in our database, the API can supply all kinds of information including retail suppliers, prices, scores and available vintages.
This page is intended for developers. More general information and pricing on the API can be found on the Use Our API page. Please contact us to apply for a trial API Key.
The API is a RESTful web service. Queries are passed via URLs constructed and submitted using the HTTP protocol (specifically the GET method), just like a web page. Results can be returned in either XML (default) or JSON format.
URL Encoding & Prohibited Characters
- To minimise potential errors we suggest 8-bit characters to be encoded with percent encoding ('URL escaping').
- Percent (%) and slash (/) symbols used in parameter values must be percent encoded otherwise requests will fail or produce unexpected results.
- Parameter names and values are case-sensitive, excluding wine name which can be mixed case.
Parameters are case-sensitive, and are passed as querystrings to our base API URL. We have created a number of optional parameters, but for every API call two parameters are compulsory: api_key and winename.
||A valid API Key
||An API Key is generated when you signup for a free trial.
||Keywords used to describe a wine, spirit or beer.
||Four digit decimal
||The vintage of the wine.
Use NV for Non-Vintage.
Use 2 for 'any' vintage.
|X = results given in XML format.
J = results given in JSON format.
|Prices from Auctions Houses.
[empty] - return prices from all merchant types, including auctions
N - exclude auctions
Y - show auctions only
|This parameter should only be used on the 'Marketplace API'. Using it with the 'Price Check API' will return an error.
||Any location from the drop-down in our website's wine search form
||Specifies a country in which to search.
E.g. location=USA to search within the USA, location=Europe to search within Europe.
|We recommend you pass this value with each query to obtain the most meaningful results.
|Tells the search engine to expand the search to 'All Countries' if no results are found in the location specified in the call. If the location specified in the call is a US state, the search will autoexpand to 'USA'.
||Specifies a geographical location for the search (in combination with longitude).
||Overrides all other location parameters.
||Specifies a geographical location for the search (in combination with latitude).
||Overrides all other location parameters.
||ANY, or one of the 50 US state abbreviations
||If state AND zipcode are passed in the request, zipcode will take precedence.
||Any valid Zip Code
||zipcode is used with location parameter; zipcode is only applied if location=USA.
||Distance in miles
||Define a search radius of x miles around the Zip Code given in zipcode.
||Valid ISO currency code
||A subset of ISO currency abbreviations (see change currency page for the currencies we support). Defaults to USD.
|a = All bottle sizes
b = Bottles
c = Cases
h = Half Bottles
m = Magnums
dm = Double Magnums
o = Other sizes
|This parameter should only be used on the 'Marketplace API'. In the 'Price Check API' the parameter will act as a filter, but has no impact on the values returned.
The following describes the fields included in each of the result sets, starting with a list of the fields common to all.
Common fields across outputs:
0 - Success, wines found
1 - No matching wines were found
2 - Input values error
3 - Error, database timeout
4 - Invalid access code
5 - Exceeded Limit
6 - Access Denied
7 - Subscription Ended
8 - Keywords match multiple wines
10 - Can not access Price Check data / Marketplace data
99 - Unknown error
1. Price Check API
A list of product names matching your search phrase. The list is limited to those products currently available from merchants in our database. If vintage and location are specified in the parameters, the list will be further narrowed down by availability. We aim to return a single closest-match result.
<Price Check API Base URL>?api_key=<API_Key>&winename=haut+brion&vintage=1995¤cycode=USD
Common fields listed above
score (Wine-Searcher aggregated critic score)
2. Marketplace API
A list of wine offers (prices) matching your search criteria. Includes the merchant's name, price, location, contact details and URL.
<Marketplace API Base URL>?api_key=<API_Key>&winename=haut+brion&vintage=1995¤cycode=USD&location=USA&state=CA
Common fields listed above, plus;