Struct stac_api::Search

source ·

pub struct Search {
    pub items: Items,
    pub intersects: Option<Geometry>,
    pub ids: Option<Vec<String>>,
    pub collections: Option<Vec<String>>,
}

Expand description

The core parameters for STAC search are defined by OAFeat, and STAC adds a few parameters for convenience.

Fields§

§items: Items

Many fields are shared with Items, so we re-use that structure.

§intersects: Option<Geometry>

Searches items by performing intersection between their geometry and provided GeoJSON geometry.

All GeoJSON geometry types must be supported.

§ids: Option<Vec<String>>

Array of Item ids to return.

§collections: Option<Vec<String>>

Array of one or more Collection IDs that each matching Item must be in.

Implementations§

source §

impl Search

source

pub fn new() -> Search

Creates a new, empty search.

§Examples

use stac_api::Search;

let search = Search::new();

source

pub fn ids(self, ids: impl Into<Option<Vec<String>>>) -> Search

Sets the ids field of this search.

§Examples

use stac_api::Search;
let search = Search::new().ids(vec!["an-id".to_string()]);

source

pub fn valid(self) -> Result<Search>

Returns an error if this search is invalid, e.g. if both bbox and intersects are specified.

Returns the search unchanged if it is valid.

§Examples

use stac_api::Search;
use geojson::{Geometry, Value};

let mut search = Search::default();
search.items.bbox =  Some(vec![-180.0, -90.0, 180.0, 80.0].try_into().unwrap());
search = search.valid().unwrap();
search.intersects = Some(Geometry::new(Value::Point(vec![0.0, 0.0])));
search.valid().unwrap_err();

source

pub fn matches(&self, item: &Item) -> Result<bool>

Returns true if this item matches this search.

§Examples

use stac::Item;
use stac_api::Search;

let item = Item::new("an-id");
assert!(Search::new().matches(&item).unwrap());
assert!(!Search::new().ids(vec!["not-the-id".to_string()]).matches(&item).unwrap());

source

pub fn collection_matches(&self, item: &Item) -> bool

Returns true if this item’s collection matches this search.

§Examples

use stac_api::Search;
use stac::Item;

let mut search = Search::new();
let mut item = Item::new("item-id");
assert!(search.collection_matches(&item));
search.collections = Some(vec!["collection-id".to_string()]);
assert!(!search.collection_matches(&item));
item.collection = Some("collection-id".to_string());
assert!(search.collection_matches(&item));
item.collection = Some("another-collection-id".to_string());
assert!(!search.collection_matches(&item));

source

pub fn id_matches(&self, item: &Item) -> bool

Returns true if this item’s id matches this search.

§Examples

use stac_api::Search;
use stac::Item;

let mut search = Search::new();
let mut item = Item::new("item-id");
assert!(search.id_matches(&item));
search.ids = Some(vec!["item-id".to_string()]);
assert!(search.id_matches(&item));
search.ids = Some(vec!["another-id".to_string()]);
assert!(!search.id_matches(&item));

source

pub fn intersects_matches(&self, item: &Item) -> Result<bool>

Returns true if this item’s geometry matches this search’s intersects.

§Examples

use stac_api::Search;
use stac::Item;
use geojson::{Geometry, Value};

let mut search = Search::new();
let mut item = Item::new("item-id");
assert!(search.intersects_matches(&item).unwrap());
search.intersects = Some(Geometry::new(Value::Point(vec![-105.1, 41.1])));
assert!(!search.intersects_matches(&item).unwrap());
item.set_geometry(Geometry::new(Value::Point(vec![-105.1, 41.1])));
assert!(search.intersects_matches(&item).unwrap());

Methods from Deref<Target = Items>§

source

pub fn matches(&self, item: &Item) -> Result<bool>

Returns true if this items structure matches the given item.

§Examples

use stac_api::Items;
use stac::Item;

assert!(Items::default().matches(&Item::new("an-id")).unwrap());

source

pub fn bbox_matches(&self, item: &Item) -> Result<bool>

Returns true if this item’s geometry matches this search’s bbox.

If stac-api is not built with the geo feature, this will return an error.

§Examples

use stac_api::Search;
use stac::Item;
use geojson::{Geometry, Value};

let mut search = Search::new();
let mut item = Item::new("item-id");
assert!(search.bbox_matches(&item).unwrap());
search.bbox = Some(vec![-110.0, 40.0, -100.0, 50.0].try_into().unwrap());
assert!(!search.bbox_matches(&item).unwrap());
item.set_geometry(Geometry::new(Value::Point(vec![-105.1, 41.1])));
assert!(search.bbox_matches(&item).unwrap());

source

pub fn datetime_matches(&self, item: &Item) -> Result<bool>

Returns true if this item’s datetime matches this items structure.

§Examples

use stac_api::Search;
use stac::Item;

let mut search = Search::new();
let mut item = Item::new("item-id");  // default datetime is now
assert!(search.datetime_matches(&item).unwrap());
search.datetime = Some("../2023-10-09T00:00:00Z".to_string());
assert!(!search.datetime_matches(&item).unwrap());
item.properties.datetime = Some("2023-10-08T00:00:00Z".parse().unwrap());
assert!(search.datetime_matches(&item).unwrap());

source

pub fn query_matches(&self, _: &Item) -> Result<bool>

Returns true if this item’s matches this search query.

Currently unsupported, always raises an error if query is set.

§Examples

use stac_api::Search;
use stac::Item;

let mut search = Search::new();
let mut item = Item::new("item-id");
assert!(search.query_matches(&item).unwrap());
search.query = Some(Default::default());
assert!(search.query_matches(&item).is_err());

source

pub fn filter_matches(&self, _: &Item) -> Result<bool>

Returns true if this item matches this search’s filter.

Currently unsupported, always raises an error if filter is set.

§Examples

use stac_api::Search;
use stac::Item;

let mut search = Search::new();
let mut item = Item::new("item-id");
assert!(search.filter_matches(&item).unwrap());
search.filter = Some(Default::default());
assert!(search.filter_matches(&item).is_err());