API Documentation

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.

Beer List Data

Please note that Venue Beer List (or tap list information) are NOT SUPPORTED in the Public API. If you are member of the Untappd for Business platform, please head over to https://docs.business.untappd.com for documentation and how to get your API keys.

User-Agent

Please note that you must provide a non-standard User Agent for all requests using the API (including authentication). Your user-agent can include your app name and Client ID, such as "Greg's App (CLIENT_ID)", however can be customized for your needs. Do not use standard user-agents, always indentify your self.

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 is handled via OAuth 2.0 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

Notice: We optional support the state parameter that can be used in the request like below to prevent Cross-site Request Forgery. Simple pass the state paramater in the authentication URL like &state=STATEVALUE to enable this. The state paramater will be returned in the URL below as well once authentication occurs for you to validate.

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 paramater 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:

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

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 25, default is 25

Example Response

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

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

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

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

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

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

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

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.

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

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
limit (int, optional) - The number of badges to return in your result set

Example Response

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

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
start_date (string) (To be used with End Date) To get all beers between this start_date and end_date (format: YYYY-MM-DD)
end_date (string)(To be used with Start Date) To get all beers between the start_date and end_date (format: YYYY-MM-DD)

Example Response

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

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

Authentication: Not Required
HTTP Method: GET
Endpoint: /v4/beer/trending

This method will allow you see trending beers (macro and micro) globally

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

Example Response

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

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.
comment (string, required) - The text of the comment you want to add. Max of 140 characters.

Example Response

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

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

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

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

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

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

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

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

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

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

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

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.