iNatGeoTagger

Automatically geotag photos by matching their capture timestamps with GPS tracks stored in a KML (gx:Track) file.

This tool is designed for photographers and iNaturalist users who record GPS tracks separately (e.g., with a phone or GPS logger) and want to write location information into their photos before uploading.

📖 Chinese documentation: README_zh.md

• Read GPS tracks from KML (gx:Track) files.
• Scan all JPG/JPEG images in a folder.
• Read capture timestamps from EXIF metadata.
• Fall back to the file modification time if EXIF timestamps are unavailable.
• Support configurable photo timezone offsets.
• Automatically convert photo timestamps to UTC before matching.
• Efficiently locate the nearest GPS point using binary search (bisect).
• Write GPS coordinates into the image EXIF metadata.
• Preserve image quality (metadata only).
• Print detailed processing logs.

• Python 3.9 or later

Install dependencies:

pip install lxml piexif

Assuming the photos were taken in UTC+8 (default):

python iNatGeoTagger.py track.kml photos/

For example, photos taken in Japan (UTC+9):

python iNatGeoTagger.py track.kml photos/ 9

Photos taken in London during winter (UTC+0):

python iNatGeoTagger.py track.kml photos/ 0

Photos taken in New York (UTC−5):

python iNatGeoTagger.py track.kml photos/ -5

The program performs the following steps:

1. Load and parse the GPS track from the KML file.
2. Read each photo's capture timestamp.
3. Interpret the timestamp using the specified timezone.
4. Convert the timestamp to UTC.
5. Use binary search (bisect) to locate the nearest GPS point.
6. Find the GPS point with the closest timestamp and write its latitude and longitude into the photo's EXIF metadata.

KML (gx:Track) timestamps are stored in UTC.

However, most cameras and smartphones save EXIF timestamps as local time without recording the timezone.

For example:

The program assumes that the EXIF timestamp belongs to the specified timezone, converts it to UTC internally, and then performs timestamp matching.

This solves the common issue where photo timestamps and GPS tracks differ by a fixed number of hours.

• Supports KML gx:Track files.
• Processes JPG/JPEG images only.
• Existing GPS EXIF metadata will be overwritten.
• Other EXIF metadata is preserved.
• The image content is not recompressed.
• It is recommended to back up your photos before processing.

The most common reason is an incorrect timezone.

For example, if:

• the KML timestamps are in UTC, and
• the photos were taken in Japan,

run:

python iNatGeoTagger.py track.kml photos/ 9

Check whether the correct timezone offset is specified.