Search

stacrs.search builtin

search(href: str, *, intersects: Optional[str | dict[str, Any]] = None, ids: Optional[str | list[str]] = None, collections: Optional[str | list[str]] = None, max_items: Optional[int] = None, limit: Optional[int] = None, bbox: Optional[list[float]] = None, datetime: Optional[str] = None, include: Optional[str | list[str]] = None, exclude: Optional[str | list[str]] = None, sortby: Optional[str | list[str]] = None, filter: Optional[str | dict[str, Any]] = None, query: Optional[dict[str, Any]] = None, use_duckdb: Optional[bool] = None) -> list[dict[str, Any]]

Searches a STAC API server.

Parameters:

Name	Type	Description	Default
href	str	The STAC API to search.	required
intersects	str | dict[str, Any] | GeoInterface | None	Searches items by performing intersection between their geometry and provided GeoJSON geometry.	None
ids	list[str] | None	Array of Item ids to return.	None
collections	list[str] | None	Array of one or more Collection IDs that each matching Item must be in.	None
max_items	int | None	The maximum number of items to iterate through.	None
limit	int | None	The page size returned from the server. Use max_items to actually limit the number of items returned from this function.	None
bbox	list[float] | None	Requested bounding box.	None
datetime	str | None	Single date+time, or a range (/ separator), formatted to RFC 3339, section 5.6. Use double dots .. for open date ranges.	None
include	list[str]] | None	fields to include in the response (see the extension docs) for more on the semantics).	None
exclude	list[str]] | None	fields to exclude from the response (see the extension docs) for more on the semantics).	None
sortby	list[str] | None	Fields by which to sort results (use -field to sort descending).	None
filter	str | dict[str, Any] | none	CQL2 filter expression. Strings will be interpreted as cql2-text, dictionaries as cql2-json.	None
query	dict[str, Any] | None	Additional filtering based on properties. It is recommended to use filter instead, if possible.	None
use_duckdb	bool | None	Query with DuckDB. If None and the href has a 'parquet' or 'geoparquet' extension, will be set to True. Defaults to None.	None

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list of the returned STAC items.

Examples:

>>> items = stacrs.search(
...     "https://landsatlook.usgs.gov/stac-server",
...     collections=["landsat-c2l2-sr"],
...     intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
...     sortby="-properties.datetime",
...     max_items=1,
... )

stacrs.search_to builtin

search_to(outfile: str, href: str, *, intersects: Optional[str | dict[str, Any]] = None, ids: Optional[str | list[str]] = None, collections: Optional[str | list[str]] = None, max_items: Optional[int] = None, limit: Optional[int] = None, bbox: Optional[list[float]] = None, datetime: Optional[str] = None, include: Optional[str | list[str]] = None, exclude: Optional[str | list[str]] = None, sortby: Optional[str | list[str]] = None, filter: Optional[str | dict[str, Any]] = None, query: Optional[dict[str, Any]] = None, format: Optional[str] = None, options: Optional[list[Tuple[str, str]]] = None, use_duckdb: Optional[bool] = None) -> int

Searches a STAC API server and saves the result to an output file.

Parameters:

Name	Type	Description	Default
outfile	str	The output href. This can be a local file path, or any url scheme supported by [stac::object_store::write].	required
href	str	The STAC API to search.	required
intersects	str | dict[str, Any] | GeoInterface | None	Searches items by performing intersection between their geometry and provided GeoJSON geometry.	None
ids	list[str] | None	Array of Item ids to return.	None
collections	list[str] | None	Array of one or more Collection IDs that each matching Item must be in.	None
max_items	int | None	The maximum number of items to iterate through.	None
limit	int | None	The page size returned from the server. Use max_items to actually limit the number of items returned from this function.	None
bbox	list[float] | None	Requested bounding box.	None
datetime	str | None	Single date+time, or a range ('/' separator), formatted to RFC 3339, section 5.6. Use double dots .. for open date ranges.	None
include	list[str]] | None	fields to include in the response (see the extension docs) for more on the semantics).	None
exclude	list[str]] | None	fields to exclude from the response (see the extension docs) for more on the semantics).	None
sortby	list[str] | None	Fields by which to sort results (use -field to sort descending).	None
filter	str | dict[str, Any] | none	CQL2 filter expression. Strings will be interpreted as cql2-text, dictionaries as cql2-json.	None
query	dict[str, Any] | None	Additional filtering based on properties. It is recommended to use filter instead, if possible.	None
format	str | None	The output format. If none, will be inferred from the outfile extension, and if that fails will fall back to compact JSON.	None
options	list[tuple[str, str]] | None	Configuration values to pass to the object store backend.	None
use_duckdb	bool | None	Query with DuckDB. If None and the href has a 'parquet' or 'geoparquet' extension, will be set to True. Defaults to None.	None

Returns:

Type	Description
int	list[dict[str, Any]]: A list of the returned STAC items.

Examples:

>>> items = stacrs.search_to("out.parquet",
...     "https://landsatlook.usgs.gov/stac-server",
...     collections=["landsat-c2l2-sr"],
...     intersects={"type": "Point", "coordinates": [-105.119, 40.173]},
...     sortby="-properties.datetime",
...     max_items=1,
... )