GoGIS is a comprehensive Go library that provides PostGIS geometry types for GORM, enabling seamless integration of spatial data with your Go applications.
✨ Complete PostGIS Integration - Full support for Point, LineString, Polygon, and GeometryCollection types
🚀 GORM Compatible - Implements sql.Scanner and driver.Valuer for automatic ORM integration
🗺️ WGS 84 Support - Uses SRID 4326 coordinate system for global geographic data
📐 Well-Known Formats - Supports both WKB (Well-Known Binary) and WKT (Well-Known Text)
⚡ High Performance - Optimized for spatial queries with proper indexing support
🧪 Thoroughly Tested - Comprehensive test suite with >95% coverage
📚 Well Documented - Complete API documentation and usage examples
go get github.com/restayway/gogis- Go 1.19+
- PostgreSQL 12+ with PostGIS 3.0+
- GORM v2
Enable PostGIS extension in your PostgreSQL database:
CREATE EXTENSION IF NOT EXISTS postgis;package main
import (
"github.com/restayway/gogis"
"gorm.io/driver/postgres"
"gorm.io/gorm"
)
type Location struct {
ID uint `gorm:"primaryKey"`
Name string `gorm:"not null"`
Point gogis.Point `gorm:"type:geometry(Point,4326)"`
}
func main() {
// Connect to database
db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
if err != nil {
panic(err)
}
// Auto-migrate
db.AutoMigrate(&Location{})
// Create location
location := Location{
Name: "Statue of Liberty",
Point: gogis.Point{
Lng: -74.0445, // Longitude
Lat: 40.6892, // Latitude
},
}
db.Create(&location)
// Spatial query - find locations within 1km
var nearby []Location
db.Where("ST_DWithin(point, ST_Point(?, ?), ?)",
-74.0445, 40.6892, 0.009).Find(&nearby)
}Represents a single location with longitude and latitude coordinates.
type Location struct {
ID uint `gorm:"primaryKey"`
Name string
Point gogis.Point `gorm:"type:geometry(Point,4326)"`
}
location := Location{
Name: "Central Park",
Point: gogis.Point{
Lng: -73.9665, // Longitude (X)
Lat: 40.7812, // Latitude (Y)
},
}Represents paths, routes, or any sequence of connected points.
type Route struct {
ID uint `gorm:"primaryKey"`
Name string
Path gogis.LineString `gorm:"type:geometry(LineString,4326)"`
}
route := Route{
Name: "Broadway Walk",
Path: gogis.LineString{
Points: []gogis.Point{
{Lng: -73.9857, Lat: 40.7580}, // Times Square
{Lng: -73.9857, Lat: 40.7614}, // North on Broadway
{Lng: -73.9855, Lat: 40.7682}, // Further north
},
},
}Represents areas with outer boundaries and optional holes.
type Region struct {
ID uint `gorm:"primaryKey"`
Name string
Area gogis.Polygon `gorm:"type:geometry(Polygon,4326)"`
}
region := Region{
Name: "Central Park",
Area: gogis.Polygon{
Rings: [][]gogis.Point{
{ // Outer boundary
{Lng: -73.9812, Lat: 40.7644},
{Lng: -73.9734, Lat: 40.7644},
{Lng: -73.9734, Lat: 40.7947},
{Lng: -73.9812, Lat: 40.7947},
{Lng: -73.9812, Lat: 40.7644}, // Close the ring
},
// Optional: holes can be added as additional rings
},
},
}Represents collections of heterogeneous geometries.
type Place struct {
ID uint `gorm:"primaryKey"`
Name string
Geometries gogis.GeometryCollection `gorm:"type:geometry(GeometryCollection,4326)"`
}
place := Place{
Name: "Campus",
Geometries: gogis.GeometryCollection{
Geometries: []gogis.Geometry{
&gogis.Point{Lng: -73.9550, Lat: 40.8050}, // Building
&gogis.LineString{Points: walkwayPoints}, // Walkway
&gogis.Polygon{Rings: campusAreaRings}, // Campus area
},
},
}// Find locations within 1km of a point
var locations []Location
db.Where("ST_DWithin(point, ST_Point(?, ?), ?)",
lng, lat, 0.009).Find(&locations)
// Find nearest 10 locations
db.Order("ST_Distance(point, ST_Point(?, ?))").
Limit(10).Find(&locations, lng, lat)// Find points within a polygon
var pointsInside []Location
db.Where("ST_Contains(?, point)", polygon.String()).Find(&pointsInside)
// Find polygons containing a point
var regions []Region
db.Where("ST_Contains(area, ST_Point(?, ?))", lng, lat).Find(®ions)// Find routes that intersect with an area
var routes []Route
db.Where("ST_Intersects(path, ?)", polygon.String()).Find(&routes)
// Find overlapping regions
var overlapping []Region
db.Where("ST_Overlaps(area, ?)", otherPolygon.String()).Find(&overlapping)// Calculate polygon areas in square meters
db.Select("*, ST_Area(ST_Transform(area, 3857)) as area_meters").Find(®ions)
// Calculate route lengths in meters
db.Select("*, ST_Length(ST_Transform(path, 3857)) as length_meters").Find(&routes)Create spatial indexes for optimal query performance:
-- For points
CREATE INDEX idx_locations_point ON locations USING GIST (point);
-- For linestrings
CREATE INDEX idx_routes_path ON routes USING GIST (path);
-- For polygons
CREATE INDEX idx_regions_area ON regions USING GIST (area);
-- For geometry collections
CREATE INDEX idx_places_geometries ON places USING GIST (geometries);- Use ST_DWithin instead of ST_Distance with WHERE clauses
- Create compound indexes for frequently filtered queries
- Use ST_Transform for accurate distance/area calculations
- Consider partial indexes for large datasets
See INDEXING.md for detailed performance optimization guide.
Comprehensive examples are available in the examples/ directory:
- basic_usage/ - Point operations and spatial queries
- linestring_example/ - Routes and path analysis
- polygon_example/ - Area operations and containment
- geometry_collection_example/ - Complex geometries
Run examples:
cd examples/basic_usage && go run main.go
cd examples/linestring_example && go run main.go
cd examples/polygon_example && go run main.go
cd examples/geometry_collection_example && go run main.gogo test -v# Set up test database
createdb gogis_test
psql gogis_test -c "CREATE EXTENSION postgis;"
# Run integration tests
go test -tags=integration -vgo test -bench=. -benchmemFull API documentation is available at pkg.go.dev.
If migrating from other PostGIS Go libraries:
- Update imports: Change to
github.com/restayway/gogis - Update struct tags: Use
gorm:"type:geometry(Type,4326)" - Update coordinate order: GoGIS uses
{Lng, Lat}(longitude, latitude) - Update method calls: Check method names in documentation
See CHANGELOG.md for detailed migration information between versions.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Write tests for your changes
- Ensure all tests pass
- Submit a pull request
- 3D Geometry Support - PointZ, LineStringZ, PolygonZ
- Additional Geometry Types - MultiPoint, MultiLineString, MultiPolygon
- Custom SRID Support - Beyond SRID 4326
- Spatial Functions - Built-in Go implementations of common operations
- GeoJSON Integration - Direct GeoJSON marshaling/unmarshaling
- Performance Optimizations - Further query performance improvements
This project is licensed under the MIT License - see the LICENSE file for details.
- PostGIS Team - For the excellent spatial database extension
- GORM Team - For the fantastic ORM library
- Go Community - For the great language and ecosystem
- 📖 Documentation: pkg.go.dev
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: For security issues
GoGIS - Bringing PostGIS spatial capabilities to the Go ecosystem with GORM integration. Build location-aware applications with confidence! 🌍