timezone-tools

# Timezone Tools

Get current time in any timezone and convert times between different timezones using IANA timezone database.

## Quick Start

### Get current time in a timezone

```bash
python scripts/get_time.py" "America/New_York"
```

### Convert time between timezones

```bash
python scripts/convert_time.py" "America/New_York" "14:30" "Australia/Perth"
```

### Search for timezone names

```bash
python scripts/list_timezones.py" "perth"
```

## Instructions

When the user asks about time or timezones:

1. **For current time queries** (e.g., "What time is it in Tokyo?"):
   - Use `scripts/get_time.py` with IANA timezone name
   - If unsure of timezone name, search first with `list_timezones.py`
   - Script outputs: timezone, datetime, day of week, DST status

2. **For time conversions** (e.g., "What's 2pm EST in Perth time?"):
   - Use `scripts/convert_time.py` with source timezone, time (HH:MM 24-hour), target timezone
   - Script shows source time, target time, and time difference
   - Automatically handles DST changes

3. **For timezone searches**:
   - Use `scripts/list_timezones.py` with city/country name
   - Returns matching IANA timezone names

## Common Timezones Reference

For quick reference, see [data/common_timezones.json](data/common_timezones.json) which includes major cities worldwide, with Perth prominently featured.

**User's local timezone**: The scripts automatically detect your local timezone using `tzlocal`.

## Examples

### Example 1: Current time query

User: "What time is it in Perth?"

```bash
python scripts/list_timezones.py" "perth"
# Output: Australia/Perth

python scripts/get_time.py" "Australia/Perth"
# Output:
# Timezone: Australia/Perth
# Current time: 2025-11-07T15:30:45
# Day: Thursday
# DST: No
```

### Example 2: Time conversion

User: "I have a meeting at 2pm New York time, what time is that in Perth?"

```bash
python scripts/convert_time.py" "America/New_York" "14:00" "Australia/Perth"
# Output:
# Source: America/New_York