Wine-Searcher API Documentation

This page is intended for IT developers or programmers. If you have consulted the information below and are happy to comply with our API Terms of Use please complete this simple online form.

Our free API enables you to integrate your application with our comprehensive wine search engine. It generates three key outputs:

• the list of vintages available for a wine (from our full data).
• the ex-tax average, min. and max. prices for a wine (from our full data).
• a list of suppliers and prices for a particular wine (from our restricted free-for-use data).

The principal users of the Wine-Searcher API are wine websites, blogs, wine content providers, mobile solution providers and market research companies. Access is free for up to 5000 requests per day. If an API is too complicated for your needs, here are some simple (but effective) ways to integrate with Wine-Searcher.

The Wine-Searcher API is a RESTful web service. Queries are passed to the API via URLs constructed and submitted using the HTTP protocol (specifically the HTTP GET method), just like a web page. Results are returned as XML or JSON data, allowing you to format the information as you wish.

• Wine-Searcher accepts Latin1 (ISO-8859-1) encoding for API requests.
• 8-bit characters must be represented using the appropriate percent encoding (or 'URL escaping').
• Percent encoding must be used for all special characters (e.g. accented characters like â, é, í, ò and ü).
• Percent ‘%’ and forward slash ‘/’ symbols used in any way other than percent encoding will cause API requests to fail.

Parameter explanation

Parameters are passed as querystrings to our base API URL. The URL will be supplied when you are assigned an API key.

Parameters are case sensitive.

Required parameters:

Xkey

Required. If this parameter is not supplied with a value you will not receive any results. Please Submit an online request to be assigned a Xkey value (API Key) to pass with each API request.

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

Show additional parameters ... >>

Additional parameters:

Xversion

Optional. Valid values:

2 Specify Xversion=2.

3 Specify Xversion=3.

4 (Default) The current default if Xversion parameter is not supplied.

5 Specify Xversion=5.

Xformat

Optional. Valid values:

X (Default) - results in XML format.

J Results in JSON format.

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

Xwidesearch

Optional.
This parameter tells the API whether to narrow the search down to the single exact match (suitable for valuations, Xwidesearch=V), only closest matches (suitable to find the single 'closest match' if possible or a list of 'closest matches' for the specified criteria, Xwidesearch=N) or to widen the search to include the closest matches AND all other assorted matches (Xwidesearch=Y).
Valid values:

N (Default) - attempts to restrict the search to the 'closest match'. If a 'closest match' cannot be found then a list of other 'close matches' will be returned.

Y Wide search - widens the search to return as many results as possible for the phrase, vintage and lcoation specified.

V Valuation - Only returns results for the exact wine you have searched for. If the wine cannot be found for the phrase, vintage or location specified no results will be returned.

Xlatitude

Optional (available from version 5). Decimal degress, specifying the north-south position of a point on the Earth's surface.

Must be used with Xlongitude parameter.

Other location parameters are ignored if Xlatitude and Xlongitude are present.

Xlongitude

Optional (available from version 5). Decimal degress, specifying the east-west position of a point on the Earth's surface.

Must be used with Xlatitude parameter.

Other location parameters are ignored if Xlatitude and Xlongitude are present.

Xmiles

Optional (default = 100, available from version 5). Number specifying the proximity from the latitude and longitude in which to search for wine stores.

Only valid when used with Xlatitude and Xlongitude parameters.

Xnearest

Optional (available from version 5). Valid values: Y or N (Default)

When used with Xlatitude and Xlongitude the API will attempt to find the closest store selling the wine matching Xwinename and Xvintage.

Only valid when used with Xlatitude and Xlongitude parameters. Takes precedence over Xmiles if both are present.

Xlocation

Optional Country of merchant. Filters the search to only show wines from merchants located in the specified country. For example, enter 'UK' to only search for wines from UK merchants, 'USA' for USA based merchants, 'France' for French merchants, and so on. Refer to the Wine-Searcher website search box for the complete list of available location values.
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.

Xstate

