RateBeer

RateBeer API



RateBeer allows for JSON interaction for web developers looking to implement dynamic content from RateBeer or mobile applications that allow RateBeer users to better interact with the site via mobile device.
More info on JSON is available here.
http://www.json.org/




Please Do

Get a developer key, it's now required and use it in your query string in the form:

&k = [developer key]

Follow the rules. We're all working together.

Share your creations with us. We can help promote them.

Provide feedback, especially if you've found a glitch or could use something





Please Don't

Hammer the site with repeating, recursive or otherwise demanding requests

Build a remote database of our copyrighted content

Share your developer keys





Beers List



I've created an updating list of beers with beer name, BeerID and searchable field here:

http://www.ratebeer.com/documents/downloads/beers.zip

It's recreated automatically every Saturday morning.





Below are the scripts available with instructions for use. If you have any questions or would like a custom script, please ask!
Send me an email – joet@ratebeer.com.




===================================================================

User remote login


http://www.ratebeer.com/Signin_r.asp


receives via post...

username = user name
pwd = password
saveinfo = whether to assign a cookie to the browser (bit)
redirect = redirection URL at your site to process post log in

script will return the user to the above redirect script with the following querystring info

uid = RateBeer User ID

You can then store the user ID in a cookie or session variable to use with subsequent query requests.

=================================================================

Beer Stuff


Beer search by string
http://ratebeer.com/json/bff.asp?bn=franci
vg = 1 Show averages
rc = 1 Show number of ratings


Beer lookup by beerid
http://ratebeer.com/json/bff.asp?bd=12

Flags
t = 1 Show Descriptor tags
ps = 1 Show Producer Style
vg = 1 Show averages
sid = 1 Show Beer Style ID
cid = 1 Show Country ID
rc = 1 Show rate count (number of ratings)
oo = 1 Show One Off value (1 is a one off, non rateable beer)


Saving A Beer Rating
http://www.ratebeer.com/m/m_saverating.asp

post the following...

BeerID         = bid
Aroma         = aroma
Appearance  = appearance
Taste         = taste
Mouthfeel = mouthfeel
Overall     = overall
Comments = co

UserID is verified via session variable



Beer Ticking
http://www.ratebeer.com/json/bt.asp

An end user can add a star rating to a beer in order to mark it for later review, tick it as having been drunk, and have available for future reference. This can only be done through the API for now and is not available via the web site. This will probably change.

m is the variable for Mode with values from 1-4 and relates to the following
' - 1 VIEW A USER'S TICKS
' - 2 ADD/UPDATE A TICK
' - 3 DELETE A TICK
' - 4 AVERAGE TICK SCORE OF A BEER
' - 5 VIEW A BEER'S TICKERS

b = the beer's BeerID
l = star rating from 1-5 used when adding a rating
u = is the UserID and is verified via session variable or can be sent explicitly to view ticks

In lieu of a UserID, an IP address can be used to store Beer Ticks. This is done by setting the Mode (m = 2) and sending values for a BeerID (b = BeerID) and the star rating (l = 1-5) and with no value for UserID (u), while the end user is not logged in.



Add A Beer
/json/enter-beer.asp

REQUIRED
{ BrewerID = bw
BeerName = bn
BeerStyleID, see style Ids in the appendix = bs
User must be logged in
}

OPTIONAL {
ABV, alcohol by volume, float = abv
Seasonal = s (0 Not A Seasonal, 1 Winter, 2 Spring, 3 Summer, 4 Autumn, 5 Special, 6 Series)
OneOff (Not a verifiable RateBeer unique beer. Either a one time festival or tap only variant of an existing beer.) = oo (1 = one off, 0 (default) = new beer, not a one off)
UPC, 8, 12 or 13 numbers = upc
IBUs, numeric = ibu
Producer Style (what the brewer calls the beer style), string 75 - character max = ps
Commercial Description, text, less than 1000 characters = d
}
The BeerID for the entered beer is returned or an error if there was an error.

