Wine-Searcher API Documentation

Please contact us if you wish to start using the Wine-Searcher API.

The Wine-Searcher API enables integration of our comprehensive wine search engine with your applications.

Queries are passed to Wine-Searcher via URLs constructed and submitted using the HTTP protocol, just like a web page. Results are returned in XML allowing you to format the information as you wish.

Use this API if you wish to;

• Show the average or min/max prices for wines within your own website or application.
• Allow your users to see where they can buy a wine.

Potential users of Wine-Searcher's API are: Wine websites, blogs, wine content providers, mobile solution providers, market research companies and anyone interested in wine information.

If an API is too technical or complicated for your needs, you can still put our search on your site.

Currently Wine-Searcher has a single API that provides three outputs (a vintage list, a wine names list and a wine list) depending on the parameters passed in. A description of the paramters and outputs follows;

Use of the Wine-Searcher API is subject to the Wine-Searcher API Terms of Use. You may only use the API if you agree to, and abide by, the Terms of Use.

Wine-Searcher accepts Latin1 (ISO-8859-1) encoding for API requests. 8-bit characters are NOT allowed - they must be represented using % notation (often called URL escaping). For a technical explanation please view the Wikipedia document on percent encoding. Failure to URL escape special characters (such as European characters common in wine names) when querying the Wine-Searcher API will most likely result in 0 wines being returned because our server does not interpret the query correctly.

Parameter explanation:

Parameters are passed as querystrings to our base API URL (contact us for this URL).

Parameters are case sensitive.

Xaffiliate

Required. If this parameter is not supplied with a value you will not receive any results. Please contact us to be assigned an Xaffiliate value to pass with each API request.

Xkeyword_mode

Optional. Valid values:

A Default – returns a 'wine list'.

X Exact match – returns a 'wine names list'.

R Exact match, used with Xwinename and Xwinenameid - returns a 'wine list' for a specific wine. See the sample below.

U Exclude auctions – returns a 'wine list'.

T Auctions only – returns a 'wine list'.

Xwinename

Either this or Xvintage is required. If this is not supplied you will receive a list of all the wine names that match the specified vintage.

Xvintage

Either this or Xwinename is required. If this is not supplied you will receive a list of all vintages for the wine (unless there is only one vintage found for the wine phrase).

Xlocation

Optional, but recommended Country of merchant. Filters the search to only show wines from merchants located in the specified country. For example, enter 'United Kingdom' to only search for wines from UK merchants.
Defaults to IP country. We recommend you pass this value through.

To obtain the list of valid values view the source of this page, scroll towards the bottom and note the values in the Xlocation select control.

Xip

Optional. IP address to be used to determine the country of origin. Can be used instead of Xlocation. Xlocation takes precedence if both are present.

Xstate

US only – optional. Valid values: ANY, R. (Reciprocal), plus all the 50 state abreviations.

To obtain the list of valid values view the source of this page, scroll towards the bottom and note the values in the Xstate SELECT field.

Xcurrencycode

Optional but recommended. A limited subset of ISO currency abbreviations. Defaults to currency of IP country or USD if currency code not in our valid list.

To obtain the list of valid values view the source of this page, scroll towards the bottom and note the values in the Xcurrencycode SELECT field.

Xwinenameid

Optional. Only supply this if you know the Wine-Searcher winenameid – available by retrieving a names list as a result of an 'exact match' search or a vintage only search. If you do not know the winenameid leave it out.

Xfirstwine

Optional. First wine to display. Valid values: 1 to max wines.

Xwinecount

Optional. Defines the maximum number of results to return. Note, our API will only ever return a maximum of 50 results for 'wine list', 2000 for the 'names list' and all possible vintages in the 'vintage list.

Wine-Searcher API Outputs:

The following provides a description of the XML fields included in each of the three sets of results, starting with a list of the fields common to all.

Common fields across outputs:

Header fields:

return-code

0 - success, wines found (no return-comment)

1 - no wines found (return-comment)

2 - input values error (return-comment)

3 - error our end (return-comment)

return-comment

list-comment

list-type

list-currency-code

list-currency-prefix

list-currency-symbol

list-count

list-total-count

list-max-count

1. Vintage list:
A list of all the available vintages we find (if more than one vintage is found) for a given wine search phrase. This output is the result of not passing a value in the Xvintage parameter.
Sample. Parameters: Xwinename=cloudy+bay; Xcurrencycode=USD. View sample vintage list output

Header fields:

Common fields listed above

Body fields <wine-vintage>

vintage

price-average

price-min

price-max

wine-name-id

2. Wine Names list:
A list of the distinct wines found for your search phrase (and vintage, if included). The wine-name-id output can be used in a subsequent call to the API if desired.
Sample. Parameters: Xkeyword_mode=X; Xwinename=cloudy+bay; Xcurrencycode=USD. View sample wine names list output

Header fields:

Common fields listed above

Body fields <name>

description

price-average

price-min

price-max

wine-name-id

3. Wine list:
A list of merchants, their wine descriptions and the price that match your search criteria. The link URL allows you to browse directly to the merchant's wine detail page (or home page if a detail page does not exist).
Sample. Parameters: Xkeyword_mode=R; Xwinename=cloudy+bay; Xvintage=2007; Xcurrencycode=USD; Xwinenameid=33510; Xwinecount=10. View sample wine list output

Header fields:

Common fields listed above, plus;

list-location

list-state

list-names-count (the number of distinct wines)

list-price-average (Y/N)

list-price-range (Y/N)

Body fields <wine>

merchant

merchant-id

merchant-description

wine-description

vintage

price

bottle-size

wine-name-id

link

Issues? Need more help?

We are always interested to hear of any issues you have or to provide additional help to integrate our API into your application.