Struct Search 

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

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: Vec<String>

Array of Item ids to return.

collections: Vec<String>

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

Implementations

impl Search

pub fn new() -> Search

Creates a new, empty search.

Examples

use stac::api::Search;

let search = Search::new();

pub fn ids(self, ids: 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()]);

pub fn intersects(self, intersects: impl Into<Geometry>) -> Search

Sets the intersects of this search.

pub fn collections(self, collections: Vec<String>) -> Search

Sets the collections of this search.

pub fn bbox(self, bbox: impl Into<Bbox>) -> Search

Sets the bbox of this search.

pub fn datetime(self, datetime: impl ToString) -> Search

Sets the datetime of this search.

pub fn limit(self, limit: u64) -> Search

Sets the limit of this search.

pub fn sortby(self, sortby: Vec<Sortby>) -> Search

Sets the sortby of this search.

pub fn fields(self, fields: Fields) -> Search

Sets the fields of this search.

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;

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_point(vec![0.0, 0.0]));
search.valid().unwrap_err();

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());

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 = 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));

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 = vec!["item-id".to_string()];
assert!(search.id_matches(&item));
search.ids = vec!["another-id".to_string()];
assert!(!search.id_matches(&item));

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_point(vec![-105.1, 41.1]));
assert!(!search.intersects_matches(&item).unwrap());
item.set_geometry(Geometry::new_point(vec![-105.1, 41.1]));
assert!(search.intersects_matches(&item).unwrap());

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

Converts this search’s filter to cql2-json, if set.

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

Normalizes datetime parameters by expanding partial dates to full RFC 3339 datetime ranges.

This method validates and normalizes datetime parameters by expanding partial dates (year, year-month, year-month-day) to full RFC 3339 datetime ranges:

• For single dates:
  • Year only (e.g., “2023”) → 2023-01-01T00:00:00Z/2023-12-31T23:59:59Z
  • Year-Month (e.g., “2023-06”) → 2023-06-01T00:00:00Z/2023-06-30T23:59:59Z
  • ISO 8601 date (e.g., “2023-06-15”) → 2023-06-15T00:00:00Z/2023-06-15T23:59:59Z
• For date ranges:
  • Year to Year (e.g., “2017/2018”) → 2017-01-01T00:00:00Z/2018-12-31T23:59:59Z
  • Year-Month to Year-Month (e.g., “2017-06/2017-07”) → 2017-06-01T00:00:00Z/2017-07-31T23:59:59Z
  • Date to Date (e.g., “2017-06-10/2017-06-11”) → 2017-06-10T00:00:00Z/2017-06-11T23:59:59Z

Datetime values already in RFC 3339 format are preserved. Open-ended ranges using .. are supported.

Examples

use stac::api::Search;

// Partial dates are expanded to ranges
let search = Search {
    items: stac::api::Items {
        datetime: Some("2023".to_string()),
        ..Default::default()
    },
    ..Default::default()
};
let normalized = search.normalize_datetimes().unwrap();
assert_eq!(
    normalized.datetime.as_ref().unwrap(),
    "2023-01-01T00:00:00+00:00/2023-12-31T23:59:59+00:00"
);

// RFC 3339 datetimes are preserved as single values
let search = Search {
    items: stac::api::Items {
        datetime: Some("2023-06-01T00:00:00Z".to_string()),
        ..Default::default()
    },
    ..Default::default()
};
let normalized = search.normalize_datetimes().unwrap();
assert_eq!(
    normalized.datetime.as_ref().unwrap(),
    "2023-06-01T00:00:00+00:00"
);

Methods from Deref<Target = Items>

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());

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

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

If stac 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_point(vec![-105.1, 41.1]));
assert!(search.bbox_matches(&item).unwrap());

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());

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());

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());

Trait Implementations

impl Clone for Search

fn clone(&self) -> Search

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Search

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Search

fn default() -> Search

Returns the “default value” for a type.

impl Deref for Search

type Target = Items

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Search

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de> Deserialize<'de> for Search

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Fields for Search

fn fields(&self) -> &Map<String, Value>

Gets the fields value.

fn fields_mut(&mut self) -> &mut Map<String, Value>

Gets a mutable reference to the fields value.

fn field(&self, key: &str) -> Option<&Value>

Gets the value of a field.

fn set_field<S: Serialize>( &mut self, key: impl ToString, value: S, ) -> Result<Option<Value>>

Sets the value of a field.

fn fields_with_prefix<D: DeserializeOwned>(&self, prefix: &str) -> Result<D>

Gets values with a prefix.

fn set_fields_with_prefix<S: Serialize>( &mut self, prefix: &str, value: S, ) -> Result<()>

Sets values with a prefix.

fn remove_fields_with_prefix(&mut self, prefix: &str)

Removes values with a prefix.

impl From<Items> for Search

fn from(items: Items) -> Self

Converts to this type from the input type.

impl Serialize for Search

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<GetSearch> for Search

type Error = Error

The type returned in the event of a conversion error.

fn try_from(get_search: GetSearch) -> Result<Search>

Performs the conversion.

impl TryFrom<Search> for GetSearch

type Error = Error

The type returned in the event of a conversion error.

fn try_from(search: Search) -> Result<GetSearch>

Performs the conversion.