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.
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.
| Parameter | Valid values | Description | Note |
| api_key | A valid API Key | An API Key is generated when you signup for a free trial. | Required |
| winename | String | Keywords used to describe a wine, spirit or beer. | Required |
| vintage | Four digit decimal | The vintage of the wine. | Required Use NV for Non-Vintage. Use 2 for 'any' vintage. |
| format | X (default) J |
X = results given in XML format. J = results given in JSON format. |
- |
| auction | [empty] (default) N (No) Y (Yes) |
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. |
| location | 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. |
| autoexpand | N (default) Y |
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'. | - |
| latitude | Decimal degrees | Specifies a geographical location for the search (in combination with longitude). | Overrides all other location parameters. |
| longitude | Decimal degrees | Specifies a geographical location for the search (in combination with latitude). | Overrides all other location parameters. |
| state | ANY, or one of the 50 US state abbreviations | If state AND zipcode are passed in the request, zipcode will take precedence. | USA only. |
| zipcode | Any valid Zip Code | Applicable only if location=USA. | USA only. |
| zipmiles | Distance in miles | Define a search radius of x miles around the Zip Code given in zipcode. | USA only. |
| currencycode | Valid ISO currency code | A subset of ISO currency abbreviations (see change currency page for the currencies we support). Defaults to USD. | Recommended parameter. |
| bottle_size | a (default) b c h m dm o |
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:
Header fields:
return-code
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
list-comment
list-location
list-state
list-currency-code
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.
A list of wine offers (prices) matching your search criteria. Includes the merchant's name, price, location, contact details and URL.
Example:
<Marketplace API Base URL>?api_key=<API_Key>&winename=haut+brion&vintage=1995¤cycode=USD&location=USA&state=CA
Header fields:
Common fields listed above, plus;
list-count
Body fields:
merchant-name
vintage
price
merchant-description
physical-address
country
state
zip-code
latitude
longitude
bottle-size
link