City Timezones Go

A high-performance, thread-safe Go library for city timezone lookups with comprehensive coverage of 7,326 cities worldwide.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage
  • Basic Lookups
  • Advanced Searches
  • Cache Management
• CLI Tool
• Performance
• Documentation
• Examples
• Contributing
• License
• Acknowledgments

Overview

City Timezones Go provides fast and efficient timezone information lookups by city name, supporting multiple search strategies including exact matching, partial matching, and ISO code queries. Built with performance and reliability in mind, it features zero external dependencies, comprehensive test coverage, and full thread safety.

This library is a Go port of the city-timezones JavaScript library by Kevin Roberts, offering significant performance improvements and compile-time type safety.

Features

• Multiple Search Strategies: Exact match, partial matching, and ISO code lookups
• High Performance: LRU caching with lazy loading, optimized for speed
• Thread-Safe: Full concurrent access support with proper synchronization
• Security Hardened: Input validation, XSS prevention, and injection protection
• Zero Dependencies: No external packages required
• Well Tested: 96.2% test coverage including race condition testing
• Comprehensive Dataset: 7,326 cities with accurate timezone information
• CLI Tool: Command-line interface for interactive queries

Installation

go get github.com/richoandika/city-timezones-go

Requirements: Go 1.21 or higher

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/richoandika/city-timezones-go/pkg/citytimezones"
)

func main() {
    cities, err := citytimezones.LookupViaCity("Chicago")
    if err != nil {
        log.Fatal(err)
    }

    if len(cities) > 0 {
        city := cities[0]
        fmt.Printf("City: %s, %s\n", city.City, city.Province)
        fmt.Printf("Timezone: %s\n", city.Timezone)
        fmt.Printf("Coordinates: %.4f, %.4f\n", city.Lat, city.Lng)
    }
}

Usage

Basic Lookups

// Exact city name match (case-insensitive)
cities, err := citytimezones.LookupViaCity("Chicago")

// Partial matching across city, state, and province
cities, err := citytimezones.FindFromCityStateProvince("springfield mo")

// Search by ISO2 or ISO3 country codes
cities, err := citytimezones.FindFromIsoCode("DE")

// Retrieve all cities
allCities, err := citytimezones.GetCityMapping()

Advanced Searches

// Configure search options
options := citytimezones.SearchOptions{
    CaseSensitive: true,
    ExactMatch:    false,
}

cities, err := citytimezones.SearchCities("Chicago", options)
if err != nil {
    log.Fatal(err)
}

for _, city := range cities {
    fmt.Printf("%s, %s (%s)\n", city.City, city.Country, city.Timezone)
}

Cache Management

// Retrieve cache statistics
stats := citytimezones.GetCacheStats()
fmt.Printf("Cache hit rate: %.2f%%\n", stats.HitRate)
fmt.Printf("Total hits: %d\n", stats.Hits)
fmt.Printf("Total misses: %d\n", stats.Misses)

// Check current cache size
size := citytimezones.CacheSize()
fmt.Printf("Cached entries: %d\n", size)

// Clear cache when needed
citytimezones.ClearCache()

CLI Tool

Install the command-line tool:

go install github.com/richoandika/city-timezones-go/cmd/citytimezones@latest

Or build from source:

make build

CLI Examples

# Search for a specific city
citytimezones -city Chicago

# Partial search with multiple keywords
citytimezones -search "springfield mo"

# Search by ISO country code
citytimezones -iso DE -limit 5

# Output results as JSON
citytimezones -city Tokyo -output json

# Display version information
citytimezones -version

Performance

City Timezones Go delivers exceptional performance:

• 10x faster than the original JavaScript implementation
• 7.5x lower memory footprint (~2MB vs ~15MB)
• Sub-100µs lookups with LRU caching enabled
• Thread-safe operations with minimal lock contention

For detailed benchmarks and optimization guidelines, see PERFORMANCE.md.

Documentation

Comprehensive documentation is available in the docs/ directory:

• API Reference - Complete API documentation with examples
• Performance Guide - Benchmarks and optimization techniques
• Development Guide - Contributing and development workflow
• FAQ - Frequently asked questions
• Roadmap - Future features and planned improvements

Examples

The examples/ directory contains practical code samples:

• Basic Usage - Simple lookups and search operations
• Advanced Usage - Concurrent access, caching strategies, error handling
• CLI Usage - Command-line interface examples

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting pull requests.

Development Setup

# Clone the repository
git clone https://github.com/richoandika/city-timezones-go.git
cd city-timezones-go

# Install dependencies
go mod download

# Run tests
make test

# Build the project
make build

For detailed development instructions, see DEVELOPMENT.md.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

This library is a Go port of the city-timezones JavaScript library created by Kevin Roberts. The Go implementation introduces significant performance improvements, type safety, and thread-safe operations while maintaining compatibility with the original dataset.

Special thanks to:

• Kevin Roberts - Original JavaScript library author
• Go Community - For excellent tooling and development standards
• All Contributors - For their valuable contributions to this project

---

Project Status: Active maintenance and development

For bug reports and feature requests, please use the GitHub Issues page.

For security vulnerabilities, see our Security Policy.