Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fogfish/geojson
GeoJSON / RFC7946 codec for Golang
https://github.com/fogfish/geojson
codec decoding encoding geojson geojson-parser go golang
Last synced: 5 days ago
JSON representation
GeoJSON / RFC7946 codec for Golang
- Host: GitHub
- URL: https://github.com/fogfish/geojson
- Owner: fogfish
- License: mit
- Created: 2021-05-19T19:50:23.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-08-17T19:34:04.000Z (over 1 year ago)
- Last Synced: 2024-10-18T16:24:21.727Z (2 months ago)
- Topics: codec, decoding, encoding, geojson, geojson-parser, go, golang
- Language: Go
- Homepage:
- Size: 30.3 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
GeoJSON
GeoJSON codec for Go structs
---
The library implements a type safe codec for [GeoJSON](https://geojson.org).
## Inspiration
GeoJSON is a popular format for encoding a variety of geographic data structures. It defines a standard way to express points, curves, and surfaces in coordinate space together with an application specific metadata about it.
```json
{
"type": "Feature",
"id": "[wikipedia:Helsinki]",
"geometry": {
"type": "Point",
"coordinates": [24.9384, 60.1699]
},
"properties": {
"name": "Helsinki"
}
}
```
Unfortunately, efficient and type-safe implementation of GeoJSON codec can be challenging:
(i) Pure structs are verbose. The `properties` is an application specific and it's type is controlled outside of the codec library. Usage of duck type (`interface{}`) is a common trait used by other GeoJSON Golang libraries. As the results, developers are misses an ability to caught errors at compile time, any mistake becomes visible at run time as a panic. [interface{} says nothing.](https://youtu.be/PAAkCSZUG1c?t=7m40s).
(ii) Implementing GeoJSON types using generics is requires overly complex type definitions. It can lead to complex type hierarchies, especially in nested GeoJSON structures like FeatureCollection. It suffers from usability for consumers. Specifying types for properties at every level (e.g., Feature or FeatureCollection) adds boilerplate and increases the learning curve.
## Key features
The library allows developers to use Golang pure struct to define domain models using a type safe approach of encoding/decoding these models to GeoJSON and back. The library uses type tagging technique to annotate any structure as GeoJSON feature:
```go
type City struct {
geojson.Feature
Name string `json:"name,omitempty"`
}
```
## Getting started
The latest version of the library is available at `main` branch of this repository. All development, including new features and bug fixes, take place on the `main` branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.
The following code snippet demonstrates a typical usage scenario.
```go
import "github.com/fogfish/geojson"
//
// declare any domain type and annotate as a geojson.Feature
type City struct {
geojson.Feature
Name string `json:"name,omitempty"`
}
//
// Each GeoJSON type declares codes using helper functions.
func (x City) MarshalJSON() ([]byte, error) {
type tStruct City
return x.Feature.EncodeGeoJSON(tStruct(x))
}
func (x *City) UnmarshalJSON(b []byte) error {
type tStruct *City
return x.Feature.DecodeGeoJSON(b, tStruct(x))
}
//
// Create new instance of the type
city := City{
Feature: geojson.NewPoint(
"[wikipedia:Helsinki]",
geojson.Coord{24.9384, 60.1699},
),
Name: "Helsinki",
}
//
// Use type checks to validate the type of the Geometry
city.Feature.Geometry.Coords.(*geojson.Point)
```
### Feature Collection
The library supports `FeatureCollection` object via Golang generic.
```go
seq := geojson.Collection[City]{
Features: []City{city},
}
```
## How To Contribute
The library is [MIT](LICENSE) licensed and accepts contributions via GitHub pull requests:
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
The build and testing process requires [Go](https://golang.org) version 1.16 or later.
**build** and **test** library.
```bash
git clone https://github.com/fogfish/geojson
cd geojson
go test
```
### commit message
The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter [Contributing to a Project](http://git-scm.com/book/ch5-2.html) of Git book.
### bugs
If you experience any issues with the library, please let us know via [GitHub issues](https://github.com/fogfish/geojson/issue). We appreciate detailed and accurate reports that help us to identity and replicate the issue.
## License
[](LICENSE)