Snooth Wine API Documentation

Ready to get started? Register here and get your API key. (License Agreement)

Check out our sample application which uses Snooth, Facebook, and Google Map APIs!

A. Description

I. Welcome

The Snooth API is a free, RESTful API that allows users to leverage the comprehensive Snooth wine database to create their own wine applications.

II. Best Practices

Use the API responsibly. One good rule of thumb is that you should request only the data that users of your application ask for.


When making calls that require user authentication, you will have to send user credentials in the URL. We recommend that you use the HTTPS protocol to ensure those credentials are secured.


You may construct your requests using the GET or POST methods. When using GET, it is a good idea to ensure you have not constructed a URL that is too lengthy for the protocol. This can be of particular concern when reviewing wines if your tasting note is long.

III. REST

Snooth's API is RESTful in nature and will require you to construct URIs that will return the data you want in the format you prefer.

IV. Example

An example of a search for wines using the Snooth API is as follows:


http://api.snooth.com/wines/?akey=<your api key>&ip=66.28.234.115&q=napa+cabernet&xp=30


This request will return a list of 10 Napa Cabernet Sauvignon wines priced under 30 USD, ordered by SnoothRank, in JSON format.

V. Bugs? Questions?

Please post a new discussion on our Snooth API Google Group with as much information as you can provide.

B. Methods

I. General Parameters

The following parameters can apply to any request.

akey Required.
Your Snooth API key.
format
Return format. Possible values: xml, json. Default: json.
ip
IP Address of the user making the request. This helps us make Snooth better and more location aware!
u
Username of the user making the request. Note: When sending authentication parameters we recommend the use of HTTPS.
p
Password of the user making the request. You may pass the MD5 of the password here. Note: When sending authentication parameters we recommend the use of HTTPS.

General return values.

results
All results contained in the result set.
returned
Number of results returned by the API call.
status
0 when there is an error and 1 when the API call is valid.
errmsg
An error that the API call generated.

II. Wine Search

To perform a search, use this method.

URL:

http://api.snooth.com/wines/

Parameters:

q
Your search. Set to "wine" to include all results.
f
The first result to return. Default: 1
n
Number of results. Possible values are 1-100. Default: 10.
a
Available. Set this to 0 to return all wines, or 1 to return wines in stock. The default is 1, so for many applications you need to set this to 0 to get the full set of wine results.
t
Product type. Possible values are one of: 'wine', 'spirits', 'table', 'dessert', 'sparkling', 'fruit', 'cider', 'sake'. Leave blank to include results for both wines and spirits.
color
Product color. Possible values are 'red', 'white', 'rose', 'amber', and 'clear'
m
Store ID. Limits results to wines available from this store. Will cause location-based parameters to be ignored.
c
Country. Limits results to wines available in this country. (List of supported countries)
z
Zip Code. When combined with certain countries this will return local results.
lat
Latitude. When combined with a longitude value, will return local results. If a Country parameter is included, this parameter will be ignored.
lng
Longitude. When combined with a latitude value, will return local results. If a Country parameter is included, this parameter will be ignored.
s
Sort. Possible values are sr (SnoothRank), price+asc, price+desc, qpr (Quality Price Ratio), vintage+asc, vintage+desc. Leave blank for recommended sort.
mp
Minimum price. Possible values are in full US dollars.
xp
Maximum price. Possible values are in full US dollars.
mr
Minimum SnoothRank (site rating). Possible values are any rational number in the range [0 - 5]
xr
Maximum SnoothRank (site rating). Possible values are any rational number in the range [0 - 5]
lang
Language. Only return wines with content in the specified language. Possible values: en, el, fr, de, it, pt, es. (Beta)

III. Create Account

Create a free Snooth account.

URL:

http://api.snooth.com/create-account/

Parameters:

e Required.
Email address of the account to be created.
p Required.
Password.
s Required.
Screen name.

IV. Rate and Review Wines

Post a rating or review to your Snooth account. This will always modify your most recent rating for the requested wine, or add a new review if you have not yet reviewed the wine. If you do not wish to overwrite a value do not pass it via GET or POST.

