stac 0.17.0

Rust library for the SpatioTemporal Asset Catalog (STAC) specification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! Rust implementation of the [STAC API](https://github.com/radiantearth/stac-api-spec) specification.
//!
//! This module **is**:
//!
//! - Data structures
//!
//! This module **is not**:
//!
//! - A server implementation
//!
//! For a STAC API server written in Rust based on this crate, see our
//! [stac-server](https://github.com/stac-utils/rustac/tree/main/stac-server).
//!
//! # Data structures
//!
//! Each API endpoint has its own data structure. In some cases, these are
//! light wrappers around [stac] data structures. In other cases, they can be
//! different -- e.g. the `/search` endpoint may not return [Items](stac::Item)
//! if the [fields](https://github.com/stac-api-extensions/fields) extension is
//! used, so the return type is a crate-specific [Item] struct.
//!
//! For example, here's the root structure (a.k.a the landing page):
//!
//! ```
//! use stac::Catalog;
//! use stac::api::{Root, Conformance, CORE_URI};
//! let root = Root {
//!     catalog: Catalog::new("an-id", "a description"),
//!     conformance: Conformance {
//!         conforms_to: vec![CORE_URI.to_string()]
//!     },
//! };
//! ```
//!
//! # Client trait family
//!
//! The API client traits are split by access pattern:
//!
//! - [`ItemsClient`]: fetch one page of items
//! - [`StreamItemsClient`] (`async` feature): stream items across all pages
//! - [`CollectionsClient`]: fetch all collections
//! - [`PagedCollectionsClient`]: fetch one cursor-paginated collections page
//! - [`StreamCollectionsClient`] (`async` feature): stream collections
//! - [`ArrowItemsClient`] (`geoarrow` feature): return Arrow record batches
//! - [`TransactionClient`]: write items and collections
//!
//! For `Stream`-based traits, `Stream` is the async equivalent of `Iterator`.
//! Prefer streaming paths for large result sets.
//!
//! ## Adapters
//!
//! When the `async` feature is enabled:
//!
//! - [`PagedItemsStream`] adapts any [`ItemsClient`] into [`StreamItemsClient`]
//! - [`stream_pages`] drives token/skip item pagination
//! - [`stream_pages_collections`] drives cursor-based collection pagination
//!
//! The `geoarrow` feature additionally provides Arrow adapters and blanket impls
//! for types implementing [`ArrowItemsClient`].
//!
//! ```text
//! ItemsClient ---------- PagedItemsStream ----------> StreamItemsClient
//!        ^                                                 ^
//!        |----- (geoarrow blanket, when supported) -------|
//!
//! CollectionsClient ---- (blanket) ----------------> StreamCollectionsClient
//! PagedCollectionsClient -- stream_pages_collections --> StreamCollectionsClient
//! ```

#![warn(missing_docs, unused_qualifications)]

mod adapters;
mod client;
mod collections;
mod conformance;
mod fields;
mod filter;
mod item_collection;
mod items;
mod root;
mod search;
mod sort;
mod url_builder;

#[cfg(feature = "geoarrow")]
pub use adapters::RecordBatchReaderAdapter;
#[cfg(feature = "async")]
pub use adapters::{PagedItemsStream, stream_pages, stream_pages_collections};
#[cfg(feature = "geoarrow")]
pub use client::ArrowItemsClient;
#[cfg(feature = "async")]
pub use client::{
    CollectionsClient, ItemsClient, PagedCollectionsClient, StreamCollectionsClient,
    StreamItemsClient, TransactionClient,
};
#[cfg(not(feature = "async"))]
pub use client::{CollectionsClient, ItemsClient, PagedCollectionsClient, TransactionClient};
pub use collections::Collections;
pub use conformance::{
    COLLECTIONS_URI, CORE_URI, Conformance, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
    ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
};
pub use fields::Fields;
pub use filter::Filter;
pub use item_collection::{Context, ItemCollection};
pub use items::{GetItems, Items};
pub use root::Root;
pub use search::{GetSearch, Search};
pub use sort::{Direction, Sortby};
pub use url_builder::UrlBuilder;

/// Crate-specific result type.
pub type Result<T> = std::result::Result<T, crate::Error>;

/// A STAC API Item type definition.
///
/// By default, STAC API endpoints that return [stac::Item] objects return every
/// field of those Items. However, Item objects can have hundreds of fields, or
/// large geometries, and even smaller Item objects can add up when large
/// numbers of them are in results. Frequently, not all fields in an Item are
/// used, so this specification provides a mechanism for clients to request that
/// servers to explicitly include or exclude certain fields.
pub type Item = serde_json::Map<String, serde_json::Value>;

/// Return this crate's version.
///
/// # Examples
///
/// ```
/// println!("{}", stac::api::version());
/// ```
pub fn version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

#[cfg(test)]
use geojson as _;