A local web app for tracing where a photo appears on the internet.
Upload an image or paste a URL. The app calls Google Cloud Vision Web Detection to find exact-file matches, then enriches those matches with scraped page metadata, EXIF data, and oldest-known archive dates from the Wayback Machine.
The frontend shows the full pipeline step-by-step -- raw JSON, normalized candidates, ranking decisions, and errors -- so you can inspect every part of the trace, not just the final answer.
┌────────────────────────────────────────────────────┐
│ Reserve Image Search │
│ │
┌─────────────┐ │ ┌──────────┐ ┌──────────────┐ │
│ Browser │ │ │ FastAPI │ │ SQLite │ │
│ React + │──HTTP──────>│ │ Backend │<────>│ backend/ │ │
│ Vite UI │<──JSON──────│ │ │ │ photos.db │ │
│ (port │ │ │ (port │ └──────────────┘ │
│ 5173) │ │ │ 8000) │ │
└─────────────┘ │ └────┬─────┘ ┌──────────────┐ │
│ │ │ uploads/ │ │
│ │ │ (local │ │
└───────┼────────────│ files) │────────────────┘
│ └──────────────┘
│
┌─────────────────┼──────────────────┐
│ │ │
v v v
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Google Cloud │ │ Metadata │ │ Wayback │
│ Vision API │ │ Scraper │ │ Machine CDX │
│ │ │ │ │ │
│ - full match │ │ - Open Graph │ │ - oldest │
│ - page match │ │ - Twitter │ │ archive │
│ - web entity │ │ - JSON-LD │ │ timestamp │
│ - labels │ │ - EXIF │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
v v v
┌──────────────────────────────────────────────┐
│ Ranking Engine │
│ │
│ Sorts by: Wayback > Publish > Modified > │
│ EXIF. Prefers exact over partial matches. │
│ Selects best_source with metadata. │
└──────────────────────────────────────────────┘
Each trace job runs through five stages. The frontend polls for status and shows each stage as it completes.
┌─────────────────────────────────────────────────────────────────────────────┐
│ Trace Pipeline │
│ │
│ 1. IMAGE SEARCH │
│ │ Send image to Google Cloud Vision Web Detection │
│ │ Optional: also query SerpAPI Google Lens │
│ │ Returns: exact matches, page candidates, web entities, labels │
│ v │
│ 2. CANDIDATE SELECTION │
│ │ Filter and prioritize results │
│ │ Keep fullMatchingImages as exact-file evidence │
│ │ Select up to 20 pages for scraping │
│ v │
│ 3. METADATA SCRAPING │
│ │ Fetch candidate pages and extract metadata │
│ │ Sources: Open Graph, Twitter Card, JSON-LD, │
│ │ Dublin Core, HTML meta tags, EXIF, HTTP headers │
│ │ Runs up to 6 concurrent workers │
│ v │
│ 4. WAYBACK ENRICHMENT │
│ │ Query Wayback Machine CDX API for each result │
│ │ Find the oldest known archived snapshot │
│ v │
│ 5. RANKING │
│ │ Sort results by oldest evidence │
│ │ Prefer: Wayback > Publish Date > Modified Date > EXIF │
│ │ Select best_source with full metadata │
│ v │
│ DONE │
└─────────────────────────────────────────────────────────────────────────────┘
PENDING
│
v
PROCESSING_VISION
│
v
SELECTING_EXACT_MATCHES
│
v
SCRAPING_METADATA
│
v
CHECKING_WAYBACK
│
v
RANKING_RESULTS
│
v
COMPLETED ERROR
This app is intentionally conservative about what counts as a match:
┌────────────────────────────────────────────────────────────────┐
│ │
│ fullMatchingImages -> EXACT image file evidence │
│ (same file hash) │
│ │
│ pagesWithMatchingImages -> CANDIDATE page evidence │
│ (may be context/embed) │
│ │ │
│ ├── scraper confirms the exact image URL is on the page │
│ │ -> upgraded to EXACT page │
│ │ │
│ └── cannot confirm │
│ -> stays as fallback candidate │
│ │
│ visuallySimilarImages -> stored in raw JSON only │
│ (not used for ranking) │
│ │
└────────────────────────────────────────────────────────────────┘
photo-detector/
├── backend/
│ ├── app/
│ │ ├── api/
│ │ │ └── routes.py # REST API endpoints
│ │ ├── db/
│ │ │ ├── database.py # SQLite connection setup
│ │ │ └── models.py # SQLAlchemy models (photo_jobs, bulk_jobs)
│ │ ├── services/
│ │ │ ├── pipeline.py # Main pipeline orchestrator
│ │ │ ├── bulk_pipeline.py # Bulk processing orchestrator
│ │ │ ├── scraper.py # Page metadata extraction
│ │ │ ├── vision_client.py # Google Vision API client
│ │ │ ├── serpapi_client.py # SerpAPI Google Lens client
│ │ │ └── utils.py # Helpers
│ │ └── main.py # FastAPI app entry point
│ ├── uploads/ # Uploaded image files (local)
│ ├── photos.db # SQLite database
│ ├── .env # Environment variables (API keys)
│ └── requirements.txt # Python dependencies
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ │ ├── UploadBox.tsx # Single image upload / URL input
│ │ │ ├── ResultsView.tsx # Trace results with step timeline
│ │ │ ├── BulkView.tsx # Bulk job management
│ │ │ └── BulkInput.tsx # Bulk URL input form
│ │ ├── services/
│ │ │ └── api.ts # Frontend HTTP client (Axios)
│ │ ├── hooks/ # Custom React hooks
│ │ ├── App.tsx # Main app component
│ │ └── main.tsx # React entry point
│ ├── package.json # Node.js dependencies
│ └── vite.config.ts # Vite build config
├── launcher.bat # One-click Windows launcher
└── README.md
┌─────────────────────────────────────────────────┐
│ Required │
│ │
│ Python 3.12+ https://python.org │
│ Node.js 20+ https://nodejs.org │
│ Google Cloud project with Vision API enabled │
│ -> Get a service account key or API key │
│ │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ Optional │
│ │
│ SerpAPI account │
│ -> Enables Google Lens as an additional │
│ search mode (serpapi / combined) │
│ -> https://serpapi.com │
│ │
└─────────────────────────────────────────────────┘
# Backend
cd backend
python -m venv .venv
.venv\Scripts\activate # Windows
pip install -r requirements.txt
# Frontend
cd frontend
npm installCreate backend/.env:
# Required: Google Cloud Vision
GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\service-account.json
# -- or --
GOOGLE_VISION_API_KEY=your_api_key_here
# Optional: SerpAPI (enables additional search mode)
SERPAPI_API_KEY=your_serpapi_key_hereAuth modes explained:
┌──────────────────────────────────────┐
│ GOOGLE_APPLICATION_CREDENTIALS │
│ (Recommended) │
│ │
│ Point to a service account JSON │
│ file. Used by Google's client │
│ library via Application Default │
│ Credentials. │
│ │
│ Smallest permissions + protect │
│ the key file. │
└──────────────────────────────────────┘
┌──────────────────────────────────────┐
│ GOOGLE_VISION_API_KEY │
│ (Fallback) │
│ │
│ Works but may hit 403 / │
│ API_KEY_SERVICE_BLOCKED if your │
│ API key has restrictions. │
└──────────────────────────────────────┘
Windows (one click):
launcher.batThis opens two terminal windows -- backend on port 8000, frontend on port 5173.
Manual:
# Terminal 1: Backend
cd backend
.venv\Scripts\activate
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
# Terminal 2: Frontend
cd frontend
npm run devThen open http://localhost:5173.
POST /api/trace
Body: multipart file as "file"
or form field "image_url"
Query: search_mode=google_vision | serpapi | combined
Response: { "job_id": "uuid", "status": "PENDING" }
GET /api/jobs/{job_id}
Response: { status, error_message, results: { ... full pipeline JSON } }
POST /api/bulk/trace
Body: JSON { "urls": [...], "search_mode": "..." }
Response: { "bulk_job_id": "uuid", "status": "PENDING" }
GET /api/bulk/{bulk_job_id} # status + per-job results
GET /api/bulk/{bulk_job_id}/export # CSV download
GET /api/jobs/recent # list recent trace jobs
{
"query": "input image path or URL",
"source_kind": "local_file",
"pipeline_run_at": "2026-04-14T15:59:37Z",
"steps": [],
"vision": {
"auth": {},
"request": {},
"rawResponse": {},
"webDetection": {}
},
"candidates": {
"exactImageUrls": [],
"pageCandidates": [],
"selectedPageUrls": [],
"directExactImages": [],
"confirmedExactPages": [],
"fallbackCandidates": []
},
"scraped_pages": [],
"exact_matches": [],
"fallback_candidates": [],
"best_source": {},
"ranking": {},
"errors": []
} ┌─────────────────────────────────────────┐
│ From pages │
│ │
│ Open Graph (og:image, og:title, ...) │
│ Twitter Card (twitter:card, ...) │
│ JSON-LD (ImageObject, Article, ...) │
│ Dublin Core (DC.title, DC.creator) │
│ HTML meta tags (author, date, ...) │
│ Platform-specific heuristics │
│ │
├─────────────────────────────────────────┤
│ From images │
│ │
│ HTTP headers (Last-Modified, ...) │
│ EXIF data (DateTime, Artist, ...) │
│ │
├─────────────────────────────────────────┤
│ From external archives │
│ │
│ Wayback Machine oldest snapshot │
│ │
└─────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ │
│ google_vision (default) │
│ Uses Google Cloud Vision Web Detection only. │
│ │
│ serpapi │
│ Uses SerpAPI Google Lens only. │
│ Requires SERPAPI_API_KEY in .env. │
│ │
│ combined │
│ Runs both and merges results. │
│ Requires both API keys. │
│ │
└───────────────────────────────────────────────────────────────┘
Paid API:
- Google Cloud Vision Web Detection
- First 1,000 units/month: free
- 1,001 - 5,000,000 units/month: USD 3.50 per 1,000 units
- Always verify: https://cloud.google.com/vision/pricing
Paid API (optional):
- SerpAPI: pay-per-request, see https://serpapi.com/pricing
Everything else is local:
- SQLite, React/Vite frontend, scraping, Wayback CDX queries all run on your machine with no separate billing.
- Oldest Wayback snapshot is not the same as proven first upload.
- Many platforms strip EXIF data from images.
- Some pages block scraping, lazy-load content, or require JavaScript.
- Google Vision may return context pages that don't expose enough HTML to prove they serve the same file.
- Some sites remove
Last-Modifiedheaders or normalize images behind CDNs. - This app is useful for investigation -- it does not prove legal authorship by itself.
- Google Cloud Vision Web Detection: https://docs.cloud.google.com/vision/docs/detecting-web
- Google Cloud Vision pricing: https://cloud.google.com/vision/pricing
- Google Cloud auth setup: https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment
- Internet Archive Wayback Machine: https://archive.org/web/