pub struct Client { /* private fields */ }Expand description
An async client for a STAC API.
This client provides methods for interacting with a STAC-compliant API,
allowing you to fetch Catalog, Collection, and Item objects, and to
perform searches.
The client is inexpensive to clone, as it wraps its internal state in an Arc.
Implementations§
Source§impl Client
impl Client
Sourcepub fn new(base_url: &str) -> Result<Self>
pub fn new(base_url: &str) -> Result<Self>
Creates a new Client for a given STAC API base URL.
§Arguments
base_url- The base URL of the STAC API (e.g.,"https://planetarycomputer.microsoft.com/api/stac/v1").
§Errors
Returns an Error::Url if the provided base_url is not a valid URL.
Sourcepub fn with_client(base_url: &str, client: Client) -> Result<Self>
pub fn with_client(base_url: &str, client: Client) -> Result<Self>
Creates a new Client from an existing reqwest::Client.
This allows for customization of the underlying HTTP client, such as setting default headers, proxies, or timeouts.
§Errors
Returns an Error::Url if the provided base_url is not a valid URL.
Sourcepub async fn get_catalog(&self) -> Result<Catalog>
pub async fn get_catalog(&self) -> Result<Catalog>
Fetches the root Catalog or Collection from the API.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn get_collections(&self) -> Result<Vec<Collection>>
pub async fn get_collections(&self) -> Result<Vec<Collection>>
Fetches all Collection objects from the /collections endpoint.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn get_collection(&self, collection_id: &str) -> Result<Collection>
pub async fn get_collection(&self, collection_id: &str) -> Result<Collection>
Fetches a single Collection by its ID from the /collections/{collection_id} endpoint.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn get_collection_items(
&self,
collection_id: &str,
limit: Option<u32>,
) -> Result<ItemCollection>
pub async fn get_collection_items( &self, collection_id: &str, limit: Option<u32>, ) -> Result<ItemCollection>
Fetches an ItemCollection of Item objects from a specific collection.
This method retrieves items from the /collections/{collection_id}/items endpoint.
Note that this retrieves only a single page of items; the limit parameter
can be used to control the page size.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn get_item(&self, collection_id: &str, item_id: &str) -> Result<Item>
pub async fn get_item(&self, collection_id: &str, item_id: &str) -> Result<Item>
Fetches a single Item by its collection ID and item ID.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn search(&self, params: &SearchParams) -> Result<ItemCollection>
pub async fn search(&self, params: &SearchParams) -> Result<ItemCollection>
Searches for Item objects using the POST /search endpoint.
This is the preferred method for searching, as it supports complex queries that may be too long for a GET request’s URL.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn search_get(&self, params: &SearchParams) -> Result<ItemCollection>
pub async fn search_get(&self, params: &SearchParams) -> Result<ItemCollection>
Searches for Item objects using the GET /search endpoint.
The SearchParams are converted into URL query parameters.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn conformance(&self) -> Result<&Conformance>
pub async fn conformance(&self) -> Result<&Conformance>
Fetches the API’s conformance classes from the /conformance endpoint.
The result is cached, so subsequent calls will not make a new network request.
§Errors
Returns an Error if the request fails or the response cannot be parsed.
Sourcepub async fn download_asset(&self, asset: &Asset) -> Result<DownloadedAsset>
pub async fn download_asset(&self, asset: &Asset) -> Result<DownloadedAsset>
Downloads a STAC Asset into memory.
This method fetches the asset’s data from its href URL and returns a
DownloadedAsset containing the raw bytes. It reuses the client’s
authentication and resilience settings.
§Arguments
asset- A reference to theAssetto be downloaded.
§Errors
Returns an Error if the href is not a valid URL, the request fails,
or the response body cannot be read.