> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# STAC client

> Search SpatioTemporal Asset Catalog (STAC) APIs and load items into Spark DataFrames.

```python theme={"system"}
from sedona.spark.stac import Client
```

## Client

```python theme={"system"}
Client(url: str, headers: Optional[dict] = None)
```

Initializes a STAC client with optional authentication headers.

#### Parameters

<ParamField path="url" type="str" required>
  The URL of the STAC API to connect to.
</ParamField>

<ParamField path="headers" type="Optional[dict]" default="None">
  Optional dictionary of HTTP headers to include in requests.
  Can be used for authentication or custom headers.
</ParamField>

### get\_collection()

```python theme={"system"}
get_collection(collection_id: str)
```

Retrieves a collection client for the specified collection ID.

This method creates an instance of the CollectionClient class for the given collection ID,
allowing interaction with the specified collection in the STAC API.

#### Parameters

<ParamField path="collection_id" type="str" required>
  The ID of the collection to retrieve. Example: "aster-l1t"
</ParamField>

#### Returns

<ResponseField name="return">
  An instance of the CollectionClient class for the specified collection.
</ResponseField>

### get\_collection\_from\_catalog()

```python theme={"system"}
get_collection_from_catalog()
```

Retrieves the catalog from the STAC API.

This method fetches the root catalog from the STAC API, providing access to all collections and items.

#### Returns

<ResponseField name="dict">
  The root catalog of the STAC API.
</ResponseField>

### open()

```python theme={"system"}
Client.open(url: str, headers: Optional[dict] = None)
```

Opens a connection to the specified STAC API URL.

This class method creates an instance of the Client class with the given URL
and optional authentication headers.

#### Parameters

<ParamField path="url" type="str" required>
  The URL of the STAC API to connect to. Example: "[https://planetarycomputer.microsoft.com/api/stac/v1](https://planetarycomputer.microsoft.com/api/stac/v1)"
</ParamField>

<ParamField path="headers" type="Optional[dict]" default="None">
  Optional dictionary of HTTP headers for authentication.
  Example: \{"Authorization": "Bearer token123"}
</ParamField>

#### Returns

<ResponseField name="return">
  An instance of the Client class connected to the specified URL.

  Example usage:

  # Without authentication

  client = Client.open("[https://planetarycomputer.microsoft.com/api/stac/v1](https://planetarycomputer.microsoft.com/api/stac/v1)")

  # With custom headers

  client = Client.open(
  "[https://example.com/stac/v1](https://example.com/stac/v1)",
  headers=\{"Authorization": "Bearer token123"}
  )

  # Using convenience methods

  client = Client.open("[https://example.com/stac/v1](https://example.com/stac/v1)")
  client.with\_basic\_auth("username", "password")
</ResponseField>

### search()

```python theme={"system"}
search(
    *ids: Union[str, list],
    collection_id: Optional[str] = None,
    bbox: Optional[list] = None,
    geometry: Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]] = None,
    datetime: Optional[Union[str, python_datetime.datetime, list]] = None,
    max_items: Optional[int] = None,
    return_dataframe: bool = True,
) -> Union[Iterator, DataFrame]
```

Searches for items in the specified collection with optional filters.

#### Parameters

<ParamField path="ids" type="Union[str, list]">
  A variable number of item IDs to filter the items.
  Example: "item\_id1" or \["item\_id1", "item\_id2"]
</ParamField>

<ParamField path="collection_id" type="Optional[str]" default="None">
  The ID of the collection to search in.
  Example: "aster-l1t"
</ParamField>

<ParamField path="bbox" type="Optional[list]" default="None">
  A list of bounding boxes for filtering the items.
  Each bounding box is represented as a list of four float values: \[min\_lon, min\_lat, max\_lon, max\_lat].
  Example: \[\[-180.0, -90.0, 180.0, 90.0]]  # This bounding box covers the entire world.
</ParamField>

