Snooth 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 send an email to tech@snooth.com 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.
f
The first result to return. Default: 1
n
Number of results. Possible values are 1-1000. Default: 10.
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.
a
Available. Set this to 1 to return wines in stock. Default: 0.

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.

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 rate/review.

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.
lat
Latitude. When combined with longitude this will return local results.
lng
Longitude. When combined with latitude this will return local results.

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

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