Best By Style
/json/style.asp
Returns top 25 by beer style
s = StyleID


---------
Best Beers By Country
/json/bcc.asp
Shows best beers by country. Optional userid shows best you haven't had.
u = userid (optional)
c = country id
----------------
Get Top Beers

/json/tb.asp

Top 50 worldwide
Top 50 beers by season
Top 50 beers by country


    m  = mode. "season", "country" or "top50"
    u = userID, sent so that a user knows if they've had it or not (for top50 and country only)
    s = sort type (for top50 only, 1= by rating, 2 = by alpha)
    season = season integer (1-4 for winter through fall for season only)
    c = countryID (see below bottom for country values for country only)

----------------

Beer images are available (when available) from /beerimages/[beerid].jpg
Current images from Cloudinary are more complete. The URL structure is http://res.cloudinary.com/ratebeer/image/upload/w_250,c_limit,q_85,d_No%20image/beer_[BeerID].jpg
----------------
Get Ratings (Reviews) For A Beer

/json/gr.asp

    bid = BeerID
    uid = UserID  (if you wanted to show a rating from a single user)
    s = sort (optional, 1= latest, 2 = top raters, 3 = highest ratings )
    p = page number (this is optional and designated the page of ratings you'd like to view. 10 per page.)

----------------

Event Beers Check
checks a set of users against a set of beers and returns ratings.
/json/event.asp
example
http://www.ratebeer.com/json/event.asp?u=954-195&b=3211-1124-312766
u = list of dash-separated user IDs
b = list of dash-separated beer IDs
note: both lists can have a max of 32 items


Show me Rate Counts of a Beer
http://ratebeer.com/json/rc.asp?bid=54
    BeerID      = bid

New Beers
http://ratebeer.com/json/nb.asp?d=10/01/2009&p=1
p = Page Number, integer
d = date (format is Microsoft, American)


Beer availability search by beerid
http://ratebeer.com/json/where.asp?bd=12
bd = BeerID

Add Beer availability (user must be logged in)
http://ratebeer.com/json/where.asp?bd=12&pd=66
bd = BeerID
pd = PlaceID



Advanced beer search by string
http://ratebeer.com/json/bff.asp?b=franc&u=userid
u=UserID
t = 1 Show Descriptor tags


Brewer Stuff


Show Brewer Info
http://ratebeer.com/json/bi.asp
    BrewerID   = b

Show all the Beers by a Brewer
http://ratebeer.com/json/bw.asp
    UserID        = u (optional)
    BrewerID   = b
    Sort       = s (optional)

Brewer Lookup by ID
http://ratebeer.com/json/bss.asp?bd=11


Brewer Search by Name
http://ratebeer.com/json/bss.asp?bn=anchor

search string (4 characters min) = bn
StateID     = sid (optional)
First Letter = l (optional)


===========================================================================

Place Stuff



Place Check-in
http://www.ratebeer.com/json/ci.asp


An end user can check in to a place, and check-ins at a place can be viewed. Multiple check-ins to the same place are protected against (8 hour protection window).

t Type of call. Currently accepted values are either “View” for viewing check-ins of a Place or “Log” for logging a check-in.
p The PlaceID
The UserID is available to the system only via session variable. Users must be logged in to check in.
To check in, simply request the JSON script with a PlaceID (p=PlaceID) while the end user is logged in and with the Type set to “Log” (t=Log). The user will be checked in to the place or an error will be sent in the reply.
To view the check-ins at a place, the script is called using Type “View” (t=View) and by setting p equal to the PlaceID.

-----------------
Beers Available At Place
/json/beershere.asp
get beers at places by place id..
pid = place id

-----------------
PlaceSearch
/json/psstring.asp
search for places by string. Helps if you send western characters.
s = place search string

Place info by id
http://ratebeer.com/json/pss.asp?pid=101



Beer Places available by Geo
http://ratebeer.com/json/beerme.asp?mi=15&ci=Chicago
    Miles Radius    = mi
    City     = ci
    Latitude         = la
    Longitude         = lo


===========================================================================

Misc Stuff



Beer Image Check
/json/piccheck.asp
Checks to see if a beer image exists.
Example:
http://www.ratebeer.com/json/beercheck.asp?bid=213
returns: BeerID : [your sent beer id]
ImageExists : ("True" or "False")
----------------------------------------------------------------------------------------------
UPC Search
/json/upc.asp
Returns top two matches of UPC to Beer.
Example:
http://www.ratebeer.com/json/upc.asp?upc=636251770128
upc = UPC
----------------------------------------------------------------------------------------------
Add UPC /Bar Code for a Beer (user must be logged in, please add UPCs after unsuccessful searches!)
/json/upc.asp
http://www.ratebeer.com/json/upc.asp?upc=636251770128&bid=8821
upc = bar code, no dashes or spaces
bid = beerid
===========================================================================

User Stuff



-----------------
List Of Latest Messages (requires user log in)
/json/msg.asp
max = maximum number of latest message (use 1 to check for recent unread messages)
u = user id


-----------------
Personal Message View (requires user log in)
/json/message-view.asp
mid = message id
u = user id
r = (1, 0) (1 = get replies, 0 = get original message)


-----------------
Get Friends, Buddies
/json/bud.asp

u = UserID; Script will pick up userID (requires login)

-----------------
User Activity Feed
/json/feed.asp
m = view mode (0 = friends (requires login), 1 = global, 2 = local (requires login), 3 = just this user (send u = userid)
lid = show events since last ID (max 500)
u = UserID


-----------------
Get Top Users
/json/topusers.asp
Returns the top users
p = page number
r = records per page (30 max)
----------------
Get Recent Raves

/json/raves.asp

no parameters

----------------

Get Recent Ratings

/json/ratpag.asp

r = number of records to return (optional, max is 30)

no other parameters
----------------



===============================================================

FORUMS


http://www.ratebeer.com/json/f_forum.asp
f = forum ID
m = Mode (1-3)
1 = Get the current topics in a forum; requires forum ID
2 = Get all recent topics. If user is logged in, will show his or her subscribed forums, otherwise default subscriptions
3 = Show a thread; requires a topic ID
p = Page number
t = Topic ID

Modes 1 and 2 show the column headings
Mode 3 column headings for a Topic message are: FORUM_ID, F_SUBJECT, T_SUBJECT, T_MESSAGE, T_AUTHOR, UserName, Membership, RateCount, PlaceRatings, LastPost, T_REPLIES
The author info above relates to the author of a particular reply.
The replies to the topic will contain the column headings in the JSON reply.


===============================================================
User Info
http://ratebeer.com/json/users.asp
either
u = send a user name (string) returns a UserID
uid = send a user ID (integer) returns a UserID
uid = send a user ID (integer) WITH PARAMETER X=1 returns a UserID, UserName
uid = send a dash delimited bunch of userIDs and returns UserID, username and ratecount

All User Beer/Place Reviews* http://ratebeer.com/json/revs.asp
m = Mode (BR for beer ratings, PR for place ratings)
x = 1 (extended info)
p = Page number
* IMPORTANT: May not be transferred from application or mobile device. May not be used with web applications.

Show me Rate Counts of a User
(returns place ratings and beer rating counts)
http://ratebeer.com/json/rc.asp?uid=954
    UserID      = uid

  

Show me Rate Counts of a Place
http://ratebeer.com/json/rc.asp?pid=110
    PlaceID      = pid




More Reference


Get Brewers list for offline searching
http://www.ratebeer.com/documents/downloads/brewers03032010.csv


Brewer Types
1 Commercial Brewery
2 Microbrewery
3 Brew Pub
4 Brew Pub/Brewery
5 Contract Brewer
6 Meadery
7 Sake Producer
8 Cidery
9 Client Brewer

List Of Country Codes
value = 39 Canada
value = 240 England
value = 213 United States

value = 1 Afghanistan
value = 2 Albania
value = 4 Algeria
value = 5 American Samoa
value = 6 Andorra
value = 7 Angola
value = 8 Anguilla
value = 9 Antigua & Barbuda
value = 10 Argentina
value = 11 Armenia
value = 12 Aruba
value = 13 Ascension Island
value = 14 Australia
value = 15 Austria
value = 16 Azerbaijan
value = 17 Bahamas
value = 18 Bahrain
value = 19 Bangladesh
value = 20 Barbados
value = 22 Belarus
value = 23 Belgium
value = 24 Belize
value = 25 Benin
value = 26 Bermuda
value = 27 Bhutan
value = 28 Bolivia
value = 29 Bosnia
value = 30 Botswana
value = 31 Brazil
value = 32 British Virgin Islands
value = 33 Brunei
value = 34 Bulgaria
value = 35 Burkina Faso
value = 36 Burundi
value = 37 Cambodia
value = 38 Cameroon
value = 40 Cape Verde Islands
value = 41 Cayman Islands
value = 42 Central African Republic
value = 233 Ceuta
value = 43 Chad
value = 44 Chile
value = 45 China
value = 46 Christmas Island
value = 47 Cocos-Keeling Islands
value = 48 Colombia
value = 49 Comoros
value = 50 Congo
value = 51 Cook Islands
value = 52 Costa Rica
value = 53 Croatia
value = 54 Cuba
value = 55 Cyprus
value = 56 Czech Republic
value = 57 Dem Rep of Congo
value = 58 Denmark
value = 59 Diego Garcia
value = 60 Djibouti
value = 61 Dominica
value = 62>Dominican Republic
value = 236>East Timor
value = 63>Ecuador
value = 64>Egypt
value = 65>El Salvador
value = 240>England
value = 66>Equatorial Guinea
value = 243>Eritrea
value = 67>Estonia
value = 68>Ethiopia
value = 69>Falkland Islands
value = 244>Faroe Islands
value = 70>Fiji Islands
value = 71>Finland
value = 72>France
value = 74>French Guiana
value = 75>French Polynesia
value = 76>Gabon
value = 77>Gambia
value = 78>Georgia
value = 79>Germany
value = 80>Ghana
value = 81>Gibraltar
value = 82>Greece
value = 83>Greenland
value = 84>Grenada
value = 85>Guadeloupe
value = 86>Guam
value = 88>Guatemala
value = 225>Guernsey
value = 89>Guinea
value = 253>Guinea-Bissau
value = 90>Guyana
value = 91>Haiti
value = 92>Honduras
value = 93>Hong Kong
value = 94>Hungary
value = 95>Iceland
value = 96>India
value = 97>Indonesia
value = 98>Iran
value = 99>Iraq
value = 100>Ireland
value = 224>Isle of Man
value = 101>Israel
value = 102>Italy
value = 103>Ivory Coast
value = 104>Jamaica
value = 105>Japan
value = 226>Jersey
value = 106>Jordan
value = 107>Kazakhstan
value = 108>Kenya
value = 109>Kiribati Republic
value = 242>Kosovo
value = 112>Kuwait
value = 113>Kyrgyz Republic
value = 114>Laos
value = 115>Latvia
value = 116>Lebanon
value = 117>Lesotho
value = 118>Liberia
value = 119>Libya
value = 120>Liechtenstein
value = 121>Lithuania
value = 122>Luxembourg
value = 123>Macau
value = 229>Macedonia
value = 124>Madagascar
value = 125>Malawi
value = 126>Malaysia
value = 127>Maldives
value = 128>Mali
value = 129>Malta
value = 130>Marshall Islands
value = 131>Martinique
value = 230>Mauritius
value = 132>Mayotte Island
value = 133>Mexico
value = 247>Micronesia
value = 134>Moldova
value = 135>Monaco
value = 136>Mongolia
value = 137>Monserrat
value = 234>Montenegro
value = 138>Morocco
value = 139>Mozambique
value = 140>Myanmar
value = 141>Namibia
value = 142>Nauru
value = 143>Nepal
value = 144>Netherlands
value = 145>Netherlands Antilles
value = 147>New Caledonia
value = 148>New Zealand
value = 149>Nicaragua
value = 150>Niger
value = 151>Nigeria
value = 152>Niue
value = 153>Norfolk Island
value = 110>North Korea
value = 238>Northern Ireland
value = 255>Northern Marianas
value = 154>Norway
value = 155>Oman
value = 156>Pakistan
value = 157>Palau
value = 235>Palestine
value = 158>Panama
value = 159>Papua New Guinea
value = 160>Paraguay
value = 161>Peru
value = 162>Philippines
value = 163>Poland
value = 164>Portugal
value = 165>Puerto Rico
value = 166>Qatar
value = 246>Réunion
value = 167>Romania
value = 169>Russia
value = 170>Rwanda
value = 172>Saipan Island
value = 219>Samoa
value = 173>San Marino
value = 254>Săo Tomé & Principe
value = 174>Saudi Arabia
value = 241>Scotland
value = 175>Senegal Republic
value = 221>Serbia
value = 245>Seychelles
value = 176>Sierra Leone
value = 177>Singapore
value = 178>Slovak Republic
value = 179>Slovenia
value = 180>Solomon Islands
value = 181>Somalia
value = 182>South Africa
value = 111>South Korea
value = 183>Spain
value = 184>Sri Lanka
value = 185>St Helena
value = 186>St Kitts
value = 171>St Lucia
value = 227>St Vincent & The Grenadines
value = 187>Sudan
value = 188>Suriname
value = 189>Swaziland
value = 190>Sweden
value = 191>Switzerland
value = 192>Syria
value = 193>Taiwan
value = 194>Tajikistan
value = 195>Tanzania
value = 196>Thailand
value = 237>Tibet
value = 197>Tinian Island
value = 198>Togo
value = 199>Tokelau
value = 200>Tonga
value = 201>Trinidad & Tobago
value = 202>Tunisia
value = 203>Turkey
value = 204>Turkmenistan
value = 205>Turks and Caicos Islands
value = 206>Tuvalu
value = 207>Uganda
value = 208>Ukraine
value = 209>United Arab Emirates
value = 211>United States Virgin Islands
value = 212>Uruguay
value = 214>Uzbekistan
value = 215>Vanuatu
value = 216>Vatican City
value = 217>Venezuela
value = 218>Vietnam
value = 239>Wales
value = 248>Yemen
value = 222>Zambia
value = 223>Zimbabwe

Subregion codes

0
1 Alabama
2 Alaska
3 Arizona
4 Arkansas
5 California
6 Colorado
7 Connecticut
8 Delaware
9 Florida
10 Georgia
11 Hawaii
12 Idaho
13 Indiana
14 Illinois
15 Iowa
16 Kansas
17 Kentucky
18 Louisiana
19 Maine
20 Maryland
21 Massachusetts
22 Michigan
23 Minnesota
24 Mississippi
25 Missouri
26 Montana
27 Nebraska
28 Nevada
29 New Hampshire
30 New Jersey
31 New Mexico
32 New York
33 North Carolina
34 North Dakota
35 Ohio
36 Oklahoma
37 Oregon
38 Pennsylvania
39 Rhode Island
40 South Carolina
41 South Dakota
42 Tennessee
43 Texas
44 Utah
45 Vermont
46 Virginia
47 Washington
48 Washington DC
49 West Virginia
50 Wisconsin
51 Wyoming
52 Alberta
53 British Columbia
54 Manitoba
55 New Brunswick
56 Newfoundland
57 Nova Scotia
58 Northwest Territories
59 Ontario
60 Prince Edward Island
61 Quebec

62 Saskatchewan
63 Yukon
64 Nunavut
65 Bedfordshire
66 Berkshire
67 Buckinghamshire
68 Cambridgeshire
69 Cheshire
70 Cornwall
71 Cumbria
72 Derbyshire
73 Devon
74 Dorset
75 Durham
76 East Sussex
77 East Yorkshire
78 Essex
79 Greater London
80 Greater Manchester
81 Gloucestershire
82 Hampshire
83 Herefordshire
84 Hertfordshire
85 Isle Of Wight
86 Kent
87 Lancashire
88 Leicestershire
89 Lincolnshire
90 Merseyside
91 North Yorkshire
92 Norfolk
93 Northamptonshire
94 Northumberland
95 Nottinghamshire
96 Oxfordshire
97 Rutland
98 South Yorkshire
99 Shropshire
100 Somerset
101 Staffordshire
102 Suffolk
103 Surrey
104 Tyne & Wear
105 West Sussex
106 West Yorkshire
107 Warwickshire
108 West Midlands
109 Wiltshire
110 Worcestershire
111 Baden-Württemberg
112 Bavaria
113 Berlin
114 Brandenburg
115 Bremen
116 Hamburg
117 Hesse
118 Mecklenburg-Vorpommern
119 Lower Saxony
120 North Rhine-Westphalia
121 Rhineland-Palatinate
122 Saarland
123 Saxony
124 Saxony-Anhalt
125 Schleswig-Holstein
126 Thuringia


BeerStyles

BeerStyleID BeerStyleName
71 Abbey Dubbel
72 Abbey Tripel
80 Abt/Quadrupel
2 Altbier
53 Amber Ale
36 American Dark Lager
18 American Pale Ale
64 American Strong Ale
63 Baltic Porter
11 Barley Wine
12 Belgian Ale
13 Belgian Strong Ale
48 Belgian White (Witbier)
61 Berliner Weisse
58 Bičre de Garde
20 Bitter
114 Black IPA
31 Bohemian Pilsener
15 Brown Ale
42 California Common
10 Cider
30 Classic German Pilsener
35 Cream Ale
26 Doppelbock
60 Dortmunder/Helles
22 Dry Stout
28 Dunkel
100 Dunkelweizen
9 Dunkler Bock
27 Eisbock
16 English Pale Ale
56 English Strong Ale
79 Foreign Stout
40 Fruit Beer
7 German Hefeweizen
82 German Kristallweizen
54 Golden Ale/Blond Ale
105 Heller Bock
112 Ice Cider/Perry
24 Imperial Stout
81 Imperial/Double IPA
113 Imperial/Strong Porter
17 India Pale Ale (IPA)
62 Irish Ale
39 Kölsch
77 Lambic - Faro
14 Lambic - Fruit
73 Lambic - Gueuze
78 Lambic - Unblended
75 Low Alcohol
8 Malt Liquor
44 Mead
55 Mild Ale
37 Oktoberfest/Märzen
76 Old Ale
3 Pale Lager
107 Perry
4 Pilsener
5 Porter
101 Premium Bitter/ESB
103 Premium Lager
45 Saison
87 Saké - Daiginjo
89 Saké - Futsu-shu
91 Saké - Genshu
86 Saké - Ginjo
85 Saké - Honjozo
94 Saké - Infused
84 Saké - Junmai
92 Saké - Koshu
90 Saké - Namasaké
93 Saké - Nigori
95 Saké - Taru
88 Saké - Tokubetsu
29 Schwarzbier
102 Scotch Ale
21 Scottish Ale
41 Smoked
52 Sour Ale/Wild Ale
106 Specialty Grain
57 Spice/Herb/Vegetable
6 Stout
65 Strong Pale Lager/Imperial Pils
23 Sweet Stout
59 Traditional Ale
43 Vienna
25 Weizen Bock
19 Wheat Ale
74 Zwickel/Keller/Landbier


BEER SEASONAL CODES

1) = "Winter"
2) = "Spring"
3) = "Summer"
4) = "Autumn"
5) = "Special"
6) = "Series"