from sedona.spark.stac import Client

Client

Client(url: str, headers: Optional[dict] = None)

Initializes a STAC client with optional authentication headers.

Parameters

str

required

The URL of the STAC API to connect to.

Optional[dict]

default:"None"

Optional dictionary of HTTP headers to include in requests. Can be used for authentication or custom headers.

get_collection()

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

str

required

The ID of the collection to retrieve. Example: “aster-l1t”

Returns

An instance of the CollectionClient class for the specified collection.

get_collection_from_catalog()

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

The root catalog of the STAC API.

open()

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

str

required

The URL of the STAC API to connect to. Example: “https://planetarycomputer.microsoft.com/api/stac/v1”

Optional[dict]

default:"None"

Optional dictionary of HTTP headers for authentication. Example: {“Authorization”: “Bearer token123”}

Returns

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”)

With custom headers

client = Client.open( “https://example.com/stac/v1”, headers={“Authorization”: “Bearer token123”} )

Using convenience methods

client = Client.open(“https://example.com/stac/v1”) client.with_basic_auth(“username”, “password”)

search()

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

Union[str, list]

A variable number of item IDs to filter the items. Example: “item_id1” or [“item_id1”, “item_id2”]

Optional[str]

default:"None"

The ID of the collection to search in. Example: “aster-l1t”

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.

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(…)]

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”]]

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

bool

default:"True"

If True, return the result as a Spark DataFrame instead of an iterator of PyStacItem objects. Example: True

Returns

Union[Iterator, DataFrame]

An iterator of PyStacItem objects or a Spark DataFrame that match the specified filters.

with_basic_auth()

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

str

required

The username for authentication. For API keys, this is typically the API key itself.

str

required

The password for authentication. For API keys, this is often left empty.

Returns

Self for method chaining.Example usage:

Standard basic auth

client = Client.open(“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”)

with_bearer_token()

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

str

required

The bearer token for authentication.

Returns

Self for method chaining.Example usage:

Bearer token auth

client = Client.open(“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”)

CollectionClient

Import from sedona.spark.stac.collection_client.

CollectionClient(
    url: str,
    collection_id: Optional[str] = None,
    headers: Optional[dict] = None,
)

Initializes a collection client for a STAC collection.

Parameters

str

required

The base URL of the STAC API.

Optional[str]

default:"None"

The ID of the collection to access. If None, accesses the catalog root.

Optional[dict]

default:"None"

Optional dictionary of HTTP headers for authentication.

get_dataframe()

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

Union[str, list]

A variable number of item IDs to filter the items. Example: “item_id1” or [“item_id1”, “item_id2”]

Optional[list]

default:"None"

Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]]

default:"None"

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”]]

Optional[int]

default:"None"

Returns

DataFrame

A Spark DataFrame containing the filtered items. If no filters are provided, the DataFrame contains all items in the collection.

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

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

Union[str, list]

A list of item IDs to filter the items. If not provided, no ID filtering is applied.

Optional[list]

default:"None"

A list of bounding boxes for filtering the items.

Optional[Union[str, BaseGeometry, List[Union[str, BaseGeometry]]]]

default:"None"

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.

Optional[int]

default:"None"

Returns

Iterator

An iterator of PyStacItem objects that match the specified filters. If no filters are provided, the iterator contains all items in the collection.

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

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

required

save_to_geoparquet()

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

Union[str, list]

A list of item IDs to filter the items. If not provided, no ID filtering is applied.

str

required

The path where the Parquet file will be saved.

Optional[list]

default:"None"

A bounding box for filtering the items. If not provided, no spatial filtering is applied.

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.

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”]]

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.

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

str

required

The base URL of the STAC collection.

Optional[str]

default:"None"

The optional collection ID to append to the URL.

Returns

str

The constructed collection URL.

Raises

ValueError: If the URL does not start with ‘http’ or ‘https’ and a collection ID is provided.

​Client

​Parameters

​get_collection()

​Parameters

​Returns

​get_collection_from_catalog()

​Returns

​open()

​Parameters

​Returns

​Without authentication

​With custom headers

​Using convenience methods

​search()

​Parameters

​Returns

​with_basic_auth()

​Parameters

​Returns

​Standard basic auth

​API key as username (common pattern)

​Method chaining

​with_bearer_token()

​Parameters

​Returns

​Bearer token auth

​Method chaining

​CollectionClient

​Parameters

​get_dataframe()

​Parameters

​Returns

​Raises

​get_items()

​Parameters

​Returns

​Raises

​load_items_df()

​Parameters

​save_to_geoparquet()

​Parameters

​Raises

​get_collection_url

​Parameters

​Returns

​Raises

Client

Parameters

get_collection()

Parameters

Returns

get_collection_from_catalog()

Returns

open()

Parameters

Returns

Without authentication

With custom headers

Using convenience methods

search()

Parameters

Returns

with_basic_auth()

Parameters

Returns

Standard basic auth

API key as username (common pattern)

Method chaining

with_bearer_token()

Parameters

Returns

Bearer token auth

Method chaining

CollectionClient

Parameters

get_dataframe()

Parameters

Returns

Raises

get_items()

Parameters

Returns

Raises

load_items_df()

Parameters

save_to_geoparquet()

Parameters

Raises

get_collection_url

Parameters

Returns

Raises