---

name: untappd description: Comprehensive beer tracking integration with Untappd. Search for beers, check in with ratings and comments, view checkin history, and manage your beer-drinking social experience. Use when users want to log beers, search the Untappd database, view their drinking history, or interact with beer-related data from the world's largest beer community platform.

Untappd

Integrate with Untappd, the world's largest social network for beer enthusiasts, to search beers, check in with ratings and comments, and track your beer journey.

Core Capabilities

1. Beer Search and Discovery

Search Untappd's massive beer database with natural language queries:

• Smart Search: "Find a Dogfish Head IPA" or "Search for Guinness"
• Brewery + Beer: Best results with "Stone Arrogant Bastard" format
• Style Filtering: Search by beer style, ABV, or brewery location
• Detailed Beer Info: Get comprehensive beer details, ratings, and brewery information

2. Beer Check-ins

Log your beer experiences with full social features:

• Simple Check-ins: untappd_checkin.py 12345
• Rated Check-ins: Add 1-5 star ratings (supports half ratings like 4.5)
• Comments: Include tasting notes and experiences (max 140 characters)
• Location: Add GPS coordinates or venue information
• Social Sharing: Auto-share to Facebook, Twitter, or Foursquare
• Badge Earning: Automatically earn achievement badges

3. History and Analytics

View and analyze your beer journey:

• Recent Check-ins: See your latest beer activities
• User Profiles: View any public user's beer stats and history
• Drinking Stats: Track total checkins, unique beers, and badges earned
• Compact Views: Quick overviews or detailed analysis formats

Quick Start Examples

Search for Beers

# Basic search
untappd_search.py "Pliny the Elder"

# Search with options
untappd_search.py "Stone IPA" --limit 10 --format table

Check in to a Beer

# Simple checkin (requires setup)
untappd_checkin.py 12345

# Full-featured checkin
untappd_checkin.py 12345 --rating 4.5 --comment "Fantastic hop character!" --share-twitter

View Checkin History

# Your recent checkins
untappd_checkins.py --limit 10

# Another user's public checkins  
untappd_checkins.py john_doe --compact

Workflow Decision Tree

Are you searching for beer information? → Use untappd_search.py with brewery name + beer name for best results → Get beer ID from search results for detailed info or check-ins

Are you logging a beer experience? → Ensure authentication is set up (untappd_setup.py auth) → Use untappd_checkin.py with beer ID and optional rating/comment → Add location or social sharing as desired

Are you exploring drinking history? → Use untappd_checkins.py for your history or public profiles → Choose compact format for overviews or detailed for full information

Setup and Authentication

First-Time Setup

1. Register API App: Go to https://untappd.com/api/register
2. Configure Credentials: python3 untappd_setup.py credentials
3. Complete OAuth (for check-ins): python3 untappd_setup.py auth
4. Test Setup: python3 untappd_setup.py test

Authentication Levels

• Basic (Client ID/Secret): Search, public data, beer information
• Authenticated (OAuth Token): Check-ins, private data, social features

See authentication.md for complete setup guide.

Common Usage Patterns

Research and Discovery

# Find specific beer
untappd_search.py "Russian River Pliny"

# Explore brewery catalog
untappd_search.py "Dogfish Head" --limit 20

# Get detailed beer info
python3 -c "
from scripts.untappd_client import UntappdClient
client = UntappdClient()
info = client.get_beer_info(12345)
print(f\"Rating: {info['response']['beer']['rating_score']}/5.0\")
"

Social Beer Logging

# Quick checkin
untappd_checkin.py 12345

# Detailed experience log
untappd_checkin.py 12345 \
  --rating 4.5 \
  --comment "Perfect balance of malt and hops" \
  --location 40.7128,-74.0060 \
  --share-twitter

# Dry run (test without posting)
untappd_checkin.py 12345 --rating 4 --comment "Testing" --dry-run

History Analysis

# Recent drinking activity
untappd_checkins.py --limit 15 --compact

# Detailed checkin review
untappd_checkins.py --limit 5

# Export to JSON for analysis
untappd_checkins.py --format json > my_checkins.json

Scripts Reference

Core Scripts

untappd_client.py - Python API client library

• Handles authentication, rate limiting, error handling
• Supports all major Untappd API endpoints
• Can be imported or used standalone for testing

untappd_setup.py - Authentication and configuration

• Interactive credential setup
• OAuth authentication flow
• Configuration testing and status checking

untappd_search.py - Beer and brewery search

• Natural language search queries
• Formatted table or JSON output
• Configurable result limits and sorting

untappd_checkin.py - Beer check-in functionality

• Full-featured beer logging with ratings and comments
• Location and social media integration
• Dry-run mode for testing

untappd_checkins.py - View checkin history

• Your checkins or public user profiles
• Compact or detailed viewing formats
• Pagination support

Advanced Features

Location Integration

Add GPS coordinates or venue information to checkins:

# GPS coordinates
untappd_checkin.py 12345 --location 40.7128,-74.0060

# With venue sharing to Foursquare
untappd_checkin.py 12345 --location 40.7128,-74.0060 --share-foursquare

Social Media Integration

Share your beer experiences automatically:

# Share to Twitter
untappd_checkin.py 12345 --comment "Great beer!" --share-twitter

# Share to Facebook and Twitter
untappd_checkin.py 12345 --share-facebook --share-twitter

Batch Operations

For multiple operations, use the Python client directly:

from scripts.untappd_client import UntappdClient

client = UntappdClient()

# Batch search multiple breweries
breweries = ["Stone", "Dogfish Head", "Russian River"]
for brewery in breweries:
    results = client.search_beer(brewery)
    print(f"Found {len(results['response']['beers']['items'])} {brewery} beers")

Error Handling and Troubleshooting

Common Issues

"Invalid credentials"

• Run untappd_setup.py credentials to reconfigure
• Verify credentials at https://untappd.com/api/dashboard

"Rate limit exceeded"

• Wait for rate limit reset (100 requests/hour)
• Check remaining quota: untappd_setup.py test

"Beer not found"

• Try different search terms: "Brewery Name + Beer Name"
• Check spelling and use full beer names

"Authentication required"

• Complete OAuth setup: untappd_setup.py auth
• Verify access token: untappd_setup.py status

Debug Mode

Add error details to any script:

# Show full API responses
untappd_search.py "beer name" --format json

# Test authentication status
untappd_setup.py test

Data Privacy and Security

• API Keys: Stored securely in ~/.openclaw/untappd_config.json (600 permissions)
• Access Tokens: Don't expire but can be revoked via Untappd dashboard
• Public Data: Search and beer info don't require personal authentication
• Social Sharing: Explicitly opt-in for each checkin

Resources

References

• api.md - Complete API endpoint documentation with request/response examples
• authentication.md - Step-by-step authentication setup guide

External Links

• Untappd API Registration: https://untappd.com/api/register
• API Documentation: https://untappd.com/api/docs/v4
• Your API Dashboard: https://untappd.com/api/dashboard

Rate Limits and Performance

• Standard Rate Limit: 100 API calls per hour
• Authenticated Limit: Per-user basis when using access tokens
• Best Practices: Cache search results, batch similar operations
• Monitoring: Check X-Ratelimit-Remaining header in responses

This skill transforms Untappd's social beer platform into a powerful tool for beer discovery, experience logging, and history analysis within the OpenClaw ecosystem.