Python Photo Location Tagger

A Python utility to add GPS location metadata to images and videos based on timestamps from a CSV file (e.g., Home Assistant location history).

Features

• Reads location data (latitude, longitude) from CSV files
• Matches images and videos to coordinates based on closest timestamp match
• Extracts timestamps from EXIF data, video metadata, or filename
• Adds GPS coordinates to image EXIF metadata and video metadata
• Preserves original quality (no re-encoding for videos)
• Supports multiple formats:
  • Images: JPG, JPEG, PNG, TIFF
  • Videos: MP4, MOV, AVI, MKV, M4V
• Detailed logging showing which coordinates are assigned to each file
• Verification tool to check GPS metadata in processed images and videos

Quick Start with Docker (Recommended)

The easiest way to use these tools is with Docker - no need to install Python or ffmpeg!

Prerequisites: Place at least one .csv file with location data in the project directory.

# Build the Docker images
make build

# Process your images/videos (automatically uses first .csv file found)
make tag

# Verify the results
make verify

The make tag command will automatically use the first .csv file it finds in the current directory. To use a specific CSV file, set the CSV_FILE environment variable:

CSV_FILE=my_locations.csv make tag

For detailed Docker usage, see DOCKER.md.

Using Docker Run Commands Directly

If you prefer to use docker run instead of make commands:

Build the images:

docker build -t photo-location-tagger:latest -f Dockerfile.tagger .
docker build -t photo-location-verify:latest -f Dockerfile.verify .

Tag images/videos with GPS coordinates:

docker run --rm \
  -v "$(pwd)/input:/input:ro" \
  -v "$(pwd)/output:/output" \
  -v "$(pwd)/your_coordinates.csv:/csv/coordinates.csv:ro" \
  photo-location-tagger:latest \
  --input-folder /input \
  --output-folder /output \
  --csv-file /csv/coordinates.csv

Verify GPS metadata in a folder:

docker run --rm \
  -v "$(pwd)/output:/data:ro" \
  photo-location-verify:latest \
  /data

Verify GPS metadata in a single file:

docker run --rm \
  -v "$(pwd)/output:/data:ro" \
  photo-location-verify:latest \
  /data/your-file.jpg

Installation (Python)

1. Clone or download this repository

2. Install ffmpeg (required for video processing):

   # Ubuntu/Debian
   sudo apt install ffmpeg
   
   # macOS
   brew install ffmpeg
   
   # Windows
   # Download from https://ffmpeg.org/download.html
   

3. Create a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

4. Install Python dependencies:

   pip install -r requirements.txt
   

Scripts

1. add_location_metadata.py

Main script that adds GPS coordinates to images and videos.

Usage

python src/add_location_metadata.py -i INPUT_FOLDER -o OUTPUT_FOLDER -c CSV_FILE

Parameters

• -i, --input-folder: Path to folder containing input images and videos (required)
• -o, --output-folder: Path to folder where processed files will be saved (required)
• -c, --csv-file: Path to CSV file containing timestamp and location data (required)

Example

Process images from the input folder using coordinates from your CSV file:

python src/add_location_metadata.py \
  --input-folder ./input \
  --output-folder ./output \
  --csv-file your_coordinates.csv

Output Example

Loading location data from your_coordinates.csv...
Loaded 6830 location entries
Found 3 file(s) to process:
  Images: 2
  Videos: 1
Output directory: /home/user/output

================================================================================

[1/3] Processing video: 20240910_121507.mp4
--------------------------------------------------------------------------------
  Input:  /home/user/input/20240910_121507.mp4
  Using timestamp from filename
  Video timestamp: 2024-09-10 12:15:07
  CSV timestamp:   2024-09-10 12:11:28
  Time difference: 219 seconds

  GPS COORDINATES TO BE ADDED:
    Latitude:  37.9417912°
    Longitude: 12.8357155°
    Maps link: https://www.google.com/maps?q=37.9417912,12.8357155

  Writing GPS metadata to video...
  Output: /home/user/output/20240910_121507.mp4
  ✓ STATUS: SUCCESS