<ParamField path="geometry" type="Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]]" default="None">
  Shapely geometry object(s) or WKT string(s) for spatial filtering.
  Can be a single geometry, WKT string, or a list of geometries/WKT strings.
  If both bbox and geometry are provided, geometry takes precedence.
  Example: Polygon(...) or "POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" or \[Polygon(...), Polygon(...)]
</ParamField>

<ParamField path="datetime" type="Optional[Union[str, python_datetime.datetime, list]]" default="None">
  A single datetime, RFC 3339-compliant timestamp,
  or a list of date-time ranges for filtering the items. The datetime can be specified in various formats:

  * "YYYY" expands to \["YYYY-01-01T00:00:00Z", "YYYY-12-31T23:59:59.999999Z"]
  * "YYYY-mm" expands to \["YYYY-mm-01T00:00:00Z", "YYYY-mm-\<last\_day>T23:59:59.999999Z"]
  * "YYYY-mm-dd" expands to \["YYYY-mm-ddT00:00:00Z", "YYYY-mm-ddT23:59:59.999999Z"]
  * "YYYY-mm-ddTHH:MM:SSZ" remains as \["YYYY-mm-ddTHH:MM:SSZ", "YYYY-mm-ddTHH:MM:SSZ"]
  * A list of date-time ranges can be provided for multiple intervals.

  Example: "2020-01-01T00:00:00Z" or python\_datetime.datetime(2020, 1, 1) or \[\["2020-01-01T00:00:00Z", "2021-01-01T00:00:00Z"]]
</ParamField>

<ParamField path="max_items" type="Optional[int]" default="None">
  The maximum number of STAC API results to return. Supported
  single-collection bbox/datetime searches follow pystac-client semantics and
  trust the API's matching behavior. Multiple bboxes are queried independently,
  unioned, and deduplicated before the final result limit; extended Spark-side
  filters are applied before that limit. Example: 100
</ParamField>

<ParamField path="return_dataframe" type="bool" default="True">
  If True, return the result as a Spark DataFrame instead of an iterator of PyStacItem objects.
  Example: True
</ParamField>

#### Returns

<ResponseField name="return" type="Union[Iterator, DataFrame]">
  An iterator of PyStacItem objects or a Spark DataFrame that match the specified filters.
</ResponseField>

### with\_basic\_auth()

```python theme={"system"}
with_basic_auth(username: str, password: str)
```

Adds HTTP Basic Authentication to the client.

This method encodes the username and password using Base64 and adds
the appropriate Authorization header for HTTP Basic Authentication.

#### Parameters

<ParamField path="username" type="str" required>
  The username for authentication. For API keys, this is typically the API key itself.
</ParamField>

<ParamField path="password" type="str" required>
  The password for authentication. For API keys, this is often left empty.
</ParamField>

#### Returns

<ResponseField name="return">
  Self for method chaining.

  Example usage:

  # Standard basic auth

  client = Client.open("[https://example.com/stac/v1](https://example.com/stac/v1)")
  client.with\_basic\_auth("user", "pass")

  # API key as username (common pattern)

  client.with\_basic\_auth("api\_key\_xyz", "")

  # Method chaining

  df = Client.open(url).with\_basic\_auth(api\_key, "").search(collection\_id="test")
</ResponseField>

### with\_bearer\_token()

```python theme={"system"}
with_bearer_token(token: str)
```

Adds Bearer Token Authentication to the client.

This method adds the appropriate Authorization header for Bearer Token
authentication, commonly used with OAuth2 and API tokens.

#### Parameters

<ParamField path="token" type="str" required>
  The bearer token for authentication.
</ParamField>

#### Returns

<ResponseField name="return">
  Self for method chaining.

  Example usage:

  # Bearer token auth

  client = Client.open("[https://example.com/stac/v1](https://example.com/stac/v1)")
  client.with\_bearer\_token("your\_access\_token\_here")

  # Method chaining

  df = Client.open(url).with\_bearer\_token(token).search(collection\_id="test")
</ResponseField>

## CollectionClient

Import from `sedona.spark.stac.collection_client`.

