geokit/geojson

GeoJSON (RFC 7946) encode / decode.

Maps geokit’s Geometry ADT to and from the JSON shapes defined in RFC 7946:

Point / LineString / Polygon / MultiPolygon round-trip through this module.
MultiPoint, MultiLineString, and GeometryCollection are valid GeoJSON types but are not currently representable in Geometry; decoding returns UnsupportedType.

Coordinate order in GeoJSON is [longitude, latitude], opposite of the lat: ..., lng: ... constructors elsewhere in geokit. The encoder and decoder handle the swap so callers never see the reversed order. Altitude (a third coordinate) is accepted on decode but discarded.

Properties on Feature and FeatureCollection are user-typed: pass a Json builder when encoding and a decode.Decoder when decoding. Use gleam/dynamic/decode.dynamic and gleam/json.null() if you don’t care about properties.

Types

Feature

</>

A GeoJSON Feature. Properties are user-typed: the type parameter properties is whatever your application chooses (often a record type, sometimes a dict.Dict(String, dynamic.Dynamic) for fully dynamic payloads).

pub type Feature(properties) {
  Feature(
    geometry: geometry.Geometry,
    properties: properties,
    id: option.Option(FeatureId),
  )
}

Constructors

Feature(
  geometry: geometry.Geometry,
  properties: properties,
  id: option.Option(FeatureId),
)

FeatureId

</>

A GeoJSON id value. RFC 7946 §3.2 allows either a JSON string or a JSON number; this type captures both losslessly.

pub type FeatureId {
  StringId(value: String)
  IntId(value: Int)
}

Constructors

```
StringId(value: String)
```
```
IntId(value: Int)
```

GeoJsonError

</>

Errors returned by the decoders.

pub type GeoJsonError {
  InvalidJson(reason: String)
  InvalidStructure(reason: String)
  UnknownType(type_: String)
  UnsupportedType(type_: String)
  InvalidPosition(coords: List(Float))
  InvalidLatLng(error: latlng.LatLngError)
}

Constructors

```
InvalidJson(reason: String)
```
The input was not valid JSON.
```
InvalidStructure(reason: String)
```
The input was valid JSON but the structure did not match the expected GeoJSON shape (missing field, wrong field type, …).
```
UnknownType(type_: String)
```
The type field carried a string that is not a known GeoJSON geometry or container type.
```
UnsupportedType(type_: String)
```
The type is a valid GeoJSON type but cannot be represented in geokit’s Geometry ADT (MultiPoint, MultiLineString, GeometryCollection).
```
InvalidPosition(coords: List(Float))
```
A coordinate array did not have the expected shape — fewer than two elements, or non-numeric entries.
```
InvalidLatLng(error: latlng.LatLngError)
```
A coordinate pair was structurally valid but the values fell outside the documented domain of latlng.new.

Values

decode_feature

</>

pub fn decode_feature(
  input input: String,
  properties properties: decode.Decoder(p),
) -> Result(Feature(p), GeoJsonError)

Decode a GeoJSON Feature. Pass a decoder for your properties type. To accept any shape, pass decode.dynamic.

decode_feature_collection

</>

pub fn decode_feature_collection(
  input input: String,
  properties properties: decode.Decoder(p),
) -> Result(List(Feature(p)), GeoJsonError)

Decode a GeoJSON FeatureCollection into a list of features.

decode_geometry

</>

pub fn decode_geometry(
  input input: String,
) -> Result(geometry.Geometry, GeoJsonError)

Decode a GeoJSON geometry string back to a Geometry.

encode_feature

</>

pub fn encode_feature(
  feature feature: Feature(p),
  properties to_json: fn(p) -> json.Json,
) -> String

Encode a Feature as a GeoJSON string. Pass a function that turns your properties type into a Json value.

encode_feature_collection

</>

pub fn encode_feature_collection(
  features features: List(Feature(p)),
  properties to_json: fn(p) -> json.Json,
) -> String

Encode a list of features as a GeoJSON FeatureCollection.

encode_geometry

</>

pub fn encode_geometry(
  geometry geometry: geometry.Geometry,
) -> String

Encode a Geometry as a GeoJSON string. The result is a compact JSON document with no whitespace.

import geokit/geojson
import geokit/geometry
import geokit/latlng

let assert Ok(p) = latlng.new(lat: 35.0, lng: 139.0)
geojson.encode_geometry(geometry: geometry.Point(p))
// == "{\"type\":\"Point\",\"coordinates\":[139.0,35.0]}"