API Documentation (V3)

Authentication

Authentication is handled via HTTP Authentication. Not all methods required Authentication. If you wish to authenticate the user, you must pass your username and password (in MD5 hash format) for the service. You need to hash the password on the server side prior to sending it over Untappd. All responses return a nicely parsed JSON array for your liking.

NOTE: This API is no longer supported. It will be decommissioned on 12/31/12. Please use API V4 for you new projects.

API Endpoints

The end point for all Untappd API is
http://api.untappd.com/v3

API Key

API Key must be passed as a QUERY STRING to the URI like this:
http://api.untappd.com/v3/method_name?key=12345

Note: By using the API, you state that your application is in accordance with our Terms of Use for our API.

Friend Feed

Authentication: Required

HTTP Method: GET

/v3/feed

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.

Parameters

  • key (required) - Your API Key provided when you are approved
  • since (optional) - The numeric ID of the last recent check-in. This provided to you in the next_query attribute.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.

This feed will return an attribute call "next_query" that allow you to search for recent updates to the feed.

This feed will return an attribute call "next_page" that allow you to display the next page of updates.

To test out this method and see what elements it returns use the API explorer site.

User Feed

Authentication: Not required

HTTP Method: GET

/v3/user_feed

This method allows you the obtain all the friend check-in feed of the selected user. This includes only beer checkin-ins the selected user. By default it will return at max 25 records.