```python theme={"system"}
CollectionClient(
    url: str,
    collection_id: Optional[str] = None,
    headers: Optional[dict] = None,
)
```

Initializes a collection client for a STAC collection.

#### Parameters

<ParamField path="url" type="str" required>
  The base URL of the STAC API.
</ParamField>

<ParamField path="collection_id" type="Optional[str]" default="None">
  The ID of the collection to access. If None, accesses the catalog root.
</ParamField>

<ParamField path="headers" type="Optional[dict]" default="None">
  Optional dictionary of HTTP headers for authentication.
</ParamField>

### get\_dataframe()

```python theme={"system"}
get_dataframe(
    *ids: Union[str, list],
    bbox: Optional[list] = None,
    geometry: Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]] = None,
    datetime: Optional[Union[str, python_datetime.datetime, list]] = None,
    max_items: Optional[int] = None,
) -> DataFrame
```

Returns a Spark DataFrame of items with optional spatial and temporal extents.

This method loads the collection data from the specified collection URL and applies
optional spatial and temporal filters to the data. The spatial filter is applied using
a bounding box, and the temporal filter is applied using a date-time range.

#### Parameters

<ParamField path="ids" type="Union[str, list]">
  A variable number of item IDs to filter the items.
  Example: "item\_id1" or \["item\_id1", "item\_id2"]
</ParamField>

<ParamField path="bbox" type="Optional[list]" default="None">
  A list of bounding boxes for filtering the items.
  Each bounding box is represented as a list of four float values: \[min\_lon, min\_lat, max\_lon, max\_lat].
  Example: \[\[-180.0, -90.0, 180.0, 90.0]]  # This bounding box covers the entire world.
</ParamField>

<ParamField path="geometry" type="Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]]" default="None">
  Shapely geometry object(s) or WKT string(s) for spatial filtering.
  Can be a single geometry, WKT string, or a list of geometries/WKT strings.
  If both bbox and geometry are provided, geometry takes precedence.
  Example: Polygon(...) or "POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" or \[Polygon(...), Polygon(...)]
</ParamField>

<ParamField path="datetime" type="Optional[Union[str, python_datetime.datetime, list]]" default="None">
  A single datetime, RFC 3339-compliant timestamp,
  or a list of date-time ranges for filtering the items.
  Example: "2020-01-01T00:00:00Z" or python\_datetime.datetime(2020, 1, 1) or \[\["2020-01-01T00:00:00Z", "2021-01-01T00:00:00Z"]]
</ParamField>

<ParamField path="max_items" type="Optional[int]" default="None">
  The maximum number of STAC API results to return. Supported
  single-collection bbox/datetime searches follow pystac-client semantics and
  trust the API's matching behavior. Multiple bboxes are queried independently,
  unioned, and deduplicated before the final result limit; extended Spark-side
  filters are applied before that limit.
</ParamField>

#### Returns

<ResponseField name="return" type="DataFrame">
  A Spark DataFrame containing the filtered items. If no filters are provided,
  the DataFrame contains all items in the collection.
</ResponseField>

#### Raises

* `RuntimeError`: If there is an error loading the data or applying the filters, a RuntimeError
  is raised with a message indicating the failure.

### get\_items()

```python theme={"system"}
get_items(
    *ids: Union[str, list],
    bbox: Optional[list] = None,
    geometry: Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]] = None,
    datetime: Optional[Union[str, python_datetime.datetime, list]] = None,
    max_items: Optional[int] = None,
) -> Iterator
```

Returns an iterator of items. Each item has the supplied item ID and/or optional spatial and temporal extents.

This method loads the collection data from the specified collection URL and applies
optional filters to the data.

#### Parameters

<ParamField path="ids" type="Union[str, list]">
  A list of item IDs to filter the items. If not provided, no ID filtering is applied.
</ParamField>

<ParamField path="bbox" type="Optional[list]" default="None">
  A list of bounding boxes for filtering the items.
</ParamField>

