Menu

API Documentation

Select an API Method

The end point for all Untappd API is https://api.untappd.com/v4. Please note that all requests, must be made over HTTPS, HTTP is not supported.

Client ID / Client Secret

In V4 of the API, we have added Client ID and Client Secrets. You can find them on your Dashboard page. You Client ID is your old API Key, while the Client Secret has been added. Whenever you are making a call to the API, you MUST pass both your Client ID and Client Secret as GET params like below:

https://api.untappd.com/v4/method_name?client_id=CLIENTID&client_secret=CLIENTSECRET

When making Authenticated requests, you will append the access token to the URL below:

https://api.untappd.com/v4/method_name?access_token=ACESSTOKENHERE

See the Authentication section for more details.

Responses

All responses in the API return JSON. The responses are very similar to other API providers, as detailed below:

Errors

In the event of an error, Untappd API will return the relevant HTTP Code (500, 404, 401, etc) and have a format that looks like this:

Please note the developer_friendly, may or not be in the response during an error. The best practice is to check if that attribute exists, and use that to display to your users, instead of using error_detail.

Rate-Limiting

All API applications are rate-limited to protect aganist abuse and keep the platform healthly. The default limit for API access is 100 calls per hour per key. If you are using Authentication, the rate limit is applied to the user, instead of the API key.

To check your rate-limit, we pass 2 special headers on the response that can let you know your limit:

X-Ratelimit-Limit: XXXX
X-Ratelimit-Remaining: XXX

Authentication

Authentication is handled via OAuth Authentication. You must edit your app and add in a redirect URL that Untappd will callback after the authorization has taken place. You will receive an access token to make an authenticated calls. At this time, tokens do not expire.

Server Side Authentication (Recommended)

To authenticate a user, direct them to the following URL:

https://untappd.com/oauth/authenticate/?client_id=CLIENTID&response_type=code&redirect_url=REDIRECT_URL

After the user has authenticated and authorized the application, we will redirect back to the following URL:

http://REDIRECT_URL?code=CODE

Note: Your Redirect URL (also known as the Callback URL) is set up in your App Settings. You can change it anytime by going to your dashboard and clicking the Edit link next to link. This a required paramter for all apps that use authentication.

Taking the code paramater and then pass it back to the following address via GET (pass parameters via the Query String). Ensure that the REDIRECT_URL you supply in this call, is the same that was supplied in the authenticate call:

https://untappd.com/oauth/authorize/?client_id=CLIENTID&client_secret=CLIENTSECRET&response_type=code&redirect_url=REDIRECT_URL&code=CODE

Finally, we will send back the access_token that will you use for future requests, as shown in the response below:

Client Side Authentication

Note: You should only be using this method if you do not have a back-end server component to handle the request.

To authenticate a user, direct them to the following URL:

https://untappd.com/oauth/authenticate/?client_id=CLIENTID&response_type=token&redirect_url=REDIRECT_URL

After the user has logged in we will redirect back to the following address::

http://REDIRECT_URL#access_token=TOKENHERE

Activity Feed

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/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.

Parameters

  • access_token (string, required) - The access token of the authenicated user
  • max_id (int, optional) - The checkin ID that you want the results to start with
  • min_id (int, optional) - Returns only checkins that are newer than this value
  • limit (int, optional) - The number of results to return, max of 50, default is 25

Example Response

User Activity Feed

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/user/checkins/USERNAME

Note: When using authentication, you can drop off the USERNAME parameter and it will return the authenticated users'results.

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

