tessl/pypi-timezonefinder

Python package for finding the timezone of any point on earth (coordinates) offline

Overview

Eval results

Files

Command Line Interface

Name: tessl/pypi-timezonefinder
Author: tessl

Command-line utility for timezone lookups supporting multiple lookup methods and output formats. The CLI provides direct access to timezonefinder functionality from shell scripts, system integration, and interactive use.

Capabilities

Command Syntax

timezonefinder <longitude> <latitude> [options]

# Required arguments:
#   longitude    Longitude coordinate in degrees (-180.0 to 180.0)
#   latitude     Latitude coordinate in degrees (-90.0 to 90.0)

# Options:
#   -v           Enable verbose output (shows detailed lookup information)
#   -f FUNC_ID   Select lookup function (default: 0)
#   --function FUNC_ID  Select lookup function (same as -f)

Available Functions

The CLI supports multiple lookup functions selected via the -f or --function parameter:

# Function IDs:
# 0: TimezoneFinder.timezone_at() - Standard lookup (default)
# 1: TimezoneFinder.certain_timezone_at() - Exhaustive polygon checking
# 3: TimezoneFinderL.timezone_at() - Lightweight approximation
# 4: TimezoneFinderL.timezone_at_land() - Lightweight land-only lookup
# 5: TimezoneFinder.timezone_at_land() - Standard land-only lookup

Usage Examples

Basic Timezone Lookup

# Standard timezone lookup
timezonefinder 13.358 52.5061
# Output: Europe/Berlin

# Verbose output with details
timezonefinder 13.358 52.5061 -v
# Output:
# ============================================================
# TIMEZONEFINDER LOOKUP DETAILS
# ------------------------------------------------------------
# Coordinates: 52.506100°, 13.358000° (lat, lng)
# Function timezone_at (function ID: 0)
# Result: Found timezone 'Europe/Berlin'
# ============================================================

Different Lookup Methods

# Standard lookup (function 0)
timezonefinder 13.358 52.5061 -f 0
# Output: Europe/Berlin

# Exhaustive polygon checking (function 1)
timezonefinder 13.358 52.5061 -f 1
# Output: Europe/Berlin

# Lightweight approximation (function 3)
timezonefinder 13.358 52.5061 -f 3
# Output: Europe/Berlin

# Land-only lookup (function 5)
timezonefinder 13.358 52.5061 -f 5
# Output: Europe/Berlin

# Ocean coordinate with standard lookup
timezonefinder 0.0 0.0 -f 0
# Output: Etc/GMT

# Ocean coordinate with land-only lookup
timezonefinder 0.0 0.0 -f 5
# Output: (empty - no land timezone)

Batch Processing in Shell Scripts

#!/bin/bash

# Process multiple coordinates
coordinates=(
    "13.358 52.5061"    # Berlin
    "-74.0060 40.7128"  # New York
    "139.6917 35.6895"  # Tokyo
    "2.3522 48.8566"    # Paris
    "-0.1276 51.5074"   # London
)

echo "Timezone lookup results:"
for coord in "${coordinates[@]}"; do
    tz=$(timezonefinder $coord)
    echo "$coord -> $tz"
done

Error Handling

# Invalid coordinates
timezonefinder 200.0 52.5061
# Error output via stderr, empty stdout

# Invalid function ID
timezonefinder 13.358 52.5061 -f 99
# Error: argument -f/--function: invalid choice: 99

# Missing arguments
timezonefinder 13.358
# Error: the following arguments are required: lat

Integration with Other Tools

# Pipe coordinates from file
cat coordinates.txt | while read lng lat; do
    tz=$(timezonefinder "$lng" "$lat")
    echo "$lng,$lat,$tz"
done

# Use with xargs for parallel processing
cat coordinates.txt | xargs -n 2 -P 4 timezonefinder

# JSON output with jq integration
echo '{"lng": 13.358, "lat": 52.5061}' | \
jq -r '.lng, .lat' | \
xargs timezonefinder | \
jq -R '{"timezone": .}'

Performance Comparison

#!/bin/bash

# Compare different lookup methods
lng=13.358
lat=52.5061

echo "Performance comparison for ($lat, $lng):"

# Standard lookup
echo -n "Standard (f=0): "
time timezonefinder $lng $lat -f 0

# Exhaustive checking
echo -n "Exhaustive (f=1): "
time timezonefinder $lng $lat -f 1

# Lightweight
echo -n "Lightweight (f=3): "
time timezonefinder $lng $lat -f 3

Verbose Mode Details

When using the -v flag, the CLI provides detailed information about the lookup process:

timezonefinder 13.358 52.5061 -v -f 0

Output includes:

Coordinate formatting and validation
Selected function details
Lookup results with success/failure status
Performance information (when available)

Exit Codes

The CLI uses standard exit codes:

# Success (timezone found)
timezonefinder 13.358 52.5061
echo $?  # 0

# Success (no timezone found - valid for some coordinates)
timezonefinder 0.0 0.0 -f 5  # Land-only lookup on ocean
echo $?  # 0 (empty output but valid result)

# Error (invalid input)
timezonefinder 200.0 52.5061 2>/dev/null
echo $?  # Non-zero exit code

Advanced Scripting Examples

#!/bin/bash

# Function to validate and lookup timezone
lookup_timezone() {
    local lng="$1"
    local lat="$2"
    local func_id="${3:-0}"
    
    # Validate inputs
    if [[ ! "$lng" =~ ^-?[0-9]+\.?[0-9]*$ ]] || [[ ! "$lat" =~ ^-?[0-9]+\.?[0-9]*$ ]]; then
        echo "ERROR: Invalid coordinates" >&2
        return 1
    fi
    
    # Perform lookup
    local result
    result=$(timezonefinder "$lng" "$lat" -f "$func_id" 2>/dev/null)
    local exit_code=$?
    
    if [ $exit_code -eq 0 ]; then
        if [ -n "$result" ]; then
            echo "$result"
        else
            echo "NO_TIMEZONE"
        fi
    else
        echo "LOOKUP_ERROR" >&2
        return 1
    fi
}

# Bulk processing with error handling
process_coordinates() {
    local input_file="$1"
    local output_file="$2"
    
    echo "lng,lat,timezone,status" > "$output_file"
    
    while IFS=',' read -r lng lat; do
        if tz=$(lookup_timezone "$lng" "$lat"); then
            echo "$lng,$lat,$tz,SUCCESS" >> "$output_file"
        else
            echo "$lng,$lat,,ERROR" >> "$output_file"
        fi
    done < "$input_file"
}

# Usage
# process_coordinates "input.csv" "output.csv"

Integration with Monitoring Systems

#!/bin/bash

# Health check script for timezone service
check_timezone_service() {
    local test_lng=13.358
    local test_lat=52.5061
    local expected="Europe/Berlin"
    
    local result
    result=$(timezonefinder "$test_lng" "$test_lat" 2>/dev/null)
    
    if [ "$result" = "$expected" ]; then
        echo "OK: Timezone service operational"
        return 0
    else
        echo "ERROR: Timezone service failed. Expected '$expected', got '$result'"
        return 1
    fi
}

# Run health check
if check_timezone_service; then
    # Service is healthy
    exit 0
else
    # Service has issues
    exit 1
fi

Install with Tessl CLI