URL:

http://api.snooth.com/rate/

Parameters:

u Required.
Screen name/email of the user whose wines will be returned.
p Required.
Password of the user whose wines will be returned.
id Required.
The unique code for the wine to rate/review.
r
Rating. Possible values are between 0.0 and 5.0 by the half point.
b
Review body. Your textual review or tasting note.
v
Private. If set to 1 will make the review a private review.
t
Tags. Tag the wine with a comma separated string of tags.
w
Wishlist. Set to 0 for no or 1 for yes to change the wishlist status for this wine. If you do not pass this parameter the wishlist will remain unchanged.
c
Cellar Count. Pass this parameter to set the number of bottles in the user's cellar for this wine. If you do not pass this parameter the cellar will remain unchanged.

V. Wishlist Wines

This method will toggle your wishlist status for a wine. The API will return your wishlist status after making the modification.

URL:

http://api.snooth.com/wishlist/

Parameters:

u Required.
Screen name/email of the user whose wines will be returned.
p Required.
Password of the user whose wines will be returned.
id Required.
The unique code for the wine to add/remove from your wishlist.

VI. Wine Details

Get details about a specific wine.

URL:

http://api.snooth.com/wine/

Parameters:

id Required.
The unique code for the requested wine.
i
Inventory. Set this to 1 to return price information for the requested wine.
c
Country. Limits price data to wines available in this country.
z
Zip Code. When combined with certain countries this will return local results.
food
Food Pairings. Set this to 1 to return suggested recipe pairings for the requested wine.
photos
Wine Photos. Set this to 1 to return all images for the wine.
lat
Latitude. When combined with longitude this will return local results.
lng
Longitude. When combined with latitude this will return local results.
lang
Language. Return winery supplied content (Winemaker's Notes, Vintage Notes, etc) in the specified language. Possible values: en, el, fr, de, it, pt, es. (Beta)

VII. My Wines

Return list of wines the user has recently interacted with. These results are cached for 5 minutes. The filters allow for control of what is displayed. For example, if you want to see only your wishlist, use "&r=0&w=1&c=0".

URL:

http://api.snooth.com/my-wines/

Parameters:

u Required.
Username. Screen name/email of the user whose wines will be returned.
p Required.
Password. Password of the user whose wines will be returned.
n
Number of results. Possible values are 1-1000. Default: 10.
pg
Results page. Default: 1.
r
Show ratings. Default: 1.
w
Show wishlist. Default: 1.
c
Show cellar. Default: 1.

VIII. Store Search

To perform a search on local stores, use this method. A combination of country/zip code or latitude/longitude is required.

URL:

http://api.snooth.com/stores/

Parameters:

c
Country. Limits store data to stores located in this country.
z
Zip Code. When combined with certain countries this will return local stores.
lat
Latitude. When combined with longitude this will return local stores.
lng
Longitude. When combined with latitude this will return local stores.

IX. Store Details

Get details about a specific store.

URL:

http://api.snooth.com/store/

Parameters:

id Required.
The unique ID for the store.
r
Reviews. Set this to 1 to return store review information with the basic details.

X. Winery Details

Get details about a specific winery. Use the winery_id parameter returned by the API to request winery information.

URL:

http://api.snooth.com/winery/

Parameters:

id Required.
The unique ID for the winery.

XI. User Activity Feed

Get a list of recent user activities such as liking or rating wines.

URL:

http://api.snooth.com/action/

Parameters:

t
Action type code. Default: all types of user actions.
Valid Type Codes:

wine-review-add — Created a new wine review

wine-recommended — Liked/recommended a wine

created-list — Created a list

added-list-item — Added an item to a list

copied-list — Copied one list to a new list

b
Before date (YYYY-MM-DD HH:MM:SS). The date/time to search up to. Default: now.
f
First result. Default: 1.
n
Number of results. Default: 50. Maximum: 50.

Ready to get started? Register here and get your API key. (License Agreement)