Search

rustac.search `async`

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

Searches a STAC API server or a stac-geoparquet file.

Parameters:

href (str) –

The STAC API to search.
intersects (str | dict[str, Any] | None, default: None ) –

Searches items by performing intersection between their geometry and provided GeoJSON geometry.
ids (str | list[str] | None, default: None ) –

Array of Item ids to return.
collections (str | list[str] | None, default: None ) –

Array of one or more Collection IDs that each matching Item must be in.
max_items (int | None, default: None ) –

The maximum number of items to iterate through.
limit (int | None, default: None ) –

The page size returned from the server. Use max_items to actually limit the number of items returned from this function.
bbox (list[float] | None, default: None ) –

Requested bounding box.
datetime (str | None, default: None ) –
Single date+time, or a range (/ separator), formatted to RFC 3339, section 5.6. Use double dots .. for open date ranges.

Partial dates are also supported and will be automatically expanded to full RFC 3339 datetime ranges:
- Year only (e.g., "2023") expands to 2023-01-01T00:00:00Z/2023-12-31T23:59:59Z
- Year-Month (e.g., "2023-06") expands to 2023-06-01T00:00:00Z/2023-06-30T23:59:59Z
- ISO 8601 date (e.g., "2023-06-15") expands to 2023-06-15T00:00:00Z/2023-06-15T23:59:59Z
- Ranges also support partial dates (e.g., "2017/2018", "2017-06/2017-07")
include (str | list[str] | None, default: None ) –

fields to include in the response (see the extension docs) for more on the semantics).
exclude (str | list[str] | None, default: None ) –

fields to exclude from the response (see the extension docs) for more on the semantics).
sortby (str | list[str | dict[str, str]] | None, default: None ) –

Fields by which to sort results (use -field to sort descending).
filter (str | dict[str, Any] | None, default: None ) –

CQL2 filter expression. Strings will be interpreted as cql2-text, dictionaries as cql2-json.
query (dict[str, Any] | None, default: None ) –

Additional filtering based on properties. It is recommended to use filter instead, if possible.
fields (str | list[str] | dict[str, Any] | None, default: None ) –

Fields to include in or exclude from the response, per the fields extension. Strings are interpreted as a comma-delimited list (e.g. +properties.datetime,-geometry); lists as the same +/- prefixed field names (e.g. ["properties.datetime", "-geometry"]); dictionaries as {"include": [...], "exclude": [...]}. Any include or exclude arguments override the corresponding values set here.
headers (dict[str, str] | None, default: None ) –

Additional headers to include in requests to the STAC API.
max_extra_load (float | None, default: None ) –

The maximum extra load that retries are allowed to add to the server, as a fraction of the request rate. See the reqwest docs.
max_retries_per_request (int | None, default: None ) –

The maximum number of retries for a single request.
retry_status_codes (list[int] | None, default: None ) –

The HTTP status codes that should trigger a retry (e.g. [408, 429, 500, 502, 503, 504]).
use_duckdb (bool | None, default: None ) –

Query with DuckDB. If None and the href has a 'parquet' or 'geoparquet' extension, will be set to True. Defaults to None.
kwargs (str, default: {} ) –

Additional parameters to pass in to the search.

Returns:

list[dict[str, Any]] –

STAC items

Examples:

>>> items = await rustac.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,
... )

rustac.search_to `async`

search_to(
    outfile: str,
    href: str,
    *,
    intersects: str | dict[str, Any] | None = None,
    ids: str | list[str] | None = None,
    collections: str | list[str] | None = None,
    max_items: int | None = None,
    limit: int | None = None,
    bbox: list[float] | None = None,
    datetime: str | None = None,
    include: str | list[str] | None = None,
    exclude: str | list[str] | None = None,
    sortby: str | list[str | dict[str, str]] | None = None,
    filter: str | dict[str, Any] | None = None,
    query: dict[str, Any] | None = None,
    fields: str | list[str] | dict[str, Any] | None = None,
    headers: dict[str, str] | None = None,
    max_extra_load: float | None = None,
    max_retries_per_request: int | None = None,
    retry_status_codes: list[int] | None = None,
    format: str | None = None,
    parquet_compression: str | None = None,
    store: AnyObjectStore | None = None,
    use_duckdb: bool | None = None,
) -> int

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

