README
¶
GeoDecode
GeoDecode is a Go package that provides offline reverse geocoding. It allows you to find the nearest city and country for a given latitude and longitude coordinate.
What it Does
This package takes a geographic coordinate (latitude and longitude) and returns the name of the closest known city and its country code. It's designed for quick lookups using an embedded dataset.
Features
-
Offline Reverse Geocoding: Works without an internet connection after initial setup.
-
City and Country Lookup: Provides the name of the nearest city and its ISO Alpha-2 country code.
-
Fast Lookups: Uses a KD-Tree for efficient nearest neighbor searches on a large dataset.
-
Embedded Data: The necessary geographic data is bundled directly into the package.
Installation
To use GeoDecode in your Go project, you can install it using go get:
go get github.com/sdwillbrand/GeoDecode
Usage
Here's a simple example of how to use GeoDecode in your Go application:
package main
import (
"fmt"
"github.com/sdwillbrand/GeoDecode" // Import the GeoDecode package
)
func main() {
// Define a coordinate (e.g., Berlin, Germany)
coords := [2]float64{52.5200, 13.4050} // [lat, lng]
// Find the nearest location.
// The 'true' argument enables verbose logging during the initial data load.
location := geodecode.FindLocation(coords, true)
if location != nil {
fmt.Printf("Found Location:\n")
fmt.Printf(" City: %s\n", location.City)
fmt.Printf(" Country Code: %s\n", location.CC)
fmt.Printf(" Latitude: %.5f, Longitude: %.5f\n", location.Lat, location.Lon)
} else {
fmt.Println("Location not found for the given coordinates.")
}
// Example with an ocean coordinate (will return the nearest land location)
oceanCoords := [2]float64{0.0, 0.0}
oceanLocation := geodecode.FindLocation(oceanCoords, false) // No verbose logging for subsequent calls
if oceanLocation != nil {
fmt.Printf("\nClosest to ocean (0,0):\n")
fmt.Printf(" City: %s\n", oceanLocation.City)
fmt.Printf(" Country Code: %s\n", oceanLocation.CC)
}
}
Data Source
The geographic data used by GeoDecode is sourced from rg_cities1000.csv. This CSV file contains a list of cities with their coordinates and administrative information. The file is embedded directly into the Go package for ease of use.
Contributing
If you find issues or have suggestions, please open an issue on the GitHub repository.
License
GeoDecode is free and open source project licensed under the MIT License.
Documentation
¶
Overview ¶
Package geodecode provides functionality to find the nearest geographical location (city, town) for a given latitude and longitude coordinate from a pre-loaded dataset. It utilizes a KD-Tree for efficient nearest neighbor searches.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetCountryByCode ¶ added in v0.9.4
GetCountryByCode returns the full country name for a given ISO country code (e.g., "US", "GB"). It uses the github.com/biter777/countries package for lookup.
Example usage:
countryName := geodecode.GetCountryByCode("US")
fmt.Println(countryName) // Output: United States
Types ¶
type Location ¶
type Location struct {
Lat float64 // Latitude of the location.
Lon float64 // Longitude of the location.
City string // Name of the location (e.g., city name).
Admin1 string // First-level administrative division (e.g., state, province).
Admin2 string // Second-level administrative division (e.g., county, region).
CC string // Country Code (e.g., US, GB).
Country string // Name of the country
}
Location represents a geographical point with associated administrative data.
func FindLocation ¶
FindLocation is a convenience function to query the geocoder directly for a single coordinate. It returns a pointer to the nearest Location found, or nil if no location is found (e.g., input coordinate is invalid or no data is loaded). The 'verbose' parameter controls logging for the internal geocoder instance.
coordinate: [lat, lng]
Example usage:
location := geodecode.FindLocation([2]float64{34.0522, -118.2437}, false) // Los Angeles
if location != nil {
fmt.Printf("City: %s, Country: %s\n", location.City, location.Country)
}
type RGeocoder ¶
type RGeocoder struct {
// contains filtered or unexported fields
}
RGeocoder represents the main reverse geocoding service. It holds the KD-Tree and the loaded location data.
func GetRGeocoder ¶
GetRGeocoder returns a singleton instance of the reverse geocoder. The geocoder's data is loaded and the KD-Tree is built only once, on the first call to this function. The 'verbose' parameter controls whether detailed loading and warning messages are printed to the console.
Source Files
Directories