0
# Command Line Interface
1

2
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.
3

4
## Capabilities
5

6
### Command Syntax
7

8
```bash { .api }
9
timezonefinder <longitude> <latitude> [options]
10

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

15
# Options:
16
#   -v           Enable verbose output (shows detailed lookup information)
17
#   -f FUNC_ID   Select lookup function (default: 0)
18
#   --function FUNC_ID  Select lookup function (same as -f)
19
```
20

21
### Available Functions
22

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

25
```bash { .api }
26
# Function IDs:
27
# 0: TimezoneFinder.timezone_at() - Standard lookup (default)
28
# 1: TimezoneFinder.certain_timezone_at() - Exhaustive polygon checking
29
# 3: TimezoneFinderL.timezone_at() - Lightweight approximation
30
# 4: TimezoneFinderL.timezone_at_land() - Lightweight land-only lookup
31
# 5: TimezoneFinder.timezone_at_land() - Standard land-only lookup
32
```
33

34
## Usage Examples
35

36
### Basic Timezone Lookup
37

38
```bash
39
# Standard timezone lookup
40
timezonefinder 13.358 52.5061
41
# Output: Europe/Berlin
42

43
# Verbose output with details
44
timezonefinder 13.358 52.5061 -v
45
# Output:
46
# ============================================================
47
# TIMEZONEFINDER LOOKUP DETAILS
48
# ------------------------------------------------------------
49
# Coordinates: 52.506100°, 13.358000° (lat, lng)
50
# Function timezone_at (function ID: 0)
51
# Result: Found timezone 'Europe/Berlin'
52
# ============================================================
53
```
54

55
### Different Lookup Methods
56

57
```bash
58
# Standard lookup (function 0)
59
timezonefinder 13.358 52.5061 -f 0
60
# Output: Europe/Berlin
61

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

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

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

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

78
# Ocean coordinate with land-only lookup
79
timezonefinder 0.0 0.0 -f 5
80
# Output: (empty - no land timezone)
81
```
82

83
### Batch Processing in Shell Scripts
84

85
```bash
86
#!/bin/bash
87

88
# Process multiple coordinates
89
coordinates=(
90
    "13.358 52.5061"    # Berlin
91
    "-74.0060 40.7128"  # New York
92
    "139.6917 35.6895"  # Tokyo
93
    "2.3522 48.8566"    # Paris
94
    "-0.1276 51.5074"   # London
95
)
96

97
echo "Timezone lookup results:"
98
for coord in "${coordinates[@]}"; do
99
    tz=$(timezonefinder $coord)
100
    echo "$coord -> $tz"
101
done
102
```
103

104
### Error Handling
105

106
```bash
107
# Invalid coordinates
108
timezonefinder 200.0 52.5061
109
# Error output via stderr, empty stdout
110

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

115
# Missing arguments
116
timezonefinder 13.358
117
# Error: the following arguments are required: lat
118
```
119

120
### Integration with Other Tools
121

122
```bash
123
# Pipe coordinates from file
124
cat coordinates.txt | while read lng lat; do
125
    tz=$(timezonefinder "$lng" "$lat")
126
    echo "$lng,$lat,$tz"
127
done
128

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

132
# JSON output with jq integration
133
echo '{"lng": 13.358, "lat": 52.5061}' | \
134
jq -r '.lng, .lat' | \
135
xargs timezonefinder | \
136
jq -R '{"timezone": .}'
137
```
138

139
### Performance Comparison
140

141
```bash
142
#!/bin/bash
143

144
# Compare different lookup methods
145
lng=13.358
146
lat=52.5061
147

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

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

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

158
# Lightweight
159
echo -n "Lightweight (f=3): "
160
time timezonefinder $lng $lat -f 3
161
```
162

163
### Verbose Mode Details
164

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

167
```bash
168
timezonefinder 13.358 52.5061 -v -f 0
169
```
170

171
Output includes:
172
- Coordinate formatting and validation
173
- Selected function details
174
- Lookup results with success/failure status
175
- Performance information (when available)
176

177
### Exit Codes
178

179
The CLI uses standard exit codes:
180

181
```bash
182
# Success (timezone found)
183
timezonefinder 13.358 52.5061
184
echo $?  # 0
185

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

190
# Error (invalid input)
191
timezonefinder 200.0 52.5061 2>/dev/null
192
echo $?  # Non-zero exit code
193
```
194

195
### Advanced Scripting Examples
196

197
```bash
198
#!/bin/bash
199

200
# Function to validate and lookup timezone
201
lookup_timezone() {
202
    local lng="$1"
203
    local lat="$2"
204
    local func_id="${3:-0}"
205
    
206
    # Validate inputs
207
    if [[ ! "$lng" =~ ^-?[0-9]+\.?[0-9]*$ ]] || [[ ! "$lat" =~ ^-?[0-9]+\.?[0-9]*$ ]]; then
208
        echo "ERROR: Invalid coordinates" >&2
209
        return 1
210
    fi
211
    
212
    # Perform lookup
213
    local result
214
    result=$(timezonefinder "$lng" "$lat" -f "$func_id" 2>/dev/null)
215
    local exit_code=$?
216
    
217
    if [ $exit_code -eq 0 ]; then
218
        if [ -n "$result" ]; then
219
            echo "$result"
220
        else
221
            echo "NO_TIMEZONE"
222
        fi
223
    else
224
        echo "LOOKUP_ERROR" >&2
225
        return 1
226
    fi
227
}
228

229
# Bulk processing with error handling
230
process_coordinates() {
231
    local input_file="$1"
232
    local output_file="$2"
233
    
234
    echo "lng,lat,timezone,status" > "$output_file"
235
    
236
    while IFS=',' read -r lng lat; do
237
        if tz=$(lookup_timezone "$lng" "$lat"); then
238
            echo "$lng,$lat,$tz,SUCCESS" >> "$output_file"
239
        else
240
            echo "$lng,$lat,,ERROR" >> "$output_file"
241
        fi
242
    done < "$input_file"
243
}
244

245
# Usage
246
# process_coordinates "input.csv" "output.csv"
247
```
248

249
### Integration with Monitoring Systems
250

251
```bash
252
#!/bin/bash
253

254
# Health check script for timezone service
255
check_timezone_service() {
256
    local test_lng=13.358
257
    local test_lat=52.5061
258
    local expected="Europe/Berlin"
259
    
260
    local result
261
    result=$(timezonefinder "$test_lng" "$test_lat" 2>/dev/null)
262
    
263
    if [ "$result" = "$expected" ]; then
264
        echo "OK: Timezone service operational"
265
        return 0
266
    else
267
        echo "ERROR: Timezone service failed. Expected '$expected', got '$result'"
268
        return 1
269
    fi
270
}
271

272
# Run health check
273
if check_timezone_service; then
274
    # Service is healthy
275
    exit 0
276
else
277
    # Service has issues
278
    exit 1
279
fi
280
```