Crate stac_client 

STAC Client for Rust

A friendly, async client for the SpatioTemporal Asset Catalog (STAC) specification, written in Rust.

This library helps you interact with STAC APIs to find and retrieve geospatial data. It is built on tokio for async operations and reqwest for HTTP requests.

Project Goals

• Idiomatic Rust API: Provide an API that feels natural to Rust developers.
• Minimal Dependencies: Keep the dependency tree small and manageable.
• Well-Documented: Offer clear documentation for all public APIs.
• Thoroughly Tested: Maintain high test coverage to ensure stability.

Quick Start

use stac_client::{Client, SearchBuilder};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let url = "https://planetarycomputer.microsoft.com/api/stac/v1";
    let client = Client::new(url)?;

    let search = SearchBuilder::new()
        .collections(vec!["sentinel-2-l2a".to_string()])
        .limit(10)
        .build();

    let results = client.search(&search).await?;
    println!("Found {} items.", results.features.len());

    Ok(())
}

Optional Features

• pagination: Enables the Client::search_next_page method for easy pagination.
• resilience: Enables resilience features including retries with exponential backoff, jitter, and timeout configurations. Use ClientBuilder to configure these features.
• auth: Enables pluggable authentication support with ApiKey, BearerToken, and custom AuthLayer implementations for protected STAC APIs.

Using the Resilience Feature

When the resilience feature is enabled, you can use ClientBuilder to configure retry and timeout behavior:

use stac_client::{ClientBuilder, ResiliencePolicy};
use std::time::Duration;

// Create a custom resilience policy
let policy = ResiliencePolicy::new()
    .max_attempts(5)
    .base_delay(Duration::from_millis(100))
    .max_delay(Duration::from_secs(30))
    .retry_5xx(true)
    .retry_429(true)
    .request_timeout(Some(Duration::from_secs(30)))
    .connect_timeout(Some(Duration::from_secs(10)))
    .total_timeout(Some(Duration::from_secs(120)));

// Build a client with the policy
let client = ClientBuilder::new("https://planetarycomputer.microsoft.com/api/stac/v1")
    .resilience_policy(policy)
    .build()?;

// Use the client normally - retries and timeouts are handled automatically
let catalog = client.get_catalog().await?;

Using the Authentication Feature

When the auth feature is enabled, you can add authentication layers to your client:

use stac_client::{ClientBuilder, auth::{ApiKey, BearerToken}};

// API Key authentication
let client = ClientBuilder::new("https://api.example.com/stac")
    .auth_layer(ApiKey::new("X-API-Key", "your-secret-key"))
    .build()?;

// Bearer token authentication
let client = ClientBuilder::new("https://api.example.com/stac")
    .auth_layer(BearerToken::new("your-jwt-token"))
    .build()?;

// Multiple auth layers can be combined
let client = ClientBuilder::new("https://api.example.com/stac")
    .auth_layer(ApiKey::new("X-API-Key", "key123"))
    .auth_layer(BearerToken::new("token456"))
    .build()?;

// Use the client - auth is applied automatically
let catalog = client.get_catalog().await?;

Re-exports

pub use client::Client;

pub use client::SearchBuilder;

pub use error::Error;

pub use error::Result;

pub use models::*;

Modules

client

The core STAC API client and search builder. The core STAC API client and search builder.

error

Error and result types. Defines the error types and Result alias used throughout the stac-client crate.

models

STAC data models, such as Item, Collection, and Catalog. STAC data models, such as Item, Collection, and Catalog.