gegography

README

Gegography

Gegography is a library for reading, manipulating and converting geographical formats, written i pure Go. Currently, support is limited to GeoJSON, WKT (Well-Known-Text) and Shapefiles (read only). I plan on implementing WKB (Well-Known-Binary).

I do not plan on supporting writing Shapefiles. Shapefile must die!

Gegography supports the following geographical types:

• Point
• LineString
• Polygon
• MultiPoint
• MultiLineString
• MultiPolygon

Currently, only XY geometries are supported.

What is it for?

I wrote Gegography primarily as a utility for processing geographical data uploaded to websites with Go backends. For example, I manage several websites with interactive mapping capabilities, and a common request is for users to be able to upload Shapefiles or GeoJSON-documents and have them automatically displayed on the map, or saved in the underlying database for viewing on demand.

With gegography you can read a Shapefile or a GeoJSON-document and easily export all features to WKT-strings for storage as geometries inside a database engine such as PostgreSQL or SQL Server.

How do I use it?

A typical use-case would look something like this (convert a shapefile to geojson)

package main

import (
	"os"
	"github.com/Froglich/gegography"
	"io/ioutil"
)

func main() {
	infile := os.Args[1]
	fc, err := gegography.ReadShapefile(infile)

	if err != nil {
		panic(err)
	}

	gj, err := fc.ToPrettyGeoJSON()

	if err != nil {
		panic(err)
	}

	err = ioutil.WriteFile(infile[:len(infile)-4] + ".geojson", gj, 0755)

	if err != nil {
		panic(err)
	}
}

Installing

Install with go get github.com/Froglich/gegography .

Documentation

Index

• type CRS
• type CRSProperties
• type Feature
  • func LoadGeoJSONFeature(input []byte) (Feature, error)
  • func ParseWKT(wkt string) (Feature, error)
  • func (f *Feature) ToGeoJSON() ([]byte, error)
  • func (f *Feature) ToWKT() (string, error)
• type FeatureCollection
  • func LoadGeoJSON(input []byte) (FeatureCollection, error)
  • func NewFeatureCollection() FeatureCollection
  • func ReadShapefile(shapeFile string) (FeatureCollection, error)
  • func (fc *FeatureCollection) AddFeature(f Feature)
  • func (fc *FeatureCollection) ToGeoJSON() ([]byte, error)
  • func (fc *FeatureCollection) ToGeoJSONFeatureArray() ([]byte, error)
  • func (fc *FeatureCollection) ToPrettyGeoJSON() ([]byte, error)
  • func (fc *FeatureCollection) ToWKT() (string, error)
• type GeoFormatError
  • func (g GeoFormatError) Error() string
• type GeoTypeError
  • func (g GeoTypeError) Error() string
• type LineString
• type MultiPoint
• type MultiPolygon
• type Point
• type Polygon

Types

type CRS

type CRS struct {
	Type       string        `json:"type"`
	Properties CRSProperties `json:"properties"`
}

CRS describes a coordinate reference system according to the GeoJSON format specification

type CRSProperties

type CRSProperties struct {
	Name string `json:"name,omitempty"`
	Href string `json:"href,omitempty"`
	Type string `json:"type,omitempty"`
}

CRSProperties are coordinate reference system properties according to the GeoJSON format specification

type Feature

type Feature struct {
	Type        string
	Properties  map[string]interface{}
	Coordinates interface{}
}

Feature represents a geographical feature

func LoadGeoJSONFeature

func LoadGeoJSONFeature(input []byte) (Feature, error)

LoadGeoJSONFeature parses an array of bytes conforming to a GeoJSON feature to a Feature

func ParseWKT

func ParseWKT(wkt string) (Feature, error)

ParseWKT parses a WKT string and returns a feature

func (*Feature) ToGeoJSON

func (f *Feature) ToGeoJSON() ([]byte, error)

ToGeoJSON exports a Feature to a byte array containing JSON conforming to the GeoJSON format

func (*Feature) ToWKT

func (f *Feature) ToWKT() (string, error)

ToWKT writes a WKT string representing a Feature

type FeatureCollection

type FeatureCollection struct {
	Name                      string
	CoordinateReferenceSystem *CRS
	Features                  []Feature
}

FeatureCollection represents a collection of geographical features and accompanying information

func LoadGeoJSON

func LoadGeoJSON(input []byte) (FeatureCollection, error)

LoadGeoJSON parses an array of bytes conforming to the GeoJSON format to a FeatureCollection

func NewFeatureCollection

func NewFeatureCollection() FeatureCollection

NewFeatureCollection returns a new blank FeatureCollection with an instantiated feature array

func ReadShapefile

func ReadShapefile(shapeFile string) (FeatureCollection, error)

ReadShapefile reads a shapefile (and accompanying dBASE-table, if any) into a FeatureCollection

func (*FeatureCollection) AddFeature

func (fc *FeatureCollection) AddFeature(f Feature)

AddFeature adds a feature to a FeatureCollection

func (*FeatureCollection) ToGeoJSON

func (fc *FeatureCollection) ToGeoJSON() ([]byte, error)

ToGeoJSON exports a FeatureCollection to a byte array containing JSON conforming to the GeoJSON format

func (*FeatureCollection) ToGeoJSONFeatureArray

func (fc *FeatureCollection) ToGeoJSONFeatureArray() ([]byte, error)

ToGeoJSONFeatureArray exports a FeatureCollection to a byte array conforming to the GeoJSON format but discards everything except the feature array

func (*FeatureCollection) ToPrettyGeoJSON

func (fc *FeatureCollection) ToPrettyGeoJSON() ([]byte, error)

ToPrettyGeoJSON exports a FeatureCollection to a byte array containing indented JSON conforming to the GeoJSON format

func (*FeatureCollection) ToWKT

func (fc *FeatureCollection) ToWKT() (string, error)

ToWKT writes a WKT string representing a FeatureCollection

type GeoFormatError

type GeoFormatError struct {
	Msg string
}

GeoFormatError describes an error involving badly formatted geographical information

func (GeoFormatError) Error

func (g GeoFormatError) Error() string

type GeoTypeError

type GeoTypeError struct {
	Type string
}

GeoTypeError describes an error involving an unsupported geographical type

func (GeoTypeError) Error

func (g GeoTypeError) Error() string

type LineString

type LineString []Point

LineString describes a collection of points which together form a line

type MultiPoint

type MultiPoint []Point

MultiPoint describes a collection of points

type MultiPolygon

type MultiPolygon []Polygon

MultiPolygon describes a collection of Polygons

type Point

type Point struct {
	X float64
	Y float64
}

Point describes a set of coordinates

type Polygon

type Polygon []MultiPoint

Polygon describes a collection of point collections which together form a polygon