Crate stac

Rust implementation of the SpatioTemporal Asset Catalog (STAC) specification.

The SpatioTemporal Asset Catalog (STAC) specification provides a common language to describe a range of geospatial information, so it can more easily be indexed and discovered. A ‘spatiotemporal asset’ is any file that represents information about the earth captured in a certain space and time.

This is a Rust implementation of the specification, with associated utilities. Similar projects in other languages include:

• Python: PySTAC
• Go: go-stac
• .NET: DotNetStac
• PHP: resto

Data structures

STAC has three data structures:

• Item is a GeoJSON Feature augmented with foreign members
• Catalog represents a logical group of other Catalogs, Collections, and Items
• Collection shares all fields with the Catalog (with different allowed values for type and stac_extensions) and adds fields to describe the whole dataset and the included set of Items

All three are provided as serde (de)serializable structures with public attributes. Each structure provides a new method that fills most of the object’s attributes with sensible defaults:

use stac::{Item, Catalog, Collection};
let item = Item::new("id");
let catalog = Catalog::new("id", "description");
let collection = Catalog::new("id", "description");

All attributes of STAC objects are accessible as public members:

use stac::{Item, Link};
let mut item = Item::new("id");
assert_eq!(item.id, "id");
assert!(item.geometry.is_none());
assert!(item.links.is_empty());
item.links.push(Link::new("an/href", "a-rel-type"));

Reading

Synchronous reads from the filesystem are supported via read:

let value: stac::Item = stac::read("data/simple-item.json").unwrap();

If the reqwest feature is enabled, synchronous reads from urls are also supported:

#[cfg(feature = "reqwest")]
{
    let url = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json";
    let item: stac::Item = stac::read(url).unwrap();
}

If reqwest is not enabled, reading from a url will return an error:

#[cfg(not(feature = "reqwest"))]
{
    let url = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json";
    let error = stac::read::<stac::Item>(url).unwrap_err();
}

Hrefs

When objects are read from the filesystem or from a remote location, they store the href from which they were read. The href is accessible via the Href trait:

use stac::{Href, Item};
let item: Item = stac::read("data/simple-item.json").unwrap();
assert!(item.href().as_deref().unwrap().ends_with("data/simple-item.json"));

Extensions

STAC is intentionally designed with a minimal core and flexible extension mechanism to support a broad set of use cases. See the extensions module for more information.

Re-exports

• pub use extensions::Extension;
• pub use extensions::Extensions;
• pub use item::Item;
• pub use item::Properties;
• pub use item::ITEM_TYPE;
• pub use link::Link;
• pub use link::Links;

Modules

• datetime
  Datetime utilities.
• extensions
  Extensions describe how STAC can use extensions that extend the functionality of the core spec or add fields for specific domains.
• gdalgdal
  Functions that leverage GDAL.
• geogeo
  Geometry utilities, enabled by the geo feature.
• item
  STAC Items.
• link
  Links.
• media_type
  Media Types are a key element that enables STAC to be a rich source of information for clients.

Structs

• Asset
  An Asset is an object that contains a URI to data associated with the Item that can be downloaded or streamed.
• Bounds
  Two-dimensional bounds.
• Catalog
  A STAC Catalog object represents a logical group of other Catalog, Collection, and Item objects.
• Collection
  The STAC Collection Specification defines a set of common fields to describe a group of Items that share properties and metadata.
• Extent
  The object describes the spatio-temporal extents of the Collection.
• ItemCollection
  A GeoJSON FeatureCollection of items.
• Provider
  This object provides information about a provider.
• SpatialExtent
  The object describes the spatial extents of the Collection.
• TemporalExtent
  The object describes the temporal extents of the Collection.

Enums

• Error
  Error enum for crate-specific errors.
• Value
  An enum that can hold any STAC object type.

Constants

• CATALOG_TYPE
  The type field for Catalogs.
• COLLECTION_TYPE
  The type field for Collections.
• ITEM_COLLECTION_TYPE
  The type field for ItemCollections.
• STAC_VERSION
  The default STAC version supported by this library.

Traits

• Assets
  Trait implemented by anything that has assets.
• Fields
  Trait for structures that have gettable and settable fields.
• Href
  Implemented by all three STAC objects, the Href trait allows getting and setting an object’s href.

Functions

• deserialize_type
  Utility function to deserialize the type field on an object.
• href_to_url
  Parses an href into a Url if the scheme is http or https.
• read
  Reads any STAC object from an href.
• read_json
  Reads any deserializable value from the JSON at an href.
• serialize_type
  Utility function to serialize the type field on an object.

Type Aliases

• Result
  Custom Result type for this crate.