Overview

Batch Geolocate reads GPS coordinates from your geotagged photos and automatically fills in location metadata: Country, State/Province, City, Sublocation, and Point of Interest (POI). It can optionally use AI to generate keywords and descriptions for each image.

The engine is heavily multi-threaded and designed to squeeze maximum performance from your hardware. Images are clustered by GPS proximity to minimize redundant API calls. Location lookups use an in-memory cache that makes repeated queries instant. Thumbnails and metadata caches are built and refreshed automatically in background threads — you never have to think about cache maintenance.

All metadata is written using industry-standard IPTC and XMP tags, compatible with Adobe Lightroom, Bridge, Capture One, DigiKam, IrfanView, and virtually all professional photo management software.

The Five Applications

Quick How-To

Follow these steps in order for the best results with your photo library.

Step 1: Download Your Country's POI Database

Step 2: Tag Your Entire Library

Step 3: POI Enrichment

For quick, automatic POI tagging without interaction, use Quick POI only instead. This selects POIs from your saved locations and local database without showing a dialog, but only when there is exactly one unambiguous match.

Step 4: AI Analysis Optional

Step 5: Browse with Batch PhotoBrowser

Batch Geolocate — Full Guide

Main Window

The main window consists of:

• Menu bar — File (Settings, Custom Locations), Tools (Custom POI Manager, Batch PhotoBrowser, Batch MetadataSync, Batch PhotoRater, Batch PhotoFixer), Help (User Manual, About, Explain, Statistics, Donate).
• Folder selection — Choose the folder containing your images. The number of images found is shown after selection.
• Include subfolders / Overwrite existing fields — Process subfolders and optionally replace existing metadata.
• Process Images section:
  • Tag country, city and subregion — Reverse geocodes GPS coordinates using Nominatim (OpenStreetMap).
  • Tag Point of Interest — Interactive POI discovery with dialog. The label dynamically changes to show whether interactive or automatic mode is active.
  • Use AI for keywords and description — AI vision analysis (requires API key). Shows a cost warning when processing more than 1,000 images.
• Options:
  • Quick POI only — Switches POI tagging to automatic mode: uses saved locations and local database only, no dialog. Selects a POI only when exactly one unambiguous match exists.
  • Continue on API fail — Skip online POI queries if APIs are unavailable. If all APIs fail and the country isn't in the local database, it is automatically downloaded in the background.
• Action bar — Start Processing and Show Photos buttons. During processing, Pause and Quit Processing buttons appear.
• Status bar — API health indicators for each Overpass endpoint and Nominatim: green ✓ = online, red ✗ = failed, yellow ⏳ = cooldown, gray ● = not tested. APIs are health-checked at startup and automatically rotated on failure.

Settings

Access via File → Settings. Four tabs:

General

• Exiftool — Path to exiftool.exe (with Browse button). Auto-discovered from system PATH, script directory, and common install locations.
• Paths — Shows install folder and data folder locations with Open buttons.
• Cache sizes — Shows current disk usage for geocache, metadata cache, and thumbnail cache.
• Privacy — Password for hiding images marked as "private" in Batch PhotoBrowser. This does not encrypt files — it only prevents accidental viewing.

Distances

All search radii organized into three sections:

• Clustering & matching — Custom POI match (50m), image cluster radius (30m), auto-match POI (50m), geocode cache (100m), session POI filter (100m).
• POI search — Online search radius (25m), online fallback radius (100m), offline DB search (40m), offline DB wide search (100m), "Update with 250m" radius, max search radius (2000m).
• API behavior — Cooldown duration (60s), recheck interval (20 queries).

Each field has a tooltip explaining its purpose. "Restore defaults" resets all values.

POI Database

Download offline POI data from OpenStreetMap (via Geofabrik). Features:

• Country dropdown with smart suggestions — your most-photographed countries that aren't downloaded yet, marked with ★.
• Hierarchical treeview of downloaded data showing countries, sub-regions, POI counts, and download dates.
• Automatic sub-region selection — uses point-in-polygon matching on the Geofabrik geo-index to find the smallest available region containing your photos.
• Auto-download on API failure — when all Overpass APIs are down and the country isn't in the local database, it automatically downloads the best sub-region with a progress dialog.
• Expired data check at startup — prompts to update data older than 1 year.