Parameters:

outfile (str) –

The output href. This can be a local file path, or any url scheme supported by [stac::object_store::write].
href (str) –

The STAC API to search.
intersects (str | dict[str, Any] | None, default: None ) –

Searches items by performing intersection between their geometry and provided GeoJSON geometry.
ids (str | list[str] | None, default: None ) –

Array of Item ids to return.
collections (str | list[str] | None, default: None ) –

Array of one or more Collection IDs that each matching Item must be in.
max_items (int | None, default: None ) –

The maximum number of items to iterate through.
limit (int | None, default: None ) –

The page size returned from the server. Use max_items to actually limit the number of items returned from this function.
bbox (list[float] | None, default: None ) –

Requested bounding box.
datetime (str | None, default: None ) –
Single date+time, or a range ('/' separator), formatted to RFC 3339, section 5.6. Use double dots .. for open date ranges.

Partial dates are also supported and will be automatically expanded to full RFC 3339 datetime ranges:
- Year only (e.g., "2023") expands to 2023-01-01T00:00:00Z/2023-12-31T23:59:59Z
- Year-Month (e.g., "2023-06") expands to 2023-06-01T00:00:00Z/2023-06-30T23:59:59Z
- ISO 8601 date (e.g., "2023-06-15") expands to 2023-06-15T00:00:00Z/2023-06-15T23:59:59Z
- Ranges also support partial dates (e.g., "2017/2018", "2017-06/2017-07")
include (str | list[str] | None, default: None ) –

fields to include in the response (see the extension docs) for more on the semantics).
exclude (str | list[str] | None, default: None ) –

fields to exclude from the response (see the extension docs) for more on the semantics).
sortby (str | list[str | dict[str, str]] | None, default: None ) –

Fields by which to sort results (use -field to sort descending).
filter (str | dict[str, Any] | None, default: None ) –

CQL2 filter expression. Strings will be interpreted as cql2-text, dictionaries as cql2-json.
query (dict[str, Any] | None, default: None ) –

Additional filtering based on properties. It is recommended to use filter instead, if possible.
fields (str | list[str] | dict[str, Any] | None, default: None ) –

Fields to include in or exclude from the response, per the fields extension. Strings are interpreted as a comma-delimited list (e.g. +properties.datetime,-geometry); lists as the same +/- prefixed field names (e.g. ["properties.datetime", "-geometry"]); dictionaries as {"include": [...], "exclude": [...]}. Any include or exclude arguments override the corresponding values set here.
headers (dict[str, str] | None, default: None ) –

Additional headers to include in requests to the STAC API.
max_extra_load (float | None, default: None ) –

The maximum extra load that retries are allowed to add to the server, as a fraction of the request rate. See the reqwest docs.
max_retries_per_request (int | None, default: None ) –

The maximum number of retries for a single request.
retry_status_codes (list[int] | None, default: None ) –

The HTTP status codes that should trigger a retry (e.g. [408, 429, 500, 502, 503, 504]).
format (str | None, default: None ) –

The output format. If none, will be inferred from the outfile extension, and if that fails will fall back to compact JSON.
parquet_compression (str | None, default: None ) –

If writing stac-geoparquet, sets the compression algorithm. https://docs.rs/parquet/latest/parquet/basic/enum.Compression.html is a list of what's available.
store (AnyObjectStore | None, default: None ) –

An optional [ObjectStore][]
use_duckdb (bool | None, default: None ) –

Query with DuckDB. If None and the href has a 'parquet' or 'geoparquet' extension, will be set to True. Defaults to None.

Returns:

int –

The number of items written

Examples:

>>> count = await rustac.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,
... )

rustac.search_sync

