Untappd - a Perl wrapper for the Untappd.com API.
use Untappd;
my $untappd = Untappd->new({
client_id => "XXXXX",
client_secret => "YYYYY",
access_token => "ZZZZZ",
});
my $user_info = $untappd->user_info({ username => "USERNAME" });
print "Total Beers: ", $user_info->{user}{stats}{total_beers};
print "Total Badges: ", $user_info->{user}{stats}{total_badges};
my $checkins = $untappd->checkin_recent();
foreach my $checkin ( @{ $checkins->{checkins}{items} } ) {
print "$checkin->{user}{first_name} $checkin->{user}{last_name} ",
"had $checkin->{beer}{beer_name} by $checkin->{brewery}{brewery_name}\n";
}
This is a library for accessing the Untappd API.
You'll first need to register for an API key, which you can do here:
http://untappd.com/api/register
The API that this library accesses is documented here:
https://untappd.com/api/docs/v4
Once you have your API key, you'll want to obtain an access_token. See the oath_authenticate function
below for instructions on how to do that.
Parameters passed to the various methods below should be passed in as a hashref.
Responses are a multi-dimensional hashref, as provided by Untappd.com.
-
oath_authenticate()
Obtains OAuth authentication URL.
Application authentication with Untappd is handled via OAuth.
In order for most of these functions to work, you need to login to Untappd via the OAuth URL returned by this function. After authenticating, you will be redirected to the redirect_url you provide.
It will look like this:
http://REDIRECT_URL#access_token=TOKENHEREYou need to note the value of
access_token.Your application will need to use that access_token in order to authenticate with Untappd.com.
Params
redirect_url(required) - redirect to this URL after authenticating with Untappd.com.https://untappd.com/api/docs/v4#authentication
Example Usage:
use Untappd; my $untappd = Untappd->new({ client_id => MY_CLIENT_ID, client_secret => MY_CLIENT_SECRET }); print $untappd->oath_authenticate("http://redirect.url.tld");Then, take the URL output above, paste it into your browser, login to Untappd, and when your browser redirects, note the
access_tokenparameter in the URL string.You should only have to perform this step once. At this time, OAuth Tokens do not expire.
-
checkin_recent()
This method allows you the obtain all the friend check-in feed of the authenticated user. This includes only beer checkin-ins from Friends. By default it will return at max 25 records.
Params
max_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, max of 50, default is 25 -
user_checkins()
This method allows you the obtain all the check-in feed of the selected user. By default it will return at max 25 records.
Params
username(optional) - The username that you wish to call the request upon. If you do not provide a username - the feed will return results from the authenticated user (if the access_token is provided)max_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, max of 50, default is 25 -
thepub()
This method allows you the obtain all the public feed for Untappd. By default it will return at max 25 records.
Params
min_id(int, optional) - The numeric ID of the most recent check-in.max_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, max of 50, default is 25 -
thepub_local()
This method allows you the obtain all the public feed for Untappd. By default it will return at max 25 records.
Params
min_id(int, optional) - The numeric ID of the most recent check-in.lng(float, optional) - The numeric Latitude to filter the public feed.lat(float, optional) - The numeric Longitude to filter the public feed.radius(int, optional) - The max radius you would like the check-ins to start withinmax_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, max of 50, default is 25 -
venue_checkins()
This method allows you the obtain a feed for a single venue for Untappd. By default it will return at max 25 records.
Params
venue_id(required) - The Brewery ID that you want to display checkinsmin_id(int, optional) - The numeric ID of the most recent check-in. New results will only be shown if there are checkins before this IDmax_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, max of 50, default is 25 -
beer_checkins()
This method allows you the obtain a feed for a single beer for Untappd. By default it will return at max 25 records.
Params
bid(required) - The beer ID that you want to display checkinsmin_id(int, optional) - The numeric ID of the most recent check-in. This provided to you in the next_query attribute.max_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, maximum of 50, default fault is 25 -
brewery_checkins()
This method allows you the obtain a feed for a single brewery for Untappd. This includes only beer checkin-ins non private users by an authenticated user. By default it will return at max 25 records.
Params
brewery_id(required) - The Brewery ID that you want to display checkinsmin_id(int, optional) - The numeric ID of the most recent check-in. New results will only be shown if there are checkins before this IDmax_id(int, optional) - The checkin ID that you want the results to start withlimit(int, optional) - The number of results to return, max of 50, default is 25 -
brewery_info()
This method will allow you to see extended information about a brewery.
Params
brewery_id(required) - The Brewery ID that you want to display information -
beer_info()
This method will allow you to see extended information about a beer.
Params
bid(required) - The Beer ID that you want to display information -
venue_info()
This method will allow you to see extended information about a venue.
Params
venue_id(required) - The Venue ID that you want to display information -
checkin_view()
This method will allow you to see extended details for a particular checkin, which includes location, comments and toasts.
Params
checkin_id(required) - The Checkin ID that you want to display information -
user_info()
This method will return the user information for a selected user. If you want to obtain the authenticated user's information, you don't need to pass the "user" query string. Please note: The settings attribute will only be visible if the user that you are making the call on is authenticated. Unauthenticated calls do not return this attribtue.
Params
username(required) - The Username that you want to display information -
user_badges()
This method will return a list of the last 50 the user's earned badges. If you want to obtain the authenticated user's information, you don't need to pass the "USERNAME" parameter.
Params
username(required) - The Username that you want to display informationoffset(int, optional) - The numeric offset that you what results to start -
user_friends()
This method will return the last 25 friends for a selected. If you want to obtain the authenticated user's information, you don't need to pass the
usernameparameterParams
username(required) - The Username that you want to display informationoffset(int, optional) - The numeric offset that you what results to startlimit(optional) - The number of records that you will return (max 50) -
user_wishlist()
This method will allow you to see all the user's wish listed beers.
Params
username(required) - The Username that you want to display informationoffset(int, optional) - The numeric offset that you what results to start -
user_beers()
This method will allow you to see all the user's distinct beers.
Params
username(required) - The Username that you want to display informationsort(string, optional) - Your can sort the results using these values:-
Sort Params
date- sorts by date (default),checkin- sorted by highest checkinhighest_rated- sorts by global rating descending order,lowest_rated- sorts by global rating ascending orderhighest_rated_you- the user's highest rated beerlowest_rated_you- the user's lowest rated beer
offset(int, optional) - The numeric offset that you what results to start -
-
search_brewery()
This method will allow you to see all to search the Untappd database of breweries.
Params
q(required) - The search term that you want to search. -
search_beer()
This method will allow you to see all to search the Untappd database of beers.
Params
q(required) - The search term that you want to search.sort(optional):countorname(default) - This can let you choose if you want the results to be returned in Alphabetical order (name) or by checkin count (count). By default the search returns all values in Alphabetical order. -
trending()
This method will allow you see trending beers (macro and micro) globally.
-
checkin_add()
This will allow you to perform a live checkin.
Params
gmt_offset(required) - The numeric value of hours the user is away from the GMT (Greenwich Mean Time)timezone(required) - The timezone of the user, such as EST or PST.bid(required) - The numeric Beer ID you want to check into.foursquare_id(optional) - The MD5 hash ID of the Venue you want to attach the beer checkin. This HAS TO BE the MD5 non-numeric hash from the foursquare v2.geolat(optional) - The numeric Latitude of the user. This is required if you add a location.geolng(optional) - The numeric Longitude of the user. This is required if you add a location.shout(optional) - The text you would like to include as a comment of the checkin. Max of 140 characters.rating(optional) - The rating score you would like to add for the beer. This can only be 1 to 5 and whole numbers (no 4.2)facebook(optional) - Default = "off", Pass "on" to post to facebooktwitter(optional) - Default = "off", Pass "on" to post to twitterfoursquare(optional) - Default = "off", Pass "on" to checkin on foursquare -
checkin_addcomment()
This method will allow you comment on a checkin.
Params
checkin_id(required) - The checkin ID you wish you toast.comment(required) - The comment text that you would like to add. It must be less than 140 characters -
checkin_deletecomment()
This method will allow you to delete your comment on a checkin.
Params
comment_id(required) - The comment ID you wish to delete. -
checkin_toast()
This method will allow you to toast a checkin. Please note, if the user has already toasted this check-in, it will delete the toast.
Params
checkin_id(required) - The checkin ID you wish you toast. -
wishlist_add()
This method will allow you to add a beer to your wish list
Params
bid(required) - The numeric beer ID that you wish to add to your wishlist. -
wishlist_remove()
This method will allow you to remove a beer from your wish list
Params
bid(required) - The numeric beer ID that you wish to remove from your wishlist. -
friend_pending()
This will allow you to return your pending friends requests
-
friend_accept()
This will allow you to accept a pending friend request
Params
target_id(required) - The target user id that you wish to accept. -
friend_reject()
This will allow you to return you to ignore a pending friend request
Params
target_id(required) - The target user id that you wish to reject/ignore. -
friend_remove()
This will allow you to return you to revoke a current friendship
Params
target_id(required) - The target user id that you wish to remove/revoke. -
friend_request()
This will allow you to request to be someone's friend on Untappd
Params
target_id(required) - The target user id that you wish to request to be their friend. -
notifications()
This method will allow you pull in a feed of notifications (toasts and comments) on the authenticated user. It will return the 25 items by default and pagination is not supported. It will also show the last 25 news items in the order of created date.
-
foursquare_lookup()
This method will allow you to pass in a foursquare v2 ID and return a Untappd Venue ID to be used for /v4/venue/info or /v4/venue/checkins
Params
venue_id(required) - The foursquare venue v2 ID that you wish to translate into a Untappd
Show recent checkins for Founders Imperial Stout
my $checkins = $untappd->beer_checkins({ bid => 4586 });
foreach my $checkin (@{ $checkins->{checkins}{items} }) {
print "$checkin->{user}{first_name} at $checkin->{created_at}\n";
}
Search for beer from Founders
my $beers = $untappd->search_beer({ q => "founders" });
foreach my $beer ( @{ $beers->{beers}{items} } ) {
print "$beer->{beer}{beer_name}\n";
}
Show extended info on Founders Kentucky Breakfast Stout
my $beer = $untappd->beer_info({ bid => "9681" });
print "$beer->{beer}{beer_name} by $beer->{beer}{brewery}{brewery_name} ",
"in $beer->{beer}{brewery}{location}{brewery_city}, ",
"$beer->{beer}{brewery}{location}{brewery_state} ",
"rated $beer->{beer}{rating_score}\n ";
Comment on a checkin
my $response = $untappd->checkin_addcomment({
checkin_id => 26943020,
comment => "That's a fine beer!",
});
Perform a checkin
my $response = $untappd->checkin_add({
gmt_offset => "-5",
timezone => "EST",
bid => 9681,
shout => "Yum!",
rating => 5,
});
The current source for this module is available here:
https://github.com/andreychek/untappd
Untappd for Perl is not endorsed by or affiliated with Untappd.com.
Untappd.com and it's content are Copyright 10/18/10 Untappd. All Rights Reserved.
The descriptions of the above methods is taken from the Untappd.com API documentation.
Please be sure that your applications are in accordance with the Untappd.com Terms of Use:
https://untappd.com/terms/api
Eric Andreychek (eric at openthought.net)
The Untappd for Perl module is Copyright (C) 2013 by Eric Andreychek.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.