US only - optional. Only applicable if Xlocation='USA'. 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.

If Xstate AND Xzipcode are passed in the request, Xzipcode will take precedence.

Xshipto

Optional. Valid values: Y or N (Default)
When Xstate is specified as a valid US state abbreviation and Xshipto=Y the API will return results for merchants based in the specified state plus all merchants who can 'ship to' the specifed state.

Xzipcode

US only - optional. Only applicable if Xlocation='USA'. Valid values: Any valid Zip Code.

To check or find a valid Zip Code please refer to the United States Postal Service website.

Xzipmiles

US only - optional. Specify the proximty in miles from the Zip Code to search. Valid values: 0 (search Zip Code only) or any positive number.

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.

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.

Xautoexpand

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.

If Xautoexpand=Y and no wines can be found in a specified Zip Code (Xlocation=usa&Xzipcode=[valid Zip code]) then the search will automatically expand to all USA only, not all countries.

Xwinecount

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

Xcallback

Optional. Only valid when requesting results in JSON format (Xformat=J). Used to define a javascript callback function name to 'wrap' the JSON data returned by the API request. If Xcallback is blank or not specified, regular JSON data is returned.

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

1 - no wines found

2 - input values error

3 - error, database timeout

4 - invalid access code

5 - invalid version, version not supported

99 - unknown error

list-version

list-comment

list-location

list-state

list-currency-code

1. Vintage list:

A list of all the available vintages we find for a given wine search phrase. A vintage list is returned if no value is passed in the Xvintage parameter, and if more than one vintage exists for the wine.

More information ... >>

Sample. Parameters: Xwinename=haut+brion; Xcurrencycode=USD. View sample vintage list output as XML or JSON.

Header fields:

Common fields listed above

Body fields <wine-vintage>

vintage

price-average

price-min

price-max

2. Wine Names list:

This is useful for valuations as it shows ex-tax average prices

A list of the distinct wines matching your search phrase (and vintage and location, if included). By default we 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. If we cannot find a single match AND Xwidesearch=V is specified, no results will be returned (important for valuations to ensure you don't get an incorrect value for your wine).

More information ... >>

Sample 1. (default - closest match only) Parameters: Xkeyword_mode=X; Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD; Xwidesearch=N or Xwidesearch=V. View sample wine names list output as XML or JSON.

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

Header fields:

Common fields listed above

Body fields <name>

wine-name

region

grape

price-average

price-min

price-max

3. Wine list:

A list of merchants, their contact details, their wine descriptions and their prices for the wines 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).

More information ... >>

Sample 1. (default - closest match only) Parameters: Xkeyword_mode=A; Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD; Xlocation=USA; Xstate=CA; Xshipto=Y. View sample wine list output as XML or JSON.

Sample 2. (wide search) Parameters: Xwidesearch=Y; Xkeyword_mode=U (Exclude auctions); Xwinename=haut+brion; Xvintage=1995; Xcurrencycode=USD; Xlocation=USA; Xzipcode=10001; Xzipmiles=20. View sample wine list output as XML or JSON.

Header fields:

Common fields listed above, plus;

Body fields <wine>

merchant

merchant-description

physical-address (v3+)

zip-code (v3+)

zip-code-miles (v3+)

latitude (v4+)

longitude (v4+)

geo-miles (v5+)

country (v3+)

state (v3+)

contact-phone (v3+)

wine-description

vintage

price

bottle-size

link

List Selection:

The Xwinename, Xvintage and Xkeyword_mode together determine which kind of output list is returned in response to an API call.

More information ... >>

Xwinename	Xvintage	Xkeyword_mode	Result
absent	absent,0,1,2	any	Invalid
absent	>2	A,U,T	Wine Names List
present	absent,0,1	A,U,T	Vintage List
present	>1	A,U,T	Wine List
present	any	X	Wine Names List

Wine-Searcher API Release Notes

Version 5: Released June 2012.

Version 4: Released June 2011.

Version 3: Released October 2010.

Version 2: Released October 2009.

Issues? Need more help? Contact us.