AI

• API key — Moonshot API key with show/hide toggle.
• Advanced — Endpoint URL, model name, max image size (default 1024px), max tokens (default 4096), output language (12 languages).
• Default agents — Number of concurrent AI workers (1–10, default 5).
• Test connection — Verifies the API key and endpoint are working.

Supports Moonshot, OpenRouter, NVIDIA NIM, and Together AI endpoints.

POI Selection Dialog

When Tag Point of Interest is enabled (in interactive mode) and no automatic match is found, a dialog appears:

• Left panel — List of nearby POIs from offline database and Overpass API. Permanently saved POIs shown at top. Session entries are marked with "+". Right-click on "+" items to remove them.
• Right panel — Image preview with navigation arrows (click or ← → keys) for multi-image clusters. Shows cluster size, file path, GPS coordinates, and resolved location. If AI analysis has been run, description and keywords are shown below the image in a purple section.
• "Save empty POI" — Permanently marks this location as having no POI (won't ask again).
• "Add your own..." — Enter a custom name with autocomplete from your previously used POI names. Check "Save permanently" to store it in the database for automatic future use.
• "Update with 250m" — Searches a wider area using both offline database and Overpass API.
• "Skip" — Skips this location for the current session only.
• "Pause processing" — Toggles pause on the main processing pipeline.

AI Analysis Window

When AI analysis runs, a separate window shows progress with a dynamic multi-column layout. Each column represents one AI worker (agent), running as an independent thread with its own work queue:

• Completed (top row) — Finished images with generated keywords and description.
• Analyzing (middle row) — Images currently being processed by AI, with animated preview.
• Next (bottom row) — Queued images with SKIP buttons.

Add or remove agents at runtime using the + and − buttons. The default is configurable (1–10 agents, default 5). 3–6 agents is recommended for optimal throughput; too many may trigger rate limits.

If a rate limit is detected, all workers automatically pause and a dialog is shown. The window shows a progress bar with timing statistics (elapsed time, estimated remaining). Images rated as "poor quality" by the AI automatically receive a 1-star rating.

Custom POI Manager

Access via Tools → Custom POI Manager. An interactive map-based tool for managing your permanently saved POIs. Opens in a separate window with a full-screen Leaflet.js map and a resizable POI list panel.

• Interactive map — All your custom POIs shown as draggable markers on the map. Hover over a marker to see the POI name and photo count. Drag a marker to update its coordinates. Right-click a marker to open the edit dialog.
• Add POI — Right-click anywhere on the map to add a new POI at that location. Or click + Add POI in the toolbar, then click on the map to place it.
• Search & filter — Search POIs by name, city, or country. Use the Country, City filter with autocomplete to narrow by location. Filter buttons (All, Named, Unnamed) toggle between all POIs, named POIs only, or empty-name ("no POI") entries only.
• Photo count — Each POI shows how many photos in your library use that POI name (from the metadata cache). Visible in the list, map tooltips, and useful for deciding which POIs to rename or clean up.
• Edit dialog — Click the pencil icon on any list row (or right-click a marker) to edit the name, coordinates, and radius. A "Search and rename on known photos" checkbox lets you update the POI name in all matching image files automatically — both the EXIF metadata and the metadata cache are updated, with a progress bar showing status.
• Delete — Click the trash icon on any list row to delete a POI with confirmation.

Custom Locations

Access via File → Custom Locations. View, edit, and delete your permanently saved POIs. Each entry shows GPS coordinates and the resolved city/state/country. Use Edit to rename a POI and Del to remove it. Empty-name entries represent locations permanently marked as "no POI here".

Statistics

Access via Help → Statistics. Shows two tables:

• Locations — All countries, states, cities, and sublocations written, sorted by frequency.
• Points of Interest — All POI names written, sorted by frequency.

How It Works

Access via Help → Explain. An illustrated guide explaining what POIs are, how reverse geocoding works, how the POI sweep finds nearby locations, and how the caching system keeps everything fast.

Batch PhotoBrowser

A fast, modern photo browser that displays your images with metadata overlays, batch editing tools, and full-screen viewing. Built on a concurrent architecture that saturates all available CPU cores for thumbnail generation, with intelligent three-tier loading (EXIF embedded thumbnail → draft decode → full quality) that keeps the UI responsive even with 60,000+ images.

Gallery View

• Three layouts: Masonry (default), Justified, and Grid — switch with the buttons in the bottom bar.
• Zoom slider: 80px to 2000px thumbnail size, with real-time relayout.
• Filters: Location (free text), rating (stars with exact = or minimum ≥ mode), keywords (comma-separated, AND logic).
• Grouping: By year, country, POI, folder, or keyword. Keyword grouping shows images under every keyword they have.
• Sorting: By date (ascending/descending), location, folder, rating, or name.
• Rating: Click stars on any thumbnail to set/change rating (saved immediately to EXIF).
• Metadata cache: The first folder open reads metadata and generates thumbnails using a parallel pipeline. All subsequent opens are instant — metadata and thumbnails are loaded from a persistent SQLite cache and disk thumbnail store that is automatically kept up to date.

Toolbar & Painter Tools

The left-side toolbar provides three painter tools for batch editing. Activate a tool by clicking its icon, then click images to select them, and click Apply to write changes. You can also drag a tool icon onto an image to auto-fill the painter panel with that image's metadata as a template.

• Location Painter (pin icon) — Batch-write location metadata (Country, State, City, Sublocation, POI) to selected images. Three ways to pick a location:
  • Saved POIs: Search and pick from your custom saved POIs.
  • Manual entry: Type Country, State, City, Sublocation with cross-filtering autocomplete.
  • Downloaded POIs: Search the offline POI database.
  GPS coordinates are written only to images that don't already have them.
• Keyword Painter (tag icon) — Batch-write keywords to selected images. 6 keyword slots with autocomplete. Two modes: Add to existing (appends, skipping duplicates) or Replace all.
• Recycle Painter (trash icon) — Move selected images to the Recycle Bin. Shows a confirmation dialog with thumbnail previews before deleting. Removes images from the metadata cache as well.

Full-Screen Viewer

Click any thumbnail to open the full-screen viewer. Features:

• Zoom & pan: Mouse wheel to zoom (0.5x–10x), click-drag to pan when zoomed, double-click to toggle 1x/3x.
• Metadata panel (left side): Editable fields for rating, POI, Country, State, City, Sublocation, Keywords (#hashtag format), and Description. Click Save changes to write edits to the image file.
• Get location button: Runs reverse geocoding for this image via Batch Geolocate (fills Country, State, City, Sublocation from GPS).
• Get AI analysis button: Generates keywords and description using AI (requires API key configured in Batch Geolocate settings).
• Skip AI toggle: Exclude this image from future batch AI analysis runs.
• Cinema mode: Press Space to hide the metadata panel for a clean viewing experience.
• Slideshow: Auto-advance through images with configurable timing.
• Copy path: Click the filename or path to copy it to the clipboard.
• Keyboard navigation: ← → to navigate, Esc to close, Space to toggle cinema mode.

Batch MetadataSync

A multi-purpose metadata utility with three tabs. Runs all heavy operations in background threads with pause/resume controls.

IPTC ↔ XMP Sync

Ensures IPTC and XMP metadata fields contain identical data. Choose which standard is "master" (IPTC or XMP) and the tool copies values to the other.

Most users will never need this tab. Batch Geolocate already writes to both IPTC and XMP. Use it only if you have images processed by other software that wrote to only one standard.

Face Tags

Synchronizes face/person region tags across different metadata formats:

• Reads from MWG (Lightroom), Microsoft, and ACDSee formats
• Merges into the MWG standard as master
• Optionally syncs to selected target formats: Microsoft MP tags, ACDSee regions, IPTC PersonInImage, and dc:Subject keywords
• Conflicts (same face region, different names) are flagged for manual resolution

Cache + Thumbnails

Build and maintain the metadata cache and thumbnail files used by Batch PhotoBrowser. The thumbnail generator runs with parallel worker threads that scale to your CPU core count, generating 300px and 600px thumbnails simultaneously. Three actions:

• Build cache — Reads metadata and generates thumbnails for all images. Skips already-cached entries. This makes the first Batch PhotoBrowser folder opening instant.
• Refresh stale — Detects images modified since last cache and updates their metadata and thumbnails.
• Cleanup orphans — Removes cache entries for deleted images and frees disk space.

Batch PhotoRater

Scans your photo library for poor quality images using configurable quality metrics. Helps you quickly find and deal with blurry, too dark, too bright, low contrast, or low entropy photos.

• 5 quality metrics — Blurry images (Laplacian variance), too dark, too bright, low contrast, and low entropy. Each has a configurable threshold slider.
• Filmstrip preview — Shows thumbnails of analyzed images in real-time during processing (up to 200).
• 3 action modes:
  • Choose individually — Review each flagged image with a 5-star rating dialog.
  • Rate as 1 star — Automatically rate all flagged images as 1 star.
  • Delete to trash — Move flagged images to the Recycle Bin.
• Skip already rated — Ignores images that already have a rating, so you don't re-review them.
• Statistics — Shows analyzed, flagged, rated, deleted, skipped, and error counts.

Batch PhotoFixer

Repairs corrupted JPEG files using a 6-stage pipeline that progressively attempts more aggressive recovery techniques. Includes camera-specific profile detection for Canon, Nokia, Apple, Samsung, Sony, Nikon, Olympus, Panasonic and more.

The 6-stage repair pipeline:

1. Structural — Validates and reorders JPEG markers (SOI, APP, DQT, DHT, SOF, SOS, EOI).
2. Tables — Restores missing or corrupted DQT/DHT tables using ITU-T T.81 standard references or camera-specific profiles.
3. Frame/Scan — Repairs SOF/SOS markers, recovers image dimensions from EXIF data.
4. Salvage — Progressive truncation decode, gray-fill for missing data, automatic quality detection.
5. Forensic — Extracts EXIF embedded thumbnail, searches for embedded JPEG streams within the file.
6. Advanced — Bit-flip correction, MCU re-alignment for severely damaged files.

After processing, the Review tab shows original vs. repaired side-by-side. Actions per image:

• Accept — Replace the original with the repaired version.
• Accept thumbnail — Save the recovered EXIF thumbnail as replacement.
• Save as copy — Keep the original and save a repaired copy alongside it.
• Reject — Discard the repair attempt.
• Move to trash — Delete the original to the Recycle Bin.

Corrupt Image Manager (Batch PhotoBrowser)

Batch PhotoBrowser includes a background scanner that detects corrupted images while you browse. Detected issues are collected in the Corrupt Image Manager dialog.

• Automatic detection — Runs in background during browsing, checking JPEG structure, EXIF integrity, and decode validity.
• File list — Shows file path, size, dimensions, exiftool status, SOI/SOS markers, and decoder status for each corrupt image.
• Image preview — Preview of the corrupt image with corruption analysis details.
• Quick actions — Open file path, delete image, filter by 1-star rating.
• Seamless handoff — Send selected files directly to Batch PhotoFixer for repair with one click.

Context Menu Integration

If you enabled "Add to right-click context menu" during installation, you can right-click any folder or image file and select Batch PhotoTools from the menu (in the classic context menu via Show more options on Windows 11, or Shift+F10).

Context	Action	Description
Folder	Reverse geolocate	Opens Batch Geolocate with the folder pre-selected
Folder	AI identify	Opens Batch Geolocate with AI mode pre-selected
Folder	Sync IPTC and XMP	Opens Batch MetadataSync with the folder pre-selected
Image file	Show location data	Displays location, keywords, and description fields
Image file	Reverse geolocate	Immediately geocodes and writes location data
Image file	AI identify	Immediately runs AI analysis and writes results

Metadata Fields Written

All fields are written to both IPTC and XMP standards for maximum compatibility across photo management software.

Field	IPTC Tag	XMP Tag	Source
Country	Country-PrimaryLocationName	XMP-photoshop:Country	Nominatim
State/Province	Province-State	XMP-photoshop:State	Nominatim
City	City	XMP-photoshop:City	Nominatim
Sublocation	Sub-location	XMP-iptcCore:Location	Nominatim
POI	—	XMP-iptcExt:LocationShownLocationName	OSM / User
Description	Caption-Abstract	XMP-dc:Description	AI
Keywords	Keywords	XMP-dc:Subject	AI
Rating	—	XMP-xmp:Rating	AI / User

Performance & Architecture

Batch PhotoTools is engineered for speed and designed to utilize all available hardware resources. Every bottleneck has been addressed with purpose-built optimizations:

• Multi-threaded pipeline — GPS reading, geocoding, exiftool writes, AI analysis, and thumbnail generation all run in dedicated worker threads, with UI never blocking.
• Spatial clustering — Images within 30m of each other are grouped into clusters. One API call per cluster instead of per image. 80,000 images clustered in seconds.
• In-memory geocode cache — All cached locations loaded into RAM at startup. Bounding-box pre-filter + haversine distance check in pure Python for instant lookups.
• Exiftool batch writes — One exiftool call per cluster for location fields, one call per 50 images for AI pre-checks. Minimizes subprocess overhead.
• Automatic background caching — Batch PhotoBrowser and Batch MetadataSync automatically maintain metadata caches and thumbnail stores in background threads. The cache detects modified files and refreshes them without user intervention.
• Three-tier thumbnail loading — EXIF embedded thumbnail for instant small previews, Pillow draft mode for medium sizes, full decode only when needed. Thread pool scales to (CPU cores × 2) − 2 workers.
• Virtual scroll with DOM recycling — Batch PhotoBrowser renders only visible thumbnails, recycling DOM elements as you scroll. Handles 60,000+ images without performance degradation.
• Multi-endpoint API rotation — Overpass API requests automatically rotate between 4+ endpoints with per-endpoint cooldown tracking. Startup health checks identify available endpoints before processing begins.

FAQ & Troubleshooting

Why don't Country/City show in Windows File Explorer?

Windows does not support displaying IPTC/XMP location fields in file properties. This is a Microsoft limitation. Use Adobe Bridge (free), Lightroom, DigiKam, or Batch PhotoBrowser to see all metadata.

Can I undo changes?

Batch Geolocate uses -overwrite_original so no backup files are created. Always keep backups of your photos before processing.

What image formats are supported?

JPEG (.jpg, .jpeg), TIFF (.tif, .tiff), PNG, and HEIC/HEIF files. GPS extraction requires EXIF data in the image.

What if I don't have GPS in my photos?

Location tagging requires GPS coordinates in the image EXIF data. Photos without GPS will be skipped for geocoding. However, you can manually assign locations using Batch PhotoBrowser's Location Painter tool. AI analysis works on all images regardless of GPS data.

How much does AI analysis cost?

Approximately 1 cent per 5 images using Kimi K2.5. A batch of 1,000 images costs about $2. Using multiple concurrent agents (3–6 recommended) speeds this up proportionally — the multi-agent architecture processes N images simultaneously. The program shows a cost warning when enabling AI for more than 1,000 images.

Overpass API keeps failing / rate limiting

Public Overpass API endpoints are rate-limited. The program rotates between multiple endpoints and applies cooldowns automatically. For large batches, enable "Continue on API fail" and download the POI database for your countries. If all endpoints fail and you don't have the country's data locally, the program will offer to automatically download it.

Processing seems stuck

Check the status bar at the bottom. If all API indicators are yellow (cooldown), the program is waiting for rate limits to expire. You can click Pause and resume later.

Batch PhotoBrowser is slow on first open

The first time Batch PhotoBrowser opens a folder, it reads metadata from all images and generates thumbnails. This is a one-time cost — the results are cached persistently. Subsequent opens are instant. You can pre-build the cache using Batch MetadataSync's Cache + Thumbnails tab to avoid this wait.