Parameters

  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • USERNAME (string, 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 with
  • min_id (int, optional) - Returns only checkins that are newer than this value
  • limit (int, optional) - The number of results to return, max of 50, default is 25

Example Response

The Pub (Local)

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/thepub/local

Note: This will return only users who have made their account public.

This method allows you the obtain all the public feed for Untappd, within a certain location. By default it will return at max 25 records.

Parameters

  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • lat (float, required) - The latitude of the query
  • lng (float, required) - The longitude of the query
  • max_id (int, optional) - The checkin ID that you want the results to start with
  • min_id (int, optional) - Returns only checkins that are newer than this value
  • limit (int, optional) - The number of results to return, max of 25, default is 25
  • radius (int, optional) - The max radius you would like the check-ins to start within, max of 25, default is 25
  • dist_pref (string, optional) - If you want the results returned in miles or km. Available options: "m", or "km". Default is "m"

Example Response

Beer Activity Feed

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/beer/checkins/BID

Note: This will return only users who have made their account public.

This method allows you the obtain an activity feed for a single beer for Untappd. By default it will return at max 25 records

Parameters

  • BID (int, required) - The beer ID that you want to display checkins
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • max_id (int, optional) - The checkin ID that you want the results to start with
  • min_id (int, optional) - Returns only checkins that are newer than this value
  • limit (int, optional) - The number of results to return, max of 25, default is 25

Example Response

Brewery Activity Feed

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/brewery/checkins/BREWERY_ID

Note: This will return only users who have made their account public.

This method allows you the obtain an activity feed for a single brewery for Untappd. By default it will return at max 25 records.

Parameters

  • BREWERY_ID (int, required) - The Brewery ID that you want to display checkins
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • max_id (int, optional) - The checkin ID that you want the results to start with
  • min_id (int, optional) - Returns only checkins that are newer than this value
  • limit (int, optional) - The number of results to return, max of 25, default is 25

Example Response

Venue Activity Feed

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/venue/checkins/VENUE_ID

Note: This will return only users who have made their account public.

is method allows you the obtain an activity feed for a single venue for Untappd. By default it will return at max 25 records.

Parameters

  • VENUE_ID (int, required) - The Venue ID that you want to display checkins
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • max_id (int, optional) - The checkin ID that you want the results to start with
  • min_id (int, optional) - Returns only checkins that are newer than this value
  • limit (int, optional) - The number of results to return, max of 25, default is 25

Example Response

Beer Info

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/beer/info/BID

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

Parameters

  • BID (int, required) - The Beer ID that you want to display checkins
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • compact (string, optional) - You can pass "true" here only show the beer infomation, and remove the "checkins", "media", "variants", etc attributes

Example Response

Brewery Info

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/brewery/info/BREWERY_ID

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

Parameters

  • BREWERY_ID (int, required) - The Brewery ID that you want to display checkins
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • compact (string, optional) - You can pass "true" here only show the brewery infomation, and remove the "checkins", "media", "beer_list", etc attributes

Example Response

Venue Info

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/venue/info/VENUE_ID

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

Parameters

  • VENUE_ID (int, required) - The Venue ID that you want to display checkins
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • compact (string, optional) - You can pass "true" here only show the venue infomation, and remove the "checkins", "media", "top_beers", etc attributes

Example Response

Checkin Details

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/checkin/view/CHECKIN_ID

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

Parameters

  • CHECKIN_ID (int, required) - The Checkin ID that you want to display information
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls

Example Response

User Info

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/user/info/USERNAME

Note: When using authentication, you can drop off the USERNAME parameter and it will return the authenticated users'results.

This method will return the user information for a selected user.

Parameters

  • USERNAME (string, 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)
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • compact (string, optional) - You can pass "true" here only show the user infomation, and remove the "checkins", "media", "recent_brews", etc attributes

Example Response

Note: In the example response the settings attribute block is returned becaused the user provided was called with their access_token. You will get an empty settings block if you try call user/info to another USERNAME.

User Friends

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/user/friends/USERNAME

Note: When using authentication, you can drop off the USERNAME parameter and it will return the authenticated users'results.

This method will return the last 25 friends for a selected.

Parameters

  • USERNAME (string, 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)
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of records that you will return (max 25, default 25)

Example Response

User Badges

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/user/badges/USERNAME

Note: When using authentication, you can drop off the USERNAME parameter and it will return the authenticated users'results.

This method will return a list of the last 50 the user's earned badges

Parameters

  • USERNAME (string, 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)
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • offset (int, optional) - The numeric offset that you what results to start

Example Response

User Wish List

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/user/wishlist/USERNAME

Note: When using authentication, you can drop off the USERNAME parameter and it will return the authenticated users'results.

This method will return a list of 25 of the user's wish listed beers.

Parameters

  • USERNAME (string, 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)
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of results to return, max of 50, default is 25
  • sort (string, optional) - You can sort the results using these values: date - sorts by date (default), checkin - sorted by highest checkin, highest_rated - sorts by global rating descending order, lowest_rated - sorts by global rating ascending order, highest_abv - highest ABV from the wishlist, lowest_abv - lowest ABV from the wishlist

Example Response

User Distinct Beers

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/user/beers/USERNAME

Note: When using authentication, you can drop off the USERNAME parameter and it will return the authenticated users'results.

This method will return a list of 25 of the user's distinct beers.

Parameters

  • USERNAME (string, 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)
  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of results to return, max of 50, default is 25
  • sort (string, optional) - Your can sort the results using these values: date - sorts by date (default), checkin - sorted by highest checkin, highest_rated - sorts by global rating descending order, lowest_rated - sorts by global rating ascending order, highest_rated_you - the user's highest rated beer, lowest_rated_you - the user's lowest rated beer

Example Response

Beer Search

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/search/beer

Note: The best way to search is always "Brewery Name + Beer Name", such as "Dogfish 60 Minute".

This will allow you to search across the Untappd database for beers and breweries.

Parameters

  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • q (string, required) - The search term that you want to search.
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of results to return, max of 50, default is 25
  • sort (string, optional) - Your can sort the results using these values: checkin - sorts by checkin count (default), name - sorted by alphabetic beer name

Example Response

Brewery Search

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/search/brewery

This will allow you to search exclusively for breweries in the Untappd system.

Parameters

  • access_token or client_id and client_secret (string, required) - Either pass the access_token for authorized calls OR the client_id and client_secret for unauthorized calls
  • q (string, required) - The search term that you want to search.
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of results to return, max of 50, default is 25

Example Response

Trending

Check-in

  • Authentication: Required
  • HTTP Method: POST
  • Endpoint: /v4/checkin/add

This will allow you to check-in to a beer as the authenticated user

Parameters

  • access_token (string, required) - The access token for the acting user
  • gmt_offset (string, required) - The numeric value of hours the user is away from the GMT (Greenwich Mean Time), such as -5.
  • timezone (string, required) - The timezone of the user, such as EST or PST./li>
  • bid (int, required) - The numeric Beer ID you want to check into.
  • foursquare_id (string, 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 (int, optional) - The numeric Latitude of the user. This is required if you add a location.
  • geolng (int, optional) - The numeric Longitude of the user. This is required if you add a location.
  • shout (string, optional) - The text you would like to include as a comment of the checkin. Max of 140 characters.
  • rating (int, optional) - The rating score you would like to add for the beer. This can only be 1 to 5 (half ratings are included). You can't rate a beer a 0.
  • facebook (string, optional) - If you want to push this check-in to the users' Facebook account, pass this value as "on", default is "off"
  • twitter (string, optional) - If you want to push this check-in to the users' Twitter account, pass this value as "on", default is "off"
  • foursquare (string, optional) - If you want to push this check-in to the users' Foursquare account, pass this value as "on", default is "off". You must include a location for this to enabled.

Please Note It's possible that you could pass through a foursquare venue ID, and not get back a "venue" object in the response. This can be due to many reasons, but mainly due to a Foursquare connectivity issue. Your app or service should never depending on a one-to-one match on the foursquare ID send, and a venue object returned as part of the response. Always do a null check to make sure that the object's attributes exists before digging deeper into it.

Example Response

Add Comment

  • Authentication: Required
  • HTTP Method: POST
  • Endpoint: /v4/checkin/addcomment/CHECKIN_ID

This method will allow you comment on a checkin.

Parameters

  • access_token (string, required) - The access token for the acting user
  • CHECKIN_ID (int, required) - The checkin ID of the check-in you want ot add the comment.
  • shout (string, required) - The text of the comment you want to add. Max of 140 characters.

Example Response

Remove Comment

  • Authentication: Required
  • HTTP Method: POST
  • Endpoint: /v4/checkin/deletecomment/COMMENT_ID

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

Parameters

  • access_token (string, required) - The access token for the acting user
  • COMMENT_ID (int, required) - The comment ID of comment you want to delete

Example Response

Toast / Untoast

  • Authentication: Required
  • HTTP Method: POST
  • Endpoint: /v4/checkin/toast/CHECKIN_ID

Note: If you want to un-toast a check-in, you call the same method. The resulting response will tell you if the authenticated user has toasted the check-in

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.

Parameters

  • access_token (string, required) - The access token for the acting user
  • CHECKIN_ID (int, required) - The checkin ID of checkin you want to toast

Example Response

Pending Friends

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/user/pending

This will allow you to return your pending friends requests. By default, it will return up all results, but you can limit the results via the limit paramater.

Parameters

  • access_token (string, required) - The access token for the acting user
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of results to return. (default is all)

Example Response

Accept Friend

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/friend/accept/TARGET_ID

This will allow you to accept a pending friend request

Parameters

  • access_token (string, required) - The access token for the acting user
  • TARGET_ID (int, required) - The target user id that you wish to accept.

Example Response

Request Friend

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/friend/request/TARGET_ID

This will allow you to request a person to be your friend.

Parameters

  • access_token (string, required) - The access token for the acting user
  • TARGET_ID (int, required) - The target user id that you wish to accept.

Example Response

Reject Friend

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/friend/reject/TARGET_ID

This will allow you to reject a pending friend request

Parameters

  • access_token (string, required) - The access token for the acting user
  • TARGET_ID (int, required) - The target user id that you wish to reject.

Example Response

Remove Friend

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/friend/reject/TARGET_ID

This will allow you to remove a current friend

Parameters

  • access_token (string, required) - The access token for the acting user
  • TARGET_ID (int, required) - The target user id that you wish to remove.

Example Response

Request Friend

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/friend/request/TARGET_ID

This will allow you to request a user to be your friend.

Parameters

  • access_token (string, required) - The access token for the acting user
  • TARGET_ID (int, required) - The target user id that you wish to request.

Example Response

Add to Wish List

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/user/wishlist/add

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

Parameters

  • access_token (string, required) - The access token for the acting user
  • bid (int, required) - The numeric BID of the beer you want to add your list.

Example Response

Remove from to Wish List

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/user/wishlist/delete

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

Parameters

  • access_token (string, required) - The access token for the acting user
  • bid (int, required) - The numeric BID of the beer you want to remove from your list.

Example Response

Notifications

  • Authentication: Required
  • HTTP Method: GET
  • Endpoint: /v4/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.

Parameters

  • access_token (string, required) - The access token for the acting user
  • offset (int, optional) - The numeric offset that you what results to start
  • limit (int, optional) - The number of records that you will return (max 25, default 25)

Example Response

Foursquare Lookup

  • Authentication: Not Required
  • HTTP Method: GET
  • Endpoint: /v4/venue/foursquare_lookup/VENUE_ID

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.

Parameters

  • access_token (string, required) - The access token for the acting user
  • VENUE_ID (string, required) - The foursquare venue v2 ID that you wish to translate into a Untappd venue ID.

Example Response