================================================================================

[2/3] Processing image: 20240910_114356.jpg
--------------------------------------------------------------------------------
  Input:  /home/user/input/20240910_114356.jpg
  Using timestamp from filename
  Image timestamp: 2024-09-10 11:43:56
  CSV timestamp:   2024-09-10 11:43:55
  Time difference: 1 seconds

  GPS COORDINATES TO BE ADDED:
    Latitude:  37.9254224°
    Longitude: 12.7316600°
    Maps link: https://www.google.com/maps?q=37.9254224,12.73166

  Writing GPS metadata to image...
  Output: /home/user/output/20240910_114356.jpg
  ✓ STATUS: SUCCESS
================================================================================

Processing complete!
Successfully processed: 3
Skipped: 0

2. verify_gps_metadata.py

Verification script that reads and displays GPS coordinates from image EXIF data and video metadata.

Usage

Verify a single file (image or video):

python src/verify_gps_metadata.py image.jpg
python src/verify_gps_metadata.py video.mp4

Verify all files in a folder:

python src/verify_gps_metadata.py ./output
# or
python src/verify_gps_metadata.py -f ./output

Example Output

Folder verification:

Checking 3 file(s) in ./output
  Images: 2
  Videos: 1

================================================================================

20240910_114356.jpg (image)
--------------------------------------------------------------------------------
  Latitude (DMS):  ((37, 1), (55, 1), (3152, 100)) N
  Latitude (Dec):  37.9254222°
  Longitude (DMS): ((12, 1), (43, 1), (5397, 100)) E
  Longitude (Dec): 12.7316583°
  Google Maps:     https://www.google.com/maps?q=37.9254222,12.7316583

20240910_121507.mp4 (video)
--------------------------------------------------------------------------------
  Latitude:  37.9418000°
  Longitude: 12.8357000°
  ISO 6709 format: +37.9418+012.8357/
  Google Maps:     https://www.google.com/maps?q=37.9418,12.8357

================================================================================

Summary:
  Files with GPS data: 3
  Files without GPS:   0
  Total files:         3

Single file verification:

Verifying video: ./output/20240910_121507.mp4

Latitude:  37.9418000°
Longitude: 12.8357000°
ISO 6709 format: +37.9418+012.8357/
Google Maps:     https://www.google.com/maps?q=37.9418,12.8357

CSV File Format

The CSV file should have the following columns:

• timestamp: Date and time in format YYYY-MM-DD HH:MM:SS
• latitude: Latitude in decimal degrees
• longitude: Longitude in decimal degrees

Example:

timestamp,latitude,longitude
2024-09-10 11:43:56,50.9704676,4.4777719
2024-09-10 11:49:27,50.9704965,4.4777345

How It Works

1. The script loads all location data from the CSV file
2. For each file (image or video) in the input folder:
   • Extracts the timestamp (from filename first, then metadata)
   • Finds the CSV entry with the closest matching timestamp
   • Adds GPS coordinates to the file metadata
   • Saves the modified file to the output folder
3. The original files in the input folder remain unchanged

Timestamp Matching

The script uses the following priority for extracting timestamps:

For Images:

1. Filename parsing (format: YYYYMMDD_HHMMSS.jpg) - Used first if filename is in date format
2. EXIF DateTimeOriginal tag - When the photo was taken (if filename is not in date format)
3. EXIF DateTime tag - General date/time metadata (fallback)

For Videos:

1. Filename parsing (format: YYYYMMDD_HHMMSS.mp4) - Used first if filename is in date format
2. Video metadata - Creation time from video container metadata (if filename is not in date format)

This allows you to override metadata by renaming files with specific timestamps.

Notes

• The output folder will be created automatically if it doesn't exist
• Original files are not modified; only copies in the output folder contain GPS data
• Images: Saved with high quality (95% JPEG quality)
• Videos: Copied without re-encoding (stream copy mode) - very fast, no quality loss
• The script shows the time difference between the file and matched location for verification
• Google Maps links are generated in the logs for easy location verification
• ffmpeg is required for video processing (timestamps and GPS metadata)