untappd-data-cleaner

Untappd allows you to download your checkin data in JSON and CSV formats (if you are a supporter). This is great, however they do not have an option to download the data of just your 'unique' checkins. This script will take the json file you downloaded from untappd and create both json and csv files with only your last checkins of each beer.

There are also additional parsing options detailed below. I use this to generate the beer map on my website. So this has become mostly tailored towards that.

Installation

This project uses pixi to manage its environment (Python + dev tooling from conda-forge):

pixi install

Or, for a plain pip install of just the CLI:

pip install -e .

Usage

Command Line Interface

Basic usage - find unique venues (default)

untappd-parser <UNTAPPD-DATA>.json

Sort by a different key

Available keys: brewery_name, venue, beer_type, photo_url, bid

untappd-parser <UNTAPPD-DATA>.json --key brewery_name

Split venues by visit frequency (1, 2-4, 5+ visits)

untappd-parser <UNTAPPD-DATA>.json --split-by-visits

This creates 3 separate CSV files:

• *_1_visit.csv - venues with exactly 1 visit
• *_2-4_visits.csv - venues with 2-4 visits
• *_5+_visits.csv - venues with 5 or more visits

Additional Flags

• --no-human-keys - Keep original snake_case keys (e.g. venue_name instead of Venue Name)
• --no-strip-backend - Keep all keys from the original JSON file
• --no-fancy-dates - Keep dates in YYYY-MM-DD HH:MM:SS format instead of readable format

Browser Interface (No installation required!)

Open untappd.html in your browser to use the parser without installing Python. PyScript runs the same untappd_parser package in the browser via Pyodide — it fetches the source files directly, so there is no build step or bundle to maintain.

1. Serve the file

   pixi run serve   # or: python3 -m http.server 8080

2. Open in browser: http://localhost:8080/untappd.html
3. Drag and drop your Untappd JSON file
4. Download the processed CSVs with visit distribution

Development

All dev tasks run through pixi (see pixi.toml for the full list):

pixi run lint        # ruff check
pixi run format      # ruff format
pixi run typecheck   # mypy
pixi run test        # pytest
pixi run check       # lint + typecheck + test (what CI runs)

The browser interface (untappd.html) loads src/untappd_parser/ directly via PyScript, so editing parser.py or web.py needs no rebuild — just reload the page.

License

MIT