Parameters

  • key (required) - Your API Key provided when you are approved
  • user (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.
  • since (optional) - The numeric ID of the last recent check-in. This provided to you in the next_query attribute.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so yo can use that paginate the feed.

This feed will return an attribute call "next_query" that allow you to search for recent updates to the feed.

This feed will return an attribute call "next_page" that allow you to display the next page of updates.

To test out this method and see what elements it returns use the API explorer site.

The Public Feed

Authentication: Not required

HTTP Method: GET

/v3/thepub

This method allows you the obtain all the public feed for Untappd. This includes only beer checkin-ins non private users by an authenticated user. By default it will return at max 25 records.

Parameters

  • key (required) - Your API Key provided when you are approved
  • since (optional) - The numeric ID of the last recent check-in. This provided to you in the next_query attribute.
  • geolat (optional) - The numeric Latitude to filter the public feed.
  • geolng (optional) - The numeric Longitude to filter the public feed.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.
  • radius (optional) - The numeric radius that you are trying to search within. The maximum for this value is 50 and the default is 5

This feed will return an attribute call "next_query" that allow you to search for recent updates to the feed.

This feed will return an attribute call "next_page" that allow you to display the next page of updates.

To test out this method and see what elements it returns use the API explorer site.

Beer Feed

Authentication: Not required

HTTP Method: GET

/v3/beer_checkins

This method allows you the obtain a feed for a single beer for Untappd. This includes only beer checkin-ins non private users by an authenticated user. By default it will return at max 25 records.

Parameters

  • key (required) - Your API Key provided when you are approved
  • bid (required) - The beer ID that you want to display checkins
  • since (optional) - The numeric ID of the last recent check-in. This provided to you in the next_query attribute.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.

This feed will return an attribute call "next_query" that allow you to search for recent updates to the feed.

This feed will return an attribute call "next_page" that allow you to display the next page of updates.

To test out this method and see what elements it returns use the API explorer site.

Brewery Feed

Authentication: Not required

HTTP Method: GET

/v3/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.

Parameters

  • key (required) - Your API Key provided when you are approved
  • brewery_id (required) - The Brewery ID that you want to display checkins
  • since (optional) - The numeric ID of the last recent check-in. This provided to you in the next_query attribute.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.

This feed will return an attribute call "next_query" that allow you to search for recent updates to the feed.

This feed will return an attribute call "next_page" that allow you to display the next page of updates.

To test out this method and see what elements it returns use the API explorer site.

Venue Feed

Authentication: Not required

HTTP Method: GET

/v3/venue_checkins

This method allows you the obtain a feed for a single venue for Untappd. This includes only beer checkin-ins non private users by an authenticated user. By default it will return at max 25 records.

Parameters

  • key (required) - Your API Key provided when you are approved
  • venue_id (required) - The Venue ID that you want to display checkins
  • since (optional) - The numeric ID of the last recent check-in. This provided to you in the next_query attribute.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.

This feed will return an attribute call "next_query" that allow you to search for recent updates to the feed.

This feed will return an attribute call "next_page" that allow you to display the next page of updates.

To test out this method and see what elements it returns use the API explorer site.

Beer Info

Authentication: Not required

HTTP Method: GET

/v3/beer_info

This method will allow you to see extended information about a beer.

Parameters

  • key (required) - Your API Key provided when you are approved
  • bid (required) - The numeric beer ID of the beer you wish to look up.

To test out this method and see what elements it returns use the API explorer site.

Brewery Info

Authentication: Not required

HTTP Method: GET

/v3/brewery_info

This method will allow you to see extended information about a brewery.

Parameters

  • key (required) - Your API Key provided when you are approved
  • brewery_id (required) - The numeric brewery ID of the beer you wish to look up.

To test out this method and see what elements it returns use the API explorer site.

Venue Info

Authentication: Not required

HTTP Method: GET

/v3/venue_info

This method will allow you to see extended information about a venue.

Parameters

  • key (required) - Your API Key provided when you are approved
  • venue_id (required) - The numeric venue ID of the beer you wish to look up.

To test out this method and see what elements it returns use the API explorer site.

Checkin Details

Authentication: Not required

HTTP Method: GET

/v3/details

This method will allow you to see extended details for a particular checkin, which includes location, comments and toasts.

Parameters

  • key (required) - Your API Key provided when you are approved
  • id (required) - The numeric ID of the check-in.

To test out this method and see what elements it returns use the API explorer site.

User Info

Authentication: Not required

HTTP Method: GET

/v3/user

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.

Parameters

  • key (required) - Your API Key provided when you are approved
  • user (optional) - The username of the person who you wish to obtain the user information. If you wish to call the authenticated user's information, do not include this parameter in your call.

To test out this method and see what elements it returns use the API explorer site.

User Friends

Authentication: Not required

HTTP Method: GET

/v3/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 "user" query string.

Parameters

  • key (required) - Your API Key provided when you are approved
  • user (optional) - The username of the person who you wish to obtain the information. If you wish to call the authenticated user's information, do not include this parameter in your call.

To test out this method and see what elements it returns use the API explorer site.

User Badges

Authentication: Not required

HTTP Method: GET

/v3/user_badge

This method will return all the user's badges. If you want to obtain the authenticated user's information, you don't need to pass the "user" query string.

Parameters

  • key (required) - Your API Key provided when you are approved
  • user (optional) - The username of the person who you wish to obtain the badge information. If you wish to call the authenticated user's information, do not include this parameter in your call.

To test out this method and see what elements it returns use the API explorer site.

User Wish List

Authentication: Not required

HTTP Method: GET

/v3/wish_list

This method will allow you to see all the user's wish listed beers.

Parameters

  • key (required) - Your API Key provided when you are approved
  • user (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.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.

To test out this method and see what elements it returns use the API explorer site.

User Distinct Beers

Authentication: Not required

HTTP Method: GET

/v3/user_distinct

This method will allow you to see all the user's distinct beers.

Parameters

  • key (required) - Your API Key provided when you are approved
  • user (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.
  • offset (optional) - The offset that you like the dataset to begin with. Each set returns 25 max records, so you can use that paginate the feed.

To test out this method and see what elements it returns use the API explorer site.

Checkin Test

Authentication: Required

HTTP Method: POST

/v3/checkin_test

This will allow you to perform a test checkin for testing purposes. Badges/Promotions earned are only for demonstration purposes. No posting to social networks will be enabled.

Parameters

  • key (required) - Your API Key provided when you are approved
  • gmt_offset (required) - The numeric value of hours the user is away from the GMT (Greenwich Mean Time)
  • 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. Older numeric id will not be accepted.
  • user_lat (optional) - The numeric Latitude of the user. This is required if you add a location.
  • user_lng (optional) - The numeric Longitude of the user. This is required if you add a location.

To test out this method and see what elements it returns use the API explorer site.

Checkin

Authentication: Required

HTTP Method: POST

/v3/checkin

This will allow you to perform a live checkin.

Parameters

  • key (required) - Your API Key provided when you are approved
  • gmt_offset (required) - The numeric value of hours the user is away from the GMT (Greenwich Mean Time)
  • 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. Older numeric id will not be accepted.
  • user_lat (optional) - The numeric Latitude of the user. This is required if you add a location.
  • user_lng (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_value (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 facebook
  • twitter (optional) - Default = "off", Pass "on" to post to twitter
  • foursquare (optional) - Default = "off", Pass "on" to checkin on foursquare
  • gowalla (optional) - Default = "off", Pass "on" to checkin on gowalla

To test out this method and see what elements it returns use the API explorer site.

Example Response

Add Comment

Authentication: Required

HTTP Method: POST

/v3/add_comment

This method will allow you comment on a checkin.

Parameters

  • key (required) - Your API Key provided when you are approved
  • checkin_id (required) - The numeric check-in ID that you wish to add a comment.
  • comment (required) - The comment text that you would like to add. It must be less than 140 characters.

Example Response

Remove Comment

Authentication: Required

HTTP Method: POST

/v3/delete_comment

This method will allow you to delete your comment on a checkin.

Parameters

  • key (required) - Your API Key provided when you are approved
  • comment_id (required) - The comment ID you wish to delete.

Example Response

Toast

Authentication: Required

HTTP Method: POST

/v3/toast

This method will allow you to toast a checkin.

Parameters

  • key (required) - Your API Key provided when you are approved
  • checkin_id (required) - The checkin ID you wish you toast.

Example Response

Delete Toast

Authentication: Required

HTTP Method: POST

/v3/delete_toast

This method will allow you to delete your toast on a checkin.

Parameters

  • key (required) - Your API Key provided when you are approved
  • checkin_id (required) - The checkin ID you wish you remove your toast.

Example Response

Pending Friends

Authentication: Required

HTTP Method: GET

/v3/friend_pending

This will allow you to return your pending friends requests

Parameters

  • key (required) - Your API Key provided when you are approved

Example Response

Accept Friends

Authentication: Required

HTTP Method: POST

/v3/friend_accept

This will allow you to accept a pending friend request

Parameters

  • key (required) - Your API Key provided when you are approved
  • target_id (required) - The target user id that you wish to accept.

Example Response

Reject Friends

Authentication: Required

HTTP Method: POST

/v3/friend_accept

This will allow you to return you to ignore a pending friend request

Parameters

  • key (required) - Your API Key provided when you are approved
  • target_id (required) - The target user id that you wish to reject/ignore.

Example Response

Remove Friends

Authentication: Required

HTTP Method: POST

/v3/friend_revoke

This will allow you to return you to revoke a current friendship

Parameters

  • key (required) - Your API Key provided when you are approved
  • target_id (required) - The target user id that you wish to remove/revoke.

Example Response

Friend Request

Authentication: Required

HTTP Method: POST

/v3/friend_request

This will allow you to request to be someone's friend on Untappd

Parameters

  • key (required) - Your API Key provided when you are approved
  • target_id (required) - The target user id that you wish to request to be their friend.

Example Response

Add To Wish List

Authentication: Required

HTTP Method: POST

/v3/add_to_wish

This method will allow you to add a beer to your wish list

Parameters

  • key (required) - Your API Key provided when you are approved
  • bid (required) - The numeric beer ID that you wish to add to your wishlist.

Example Response

Remove From Wish List

Authentication: Required

HTTP Method: POST

/v3/remove_from_wish

This method will allow you to remove a beer from your wish list

Parameters

  • key (required) - Your API Key provided when you are approved
  • bid (required) - The numeric beer ID that you wish to remove from your wishlist.

Example Response

Activity On You

Authentication: Required

HTTP Method: GET

/v3/activity_on_you

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.

Parameters

  • key (required) - Your API Key provided when you are approved
  • since (required) - The UNIX timestamp where you want the feed to start. Will only return a max of 25 items when using this method.

Example Response

Foursquare Venue Lookup

Authentication: Not Required

HTTP Method: GET

/v3/foursquare_lookup

This method will allow you to pass in a foursquare v2 ID and return a Untappd Venue ID to be used for /v3/venue_info or /v3/venue_checkins

Parameters

  • key (required) - Your API Key provided when you are approved
  • vid (required) - The foursquare venue v2 ID that you wish to translate into a Untappd venue ID.

Example Response