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
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.
| 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 |
go get github.com/richoandika/city-timezones-gopackage 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)
}
}// 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()// 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()# 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 -versionCity 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.
| 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 |
Check out the examples/ directory for more:
- Basic Usage - Simple lookups and searches
- Advanced Usage - Concurrent access, caching, error handling
- CLI Usage - Command-line examples
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 buildSee DEVELOPMENT.md for detailed development instructions.
| Type | Link |
|---|---|
| π Documentation | docs/ |
| π Bug Reports | Issues |
| π‘ Feature Requests | Issues |
| π¬ Discussions | Discussions |
| π Security | SECURITY.md |
This project is licensed under the MIT License - see the LICENSE file for details.
This library is a Go port of the original city-timezones JavaScript library created by Kevin Roberts.
- β‘ 10x faster execution
- πΎ 7.5x less memory usage
- π Compile-time type safety
- π§΅ Full thread-safe operations
- π§ͺ 96.2% test coverage
- π¦ Zero dependencies
- 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 β