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

Version 2: Released October, 2009.

Version 1 of the API is no longer supported.

Notes: The second release of the Wine-Searcher API takes advantage of recent changes to the search engine. The data returned has been refined removing unnecessary data providing cleaner more specific information.

Version 2 of the API will try to find a closest match wine for your query and only return information for that specific wine. Occasionally a closest match cannot be found so the search engine will automatically find all other matching wines using broader matching criteria. Recognising that you may wish to explicitly find all matches we provide a new parameter (Xwidesearch) to allow this (more information in the parameter explanation section below).

So what are the advantages of returning only the closest matches for a search? There are two key reasons for the new approach:

1. Average Price for a wine: The API is designed to provide third party applications simple access to the power of the Wine-Searcher search engine. A common and popular use is to find the average price for a specific wine. Providing only the closest match by default in a wine names list provides greater accuracy and simplicity for the third party application developers. If the third party application designers wish to show a more complete list the new Xwidesearch=Y parameter can be passed with the query.
2. Better price comparison: By default a wine list returned by the API will display merchant listings for only the closest match wines, not all wines containing the keywords. This provides more sensible and accurate price comparison. If the third party application designers wish to show a more complete list the new Xwidesearch=Y parameter can be passed with the query.

Schema Change: Version 2 of the API produces XML with a new schema definition. See API Outputs section below. Version 1 documentation is still available for review.

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.

Xversion

Optional. Valid values: 2
If this parameter is not supplied with a value you will receive version 2 results by default.

Xkeyword_mode

Optional. Valid values:

A Default – returns a 'wine list'.

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

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.

Xwidesearch

Optional. Valid values: Y or N (default)
This parameter tells the API whether to narrow the search down to only closest matches (Xwidesearch=N) or to widen the search to include the closest match AND all other matches (Xwidesearch=Y). If a 'closest match' is not found for a particular search the API will automatically 'widen' the search to find any other matching wines.

Xautoexpand New

Optional. Valid values: Y or N (default)
If the API search engine cannot find any results for a specific location you can set Xautoexpand=Y to tell the search engine to fall back to 'all countries' for the query. The list-location field in the XML document header will indicate the location of the result. By default Xautoexpand is turned off.

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)

4 - invalid access code (return-comment)

list-version

list-comment

list-currency-code

1. Vintage list:
View wine list schema (XSD)

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: Xversion=2; Xwinename=haut+brion; Xcurrencycode=USD. View sample vintage list output (XML).

Header fields:

Common fields listed above

Body fields <wine-vintage>

vintage

price-average

price-min

price-max

2. Wine Names list: (Use this list to find the average price for a wine).
View wine names list schema (XSD)

A list of the distinct wines found for your search phrase (and vintage, if included). By default we will return a single result for the closest match wine. If we cannot find a single match or Xwidesearch=Y is specified we will widen the search to include all other matches too.

Sample 1. (default - closest match only) Parameters: Xversion=2; Xkeyword_mode=X; Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD. View sample wine names list output (XML).

Sample 2. (wide search) Parameters: Xversion=2; Xwidesearch=Y; Xkeyword_mode=X; Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD. View sample wine names list output (XML).

Header fields:

Common fields listed above

Body fields <name>

wine-name

display-name

region

grape

price-average

price-min

price-max

3. Wine list:
View wine list schema (XSD)

A list of merchants, their wine descriptions and their prices matching 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 1. (default - closest match only) Parameters: Xversion=2; Xkeyword_mode=U (Exclude auctions); Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD; Xlocation=USA; Xstate=CA. View sample wine list output (XML).

Sample 2. (wide search) Parameters: Xversion=2; Xwidesearch=Y; Xkeyword_mode=U (Exclude auctions); Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD; Xlocation=USA; Xstate=CA. View sample wine list output (XML).

Header fields:

Common fields listed above, plus;

list-location

list-state

Body fields <wine>

merchant

merchant-description

wine-description

vintage

price

bottle-size

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.