geojson

The library distinguishes between GeometryValue and Geometry:

1. GeometryValue: An enum representing the core GeoJSON geometry type and its specific coordinate structure (e.g., Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection). It is the payload of a geometry.
2. Geometry: A wrapper struct that follows the GeoJSON specification for a Geometry Object. It contains:
   • value: The GeometryValue (the type and coordinates).
   • bbox: An optional bounding box (Option<Bbox>).
   • foreign_members: An optional map of extra fields (Option<JsonObject>) allowed by the GeoJSON spec.

When creating geometries, it is recommended to use the Geometry::new_* constructors which wrap a GeometryValue into a Geometry struct.

The crate is structured around the GeoJSON spec (RFC 7946). A GeoJSON document is represented by the GeoJson enum, which can contain one of three top-level objects:

1. Geometry: Represents points, lines, and surfaces in coordinate space.
2. Feature: Contains a Geometry and associated data (properties).
3. FeatureCollection: A list of Features.

Because Feature and FeatureCollection are more flexible, bare Geometry documents are less common. Conversions from Geometry or GeometryValue to Feature objects are provided via the From trait.

use geojson::{GeoJson, Feature, FeatureCollection, Geometry};

GeoJSON allows for 'foreign members'—extra JSON fields not defined in the spec. This crate captures them in the foreign_members field on Geometry, Feature, and FeatureCollection structs.

Limitation: Foreign member keys must not collide with reserved GeoJSON fields (coordinates, geometries, id, geometry, properties, features), or they will be consumed by the reserved field parser instead.

use geojson::{GeoJson, Feature};

let geojson_str = r#"{ "type": "Feature", "geometry": {"type": "Point", "coordinates": [0.0, 0.0]}, "properties": null, "title": "my point" }"#;

let feature = geojson_str.parse::<GeoJson>().unwrap();
if let GeoJson::Feature(feature) = feature {
    let foreign_members = feature.foreign_members.unwrap();
    assert_eq!(foreign_members["title"], "my point");
}

To use this crate in your Rust project, add it to your Cargo.toml using cargo add:

cargo add geojson

You can deserialize GeoJSON directly into your own custom structs using serde. To do this correctly:

1. Your struct must have a geometry field.
2. If the field is a geo-types geometry, use the geojson::ser::serialize_geometry and geojson::de::deserialize_geometry helpers.
3. Otherwise, the field must be a crate::Geometry.

Note: Using this method means any fields other than geometry and properties (like foreign_members) will be lost during deserialization.

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "geojson::ser::serialize_geometry", deserialize_with = "geojson::de::deserialize_geometry")]
    geometry: geo_types::Point<f64>,
    name: String,
    count: u64,
}

You can parse a GeoJSON string into a GeoJson enum using the .parse::<GeoJson>() method. This allows you to convert raw string data into structured Rust types representing GeoJSON features, geometries, or collections.

use geojson::GeoJson;

let geojson_str = r"#
{
    "type": "Feature",
    "properties": {
        "name": "Firestone Grill"
    },
    "geometry": {
        "type": "Point",
        "coordinates": [-120.66029,35.2812]
    }
}
"#;

let geojson = geojson_str.parse::<GeoJson>().unwrap();

To write GeoJSON, construct the appropriate types such as Geometry, JsonObject, and Feature, then wrap them in the GeoJson enum. You can then use the .to_string() method to serialize the object into a GeoJSON-formatted string.

use geojson::{Feature, GeoJson, Geometry, JsonObject, JsonValue};

let geometry = Geometry::new_point([-120.66029, 35.2812]);

let mut properties = JsonObject::new();
properties.insert(
    String::from("name"),
    JsonValue::from("Firestone Grill"),
);

let geojson = GeoJson::Feature(Feature {
    bbox: None,
    geometry: Some(geometry),
    id: None,
    properties: Some(properties),
    foreign_members: None,
});

let geojson_string = geojson.to_string();

You can deserialize a GeoJSON string into a Feature (or other GeoJSON types) by using the str::parse method. This is powered by serde integration.

use geojson::{Feature, GeoJson, Geometry, GeometryValue};
use std::convert::TryFrom;

let geojson_str = r"#
{
  "type": "Feature",
  "properties": { "food": "donuts" },
  "geometry": {
    "type": "Point",
    "coordinates": [ -118.2836, 34.0956 ]
  }
}
"#;

let feature: Feature = geojson_str.parse().unwrap();

// read property data
assert_eq!("donuts", feature.property("food").unwrap());

// read geometry data
let geometry: Geometry = feature.geometry.unwrap();
if let GeometryValue::Point { coordinates } = geometry.value {
    assert_eq!(coordinates.as_slice(), &[-118.2836, 34.0956]);
}

You can serialize GeoJSON objects to a string by calling .to_string(). For Feature objects, you can define properties using JsonObject and JsonValue (which are wrappers around serde_json types).

use geojson::{Feature, GeoJson, Geometry, JsonObject, JsonValue};

fn get_properties() -> JsonObject {
    let mut properties = JsonObject::new();
    properties.insert(
        String::from("name"),
        JsonValue::from("Firestone Grill"),
    );
    properties
}

fn main() {
    let geometry = Geometry::new_point([-120.66029, 35.2812]);

    let feature = Feature {
        bbox: None,
        geometry: Some(geometry),
        id: None,
        properties: Some(get_properties()),
        foreign_members: None,
    };

    let geojson_string = feature.to_string();
}