GeoCapture

A lightweight geocoding tool that converts addresses to geographic coordinates using the Nominatim API (OpenStreetMap), with optional map downloading capability.

Features

• Convert addresses to latitude/longitude coordinates via Nominatim API
• Optionally download map images using external download tool
• Support two input formats:
  • Address-only: automatically queries coordinates via API
  • With coordinates: uses provided coordinates directly (no API call)
• Expand coordinates to create a bounding box for map download
• Batch processing from input file

Requirements

• Python 3.11+
• httpx

Install dependencies:

pip install -r requirements.txt

Configuration (config.toml)

[input]
input_file = "./locations.txt"
save_coords = false
output_coords = "./coords.txt"

[download]
expansion = 0.0001
exe_path = "C:\\Users\\ThinkPad\\my_own_files\\work\\projects\\shujupingtai\\yuhan_data\\tilemosaic\\HuTilesMosaic.exe"
url = "http://172.22.63.226:9877/services/wgs84/startlvlone/wmts"
save_dir = "C:\\Users\\ThinkPad\\my_own_files\\work\\projects\\shujupingtai\\yuhan_data\\tilemosaic\\output"
zoom = 20
level = 3

Input File Format (locations.txt)

Each line can be in one of two formats:

Format 1: Address Only

Taiwan Taoyuan
Tsing Hua University
Beijing Tiananmen

The tool will query coordinates from Nominatim API automatically.

Format 2: With Coordinates

Beijing Tiananmen 39.907359 116.391263
Shanghai Oriental Pearl 31.2419464 121.4952604

The tool uses the provided coordinates directly without calling the API.

Lines starting with # are treated as comments.

Usage

1. Geocode Only (No Download)

python geocapture.py

Output:

Taiwan Taoyuan  24.988726  121.3137769
Tsing Hua University  24.7916987  120.9924295
Beijing Tiananmen  39.907359  116.391263
Shanghai Oriental Pearl  31.2419464  121.4952604

2. Geocode and Download Map

python geocapture.py --download

This will:

1. Query coordinates from Nominatim API
2. Expand coordinates by ±0.0001 degrees (configurable via expansion)
3. Call the download tool to fetch map images

Example output for download mode:

Found 4 locations to process
--------------------------------------------------
Taiwan Taoyuan  24.988726  121.3137769
...
--------------------------------------------------
Starting map download...

Taiwan Taoyuan:
  Original: (24.988726, 121.3137769)
  Expanded: min_lon=121.3136769, max_lon=121.3138769, max_lat=24.988826, min_lat=24.988626
Executing: C:/Users/huang/Desktop/tilemosaic/HuTilesMosaic.exe ...
Downloaded: C:/Users/huang/Desktop/temp/tif/Taiwan Taoyuan.tiff

Configuration Parameters

[download] Section

Parameter	Description	Default
expansion	Coordinate expansion range in degrees	0.0001
exe_path	Path to download tool executable	-
url	Remote WMTS URL	-
save_dir	Local save directory	-
zoom	Zoom level (layers)	20
level	Type/level parameter	3

Download Tool Command Format

The tool calls the external download tool with the following command format:

<exe_path> <url> <save_dir> <save_path> <min_lon> <max_lon> <max_lat> <min_lat> <zoom> <level>

Parameters:

• min_lon, max_lon: Left-bottom and right-top longitude
• max_lat, min_lat: Right-top and left-bottom latitude

API Rate Limiting

Nominatim API has a rate limit of 1 request per second. The tool automatically includes a 1.1 second delay between API calls to comply with this limit.