search_sync(
    href: str,
    *,
    intersects: str | dict[str, Any] | None = None,
    ids: str | list[str] | None = None,
    collections: str | list[str] | None = None,
    max_items: int | None = None,
    limit: int | None = None,
    bbox: list[float] | None = None,
    datetime: str | None = None,
    include: str | list[str] | None = None,
    exclude: str | list[str] | None = None,
    sortby: str | list[str | dict[str, str]] | None = None,
    filter: str | dict[str, Any] | None = None,
    query: dict[str, Any] | None = None,
    fields: str | list[str] | dict[str, Any] | None = None,
    headers: dict[str, str] | None = None,
    max_extra_load: float | None = None,
    max_retries_per_request: int | None = None,
    retry_status_codes: list[int] | None = None,
    use_duckdb: bool | None = None,
    **kwargs: str,
) -> list[dict[str, Any]]

Searches a STAC API server or a stac-geoparquet file synchronously.

Parameters:

href (str) –

The STAC API to search.
intersects (str | dict[str, Any] | None, default: None ) –

Searches items by performing intersection between their geometry and provided GeoJSON geometry.
ids (str | list[str] | None, default: None ) –

Array of Item ids to return.
collections (str | list[str] | None, default: None ) –

Array of one or more Collection IDs that each matching Item must be in.
max_items (int | None, default: None ) –

The maximum number of items to iterate through.
limit (int | None, default: None ) –

The page size returned from the server. Use max_items to actually limit the number of items returned from this function.
bbox (list[float] | None, default: None ) –

Requested bounding box.
datetime (str | None, default: None ) –
Single date+time, or a range (/ separator), formatted to RFC 3339, section 5.6. Use double dots .. for open date ranges.

Partial dates are also supported and will be automatically expanded to full RFC 3339 datetime ranges:
- Year only (e.g., "2023") expands to 2023-01-01T00:00:00Z/2023-12-31T23:59:59Z
- Year-Month (e.g., "2023-06") expands to 2023-06-01T00:00:00Z/2023-06-30T23:59:59Z
- ISO 8601 date (e.g., "2023-06-15") expands to 2023-06-15T00:00:00Z/2023-06-15T23:59:59Z
- Ranges also support partial dates (e.g., "2017/2018", "2017-06/2017-07")
include (str | list[str] | None, default: None ) –

fields to include in the response (see the extension docs) for more on the semantics).
exclude (str | list[str] | None, default: None ) –

fields to exclude from the response (see the extension docs) for more on the semantics).
sortby (str | list[str | dict[str, str]] | None, default: None ) –

Fields by which to sort results (use -field to sort descending).
filter (str | dict[str, Any] | None, default: None ) –

CQL2 filter expression. Strings will be interpreted as cql2-text, dictionaries as cql2-json.
query (dict[str, Any] | None, default: None ) –

Additional filtering based on properties. It is recommended to use filter instead, if possible.
fields (str | list[str] | dict[str, Any] | None, default: None ) –

Fields to include in or exclude from the response, per the fields extension. Strings are interpreted as a comma-delimited list (e.g. +properties.datetime,-geometry); lists as the same +/- prefixed field names (e.g. ["properties.datetime", "-geometry"]); dictionaries as {"include": [...], "exclude": [...]}. Any include or exclude arguments override the corresponding values set here.
headers (dict[str, str] | None, default: None ) –

Additional headers to include in requests to the STAC API.
max_extra_load (float | None, default: None ) –

The maximum extra load that retries are allowed to add to the server, as a fraction of the request rate. See the reqwest docs.
max_retries_per_request (int | None, default: None ) –

The maximum number of retries for a single request.
retry_status_codes (list[int] | None, default: None ) –

The HTTP status codes that should trigger a retry (e.g. [408, 429, 500, 502, 503, 504]).
use_duckdb (bool | None, default: None ) –

Query with DuckDB. If None and the href has a 'parquet' or 'geoparquet' extension, will be set to True. Defaults to None.
kwargs (str, default: {} ) –

Additional parameters to pass in to the search.

Returns:

list[dict[str, Any]] –

STAC items

Examples:

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

Search

rustac.search async

rustac.search_to async

rustac.search_sync

rustac.search `async`

rustac.search_to `async`