Skip to content

Fast and efficient Go library for looking up timezone information by city name, with support for partial matching, ISO code lookups, and flexible search options.

License

Notifications You must be signed in to change notification settings

richoandika/city-timezones-go

Repository files navigation

🌍 City Timezones Go

Go Reference Go Report Card CI Coverage License: MIT Go Version Release

A high-performance Go library for city timezone lookups

7,326 cities β€’ Zero dependencies β€’ Thread-safe β€’ 96.2% test coverage

Features β€’ Installation β€’ Quick Start β€’ Documentation β€’ Contributing


Overview

City Timezones Go is a fast, efficient Go library for looking up timezone information by city name. It provides multiple search strategies including exact matching, partial matching, and ISO code lookups with a simple, intuitive API.

Note: This is a Go port of the city-timezones JavaScript library by Kevin Roberts, delivering 10x performance improvements and full type safety.

Features

Feature Description
πŸ” Multiple Search Strategies Exact match, partial matching, ISO code lookups
⚑ High Performance LRU caching, lazy loading, 10x faster than JavaScript
πŸ”’ Thread-Safe Full concurrent access support with proper synchronization
πŸ›‘οΈ Security First Input validation, XSS prevention, injection protection
πŸ“¦ Zero Dependencies No external packages required
πŸ§ͺ Well-Tested 96.2% test coverage with race condition testing
🌐 Comprehensive Data 7,326 cities with timezone information
πŸ–₯️ CLI Tool Command-line interface included

Installation

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

Quick Start

package main

import (
    "fmt"
    "log"

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

func main() {
    // Look up a city by name
    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)
    }
}

Core API

Search Functions

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

// Partial matching across multiple fields
cities, err := citytimezones.FindFromCityStateProvince("springfield mo")

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

// Advanced search with options
options := citytimezones.SearchOptions{
    CaseSensitive: true,
    ExactMatch:    false,
}
cities, err := citytimezones.SearchCities("Chicago", options)

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

Cache Management

// Get cache statistics
stats := citytimezones.GetCacheStats()
fmt.Printf("Hit rate: %.2f%%\n", stats.HitRate)

// Check cache size
size := citytimezones.CacheSize()

// Clear cache if needed
citytimezones.ClearCache()

CLI Tool

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

# Or build from source
make build

# Search for a city
citytimezones -city Chicago

# Search with partial matching
citytimezones -search "springfield mo"

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

# Output as JSON
citytimezones -city Tokyo -output json

# Show version
citytimezones -version

Performance

City Timezones Go is highly optimized:

  • 10x faster than the JavaScript version
  • 7.5x less memory usage (~2MB vs ~15MB)
  • Microsecond lookups with caching (<100Β΅s)
  • Thread-safe with minimal lock contention

See PERFORMANCE.md for detailed benchmarks.

Documentation

Document Description
API Reference Complete API documentation
FAQ Frequently asked questions
Performance Guide Benchmarks and optimization tips
Development Guide Contributing and development workflow
Roadmap Feature roadmap and future plans
Examples Runnable code examples

Examples

Check out the examples/ directory for more:

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick start:

# Clone and setup
git clone https://github.com/richoandika/city-timezones-go.git
cd city-timezones-go
go mod download

# Run tests
make test

# Build
make build

See DEVELOPMENT.md for detailed development instructions.

Support

Type Link
πŸ“– Documentation docs/
πŸ› Bug Reports Issues
πŸ’‘ Feature Requests Issues
πŸ’¬ Discussions Discussions
πŸ”’ Security SECURITY.md

License

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

Attribution

This library is a Go port of the original city-timezones JavaScript library created by Kevin Roberts.

Key Improvements

  • ⚑ 10x faster execution
  • πŸ’Ύ 7.5x less memory usage
  • πŸ”’ Compile-time type safety
  • 🧡 Full thread-safe operations
  • πŸ§ͺ 96.2% test coverage
  • πŸ“¦ Zero dependencies

Acknowledgments

  • Kevin Roberts - Original JavaScript library author
  • Go Community - For excellent tooling and standards
  • Contributors - All who help improve this project

Made with ❀️ for the Go community

If you find this library useful, please consider giving it a ⭐

Code Size Last Commit

⬆ Back to Top

About

Fast and efficient Go library for looking up timezone information by city name, with support for partial matching, ISO code lookups, and flexible search options.

Topics

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Packages

No packages published