Wine-Searcher API documentation

	One of our sponsors is:
	Wine-Searcher Wine API Documentation The API documentation in this page is intended for IT developers or programmers. Please contact us if you wish to start using the Wine-Searcher Wine API. Description The Wine-Searcher Wine API enables integration of our comprehensive wine search engine with your applications, for free. Queries are passed to the Wine API via URLs constructed and submitted using the HTTP protocol, just like a web page. Results are returned in XML or JSON, allowing you to format the information as you wish. Use this API if you wish to: Show the average or min/max prices (ex-tax) for wines within your own website or application. Value the wines in your private cellar. Allow your users to see where they can buy a wine. Potential users of Wine-Searcher's Wine 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 integrate with Wine-Searcher by using our web widgets or search box. The Wine API provides three outputs (a vintage list, a wine names list and a wine list), depending on the parameters supplied. A description of the parameters and outputs follows. Use of the Wine-Searcher Wine 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. URL Encoding 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. Required parameters: 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. 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. Xformat Optional. Valid values: X (Default) – results in XML format. J Results in JSON format. 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. 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. Xlocation Optional, but recommended 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 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 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 (if more than one vintage is found) for a given wine search phrase. A vintage list is returned if no value is passed in the Xvintage parameter where 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 (use this list to find the average price ex-tax for a wine – useful for valuations): A list of the distinct wines found for your search phrase (and vintage and location, 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. 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 zip-code zip-code-miles latitude longitude country state contact-phone wine-description vintage price bottle-size link Wine-Searcher API Release Notes Version 4: Released June 2011. More information The display-name has been removed from the wine names list because it is now redundant (returns the same value as the wine-name field). The wine list returns two new fields related to the merchant selling the wine: latitude and longitude. Version 3: Released October 2010. More information By popular demand we are now returning results from the API in JSON format. We expect this will allow greater flexibility to developers, particularly when wanting to query the API via AJAX. A wine list now returns more information about the merchant selling the wine, including the physical address and their contact phone number. The Xwidesearch parameter has a new valid value, V, intended to be used for valuations. If Xwidesearch=V the API will only return results for the exact wine matching the specified criteria. If an exact match cannot be found we will not return any results. Version 2: Released October 2009. More information From version 2 the API attempts 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 parameter (Xwidesearch) to allow this (more information in the additional options of parameter explanation section above). So what are the advantages of returning only the closest matches for a search? There are two key reasons for this approach: 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 (ex-tax) 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. 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. 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.

Search for any wine here.

Wine-Searcher Wine API Documentation