A web-based chronological visualization of Pinboard bookmarks.
- Loads bookmarks from a Pinboard JSON export and renders them as a horizontal timeline of colored dots — like a filmstrip or photo gallery.
- Hover any dot to see a tooltip with the page title, URL, date, tags, and a live screenshot of the website (captured on first hover, cached to disk for instant repeat views).
- Click any dot to open the original URL in a new tab.
- Date range filter (top bar) to narrow the timeline to any period. Defaults to the last 30 days.
- Search box to filter by description, tags, URL, or notes.
- Drag or scroll wheel to pan horizontally through the timeline.
- Axis labels show months or years depending on the visible time span.
┌──────────────────────────────────────────────────────────────────┐
│ Pinboard Timeline From [2026-04-17] to [2026-05-17] [Search] 285 bookmarks │
├──────────────────────────────────────────────────────────────────┤
│ │
│ ○ ○ ● ○ ○ ○ ● ● ○ ○ ● ○ ○ ○ ● ● ○ ○ ● ○ ○ ● ● ○ ○ ● ○ │
│ ──●──────────────────────────────────────────────────●── │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ Apr May │
├──────────────────────────────────────────────────────────────────┤
│ 2026-04-17 → 2026-05-17 │
└──────────────────────────────────────────────────────────────────┘
Hover tooltip:
┌──────────────────────────────┐
│ ┌────────────────────────┐ │
│ │ (screenshot image) │ │
│ └────────────────────────┘ │
│ Alan Kay at UCLA CS 201 │
│ youtube.com │
│ 5/17/2026, 12:00:37 AM │
│ [alankay] │
└──────────────────────────────┘
PinboardViz/
server.py # Flask backend — data API + screenshot capture
index.html # Frontend — single-file, no build step
screenshots/ # Cached website thumbnails (auto-created, gitignored)
README.md # This file
.gitignore # Excludes screenshots/, Python artifacts, OS files
- Python 3.9+
- Flask 3.x
- Playwright (with Chromium)
# Clone the repository
git clone https://github.com/<your-username>/PinboardViz.git
cd PinboardViz
# Install dependencies
pip install flask playwright
# Install Playwright's Chromium browser
python -m playwright install chromium
# Configure your data path (see below), then run:
python server.py
# Open in browser: http://localhost:5150/Edit the constants at the top of server.py:
| Variable | Default | Description |
|---|---|---|
DATA_PATH |
(required) | Absolute path to your Pinboard JSON export file |
SCREENSHOT_DIR |
./screenshots/ |
Where cached thumbnails are stored |
VIEWPORT_W |
1280 |
Screenshot width in pixels |
VIEWPORT_H |
720 |
Screenshot height in pixels |
SCREENSHOT_TIMEOUT |
15000 |
Max milliseconds to wait for a page to load |
The server runs on port 5150 by default. Change the port in the
app.run() call at the bottom of server.py.
Export your bookmarks from Pinboard as JSON,
then set DATA_PATH in server.py to the downloaded file's location.
- When you hover a dot, the frontend checks if a screenshot is already cached in the browser's memory for this session.
- If not, it sends a
POST /api/capturerequest to the backend. - The backend uses Playwright (headless Chromium) to navigate to the URL, wait for the page to load, and capture a viewport-sized screenshot.
- The PNG is saved to the
screenshots/directory. - Subsequent hovers serve the cached file directly — no re-capture needed.
Screenshots that fail (timeout, unreachable host, bot protection, etc.) show a fallback message in the tooltip. Navigate away and hover again to retry.
The screenshots/ directory is excluded from version control via .gitignore.
It is safe to delete at any time — screenshots will be re-captured on next
hover.
Serves the frontend (index.html).
Returns dataset statistics.
Response:
{
"count": 76778,
"dated_count": 76776,
"undated_count": 2,
"min": "2006-02-15T10:29:21Z",
"max": "2026-05-17T00:32:11Z"
}Returns bookmark data, filterable by date range and search query.
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
start |
date | — | Inclusive start date (ISO format, e.g. 2025-01-01) |
end |
date | — | Inclusive end date |
search |
string | — | Full-text search across description, tags, URL, notes |
limit |
int | 5000 |
Max results (capped at 10000) |
offset |
int | 0 |
Pagination offset |
Response:
{
"total": 143,
"offset": 0,
"limit": 5000,
"bookmarks": [
{
"href": "https://example.com/article",
"description": "Article Title",
"extended": "User notes…",
"tags": "tag1 tag2",
"time": "2025-01-15T12:00:00Z",
"shared": "yes",
"toread": "no",
"hash": "a1b2c3d4e5f6g7h8"
}
]
}Triggers a screenshot capture for a given URL. Called by the frontend on first hover.
Request body:
{
"url": "https://example.com",
"hash": "a1b2c3d4e5f6g7h8"
}Response (success):
{ "ok": true, "hash": "a1b2c3d4e5f6g7h8" }Returns a cached PNG screenshot. Returns 404 if not yet captured.
The input file is a Pinboard JSON export — a JSON array of objects:
| Field | Description |
|---|---|
href |
URL of the bookmarked page |
description |
Page title or user-provided title |
extended |
User notes (may contain HTML) |
tags |
Space-separated tag string |
time |
ISO 8601 timestamp (UTC) |
shared |
"yes" or "no" |
toread |
"yes" or "no" |
meta |
Internal Pinboard metadata hash |
hash |
Internal Pinboard URL hash |
Entries with a timestamp of 1970-01-01T00:00:00Z (Unix epoch) are treated
as undated and excluded from the timeline by default. This is Pinboard's
sentinel value for bookmarks with no saved date.
The frontend uses vanilla ES6+ JavaScript with no build step and no dependencies. It works in any modern browser (Chrome, Firefox, Safari, Edge).
- The full dataset is loaded into memory at server startup. RAM usage scales with bookmark count (roughly 3-5 KB per bookmark).
- The frontend fetches up to 10,000 bookmarks per request. For very wide date ranges, dots may overlap visually — this is intentional (density = activity).
- Screenshots are captured one at a time. Hovering many dots quickly will queue captures. Each takes 2-15 seconds depending on the target site.
- The
screenshots/directory grows over time as you explore. Safe to delete to free disk space.
| Problem | Solution |
|---|---|
| Server won't start — port in use | Change the port in server.py: app.run(..., port=5150) |
| Screenshots always fail | Ensure Playwright Chromium is installed: python -m playwright install chromium |
| Date filter returns no results | Check that your date range overlaps the data range shown in /api/stats |
| Page loads but no dots appear | Open browser console (F12) for JS errors; verify server is running on the expected port |
| Out of memory | Use a narrower date range or reduce the limit parameter |
MIT