<ParamField path="geometry" type="Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]]" default="None">
  Shapely geometry object(s) or WKT string(s) for spatial filtering.
  Can be a single geometry, WKT string, or a list of geometries/WKT strings.
  If both bbox and geometry are provided, geometry takes precedence.
</ParamField>

<ParamField path="datetime" type="Optional[Union[str, python_datetime.datetime, list]]" default="None">
  A single datetime, RFC 3339-compliant timestamp,
  or a list of date-time ranges for filtering the items.
</ParamField>

<ParamField path="max_items" type="Optional[int]" default="None">
  The maximum number of STAC API results to return. Supported
  single-collection bbox/datetime searches follow pystac-client semantics and
  trust the API's matching behavior. Multiple bboxes are queried independently,
  unioned, and deduplicated before the final result limit; extended Spark-side
  filters are applied before that limit.
</ParamField>

#### Returns

<ResponseField name="return" type="Iterator">
  An iterator of PyStacItem objects that match the specified filters.
  If no filters are provided, the iterator contains all items in the collection.
</ResponseField>

#### Raises

* `RuntimeError`: If there is an error loading the data or applying the filters, a RuntimeError
  is raised with a message indicating the failure.

### load\_items\_df()

```python theme={"system"}
load_items_df(bbox, geometry, datetime, ids, max_items)
```

Loads items from the STAC collection as a Spark DataFrame.

This method handles the conversion of headers to Spark options and
applies various filters to the data.

#### Parameters

<ParamField path="bbox" required />

<ParamField path="geometry" required />

<ParamField path="datetime" required />

<ParamField path="ids" required />

<ParamField path="max_items" required />

### save\_to\_geoparquet()

```python theme={"system"}
save_to_geoparquet(
    *ids: Union[str, list],
    output_path: str,
    bbox: Optional[list] = None,
    geometry: Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]] = None,
    datetime: Optional[list] = None,
) -> None
```

Loads the STAC DataFrame and saves it to Parquet format at the given output path.

This method loads the collection data from the specified collection URL and applies
optional spatial and temporal filters to the data. The filtered data is then saved
to the specified output path in Parquet format.

#### Parameters

<ParamField path="ids" type="Union[str, list]">
  A list of item IDs to filter the items. If not provided, no ID filtering is applied.
</ParamField>

<ParamField path="output_path" type="str" required>
  The path where the Parquet file will be saved.
</ParamField>

<ParamField path="bbox" type="Optional[list]" default="None">
  A bounding box for filtering the items. If not provided, no spatial filtering is applied.
</ParamField>

<ParamField path="geometry" type="Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]]" default="None">
  Shapely geometry object(s) or WKT string(s) for spatial filtering.
  If both bbox and geometry are provided, geometry takes precedence.
</ParamField>

<ParamField path="datetime" type="Optional[list]" default="None">
  A temporal extent that defines the
  date-time range for filtering the items. If not provided, no temporal filtering is applied.
  To match a single datetime, you can set the start and end datetime to the same value in the datetime.
  Example: \[\["2020-01-01T00:00:00Z", "2020-01-01T00:00:00Z"]]
</ParamField>

#### Raises

* `RuntimeError`: If there is an error loading the data, applying the filters, or saving the
  DataFrame to Parquet format, a RuntimeError is raised with a message indicating the failure.

## get\_collection\_url

Import from `sedona.spark.stac.collection_client`.

```python theme={"system"}
get_collection_url(url: str, collection_id: Optional[str] = None) -> str
```

Constructs the collection URL based on the provided base URL and optional collection ID.

If the collection ID is provided and the URL starts with 'http' or 'https', the collection ID
is appended to the URL. Otherwise, an exception is raised.

#### Parameters

<ParamField path="url" type="str" required>
  The base URL of the STAC collection.
</ParamField>

<ParamField path="collection_id" type="Optional[str]" default="None">
  The optional collection ID to append to the URL.
</ParamField>

#### Returns

<ResponseField name="str" type="str">
  The constructed collection URL.
</ResponseField>

#### Raises

* `ValueError`: If the URL does not start with 'http' or 'https' and a collection ID is provided.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.