Federated Collection Discovery

A React application for searching multiple STAC APIs simultaneously. Built with STAC FastAPI Collection Discovery API, this tool performs federated collection searches across multiple STAC API endpoints at once. Configure which STAC APIs to query, view comprehensive collection metadata, and get item-search code hints—all from a single unified interface.

Features

• Simultaneous Multi-API Search: Search multiple STAC APIs at once for comprehensive results across all configured endpoints
• Interactive Collection Details: Comprehensive modal with collection metadata, spatial/temporal extents, providers, and links
• Code Generation: Client-generated STAC item search examples in Python and R with dynamic values
• Pagination Support: Load more results with STAC-compliant pagination using rel=next links
• API Management: Configure, add, remove, and monitor STAC API endpoints with health diagnostics
• Conformance Checking: Automatic detection of STAC API capabilities (collection search, free-text search)
• Client-Side Filtering: Configurable per-API filtering for deployment customization
• Responsive Design: Mobile-friendly interface with sorting and filtering capabilities
• Visual Mapping: Interactive maps showing spatial extents for collections
• Health Monitoring: Real-time API health status with detailed conformance and capability information

Table of Contents

• Features
• Development
• Running with Docker
• Running in local environment
• Configuration
• Usage

Development

Installation

yarn install

Testing

TODO: write tests for client app

Running with Docker

For development and testing, a Docker setup is provided that includes both the client application and an optional backend service for advanced use cases.

Build and start the services:

docker compose up --build

This will start:

• Client application: http://localhost:3000
• Backend service (STAC API): http://localhost:8000

Stop the services:

docker compose down

Running in local environment

Option 1: Client-Only

Start the development server (pointed at a deployed backend API):

yarn install
VITE_API_URL=https://discover-api.dit.maap-project.org yarn dev

Access the application at http://localhost:3000

Option 2: With Optional Backend Service

If you want to run the STAC Collection Discovery API locally during development:

1. Install Python dependencies:

uv sync

1. Start the backend service:

uv run uvicorn stac_fastapi.collection_discovery.app:app \
  --host 0.0.0.0 --port 8000 --reload

1. Start the React development server:

yarn dev

Access:

• Client application: http://localhost:3000
• Backend service: http://localhost:8000

Configuration

API Configuration

The application searches multiple STAC API endpoints simultaneously. Configure which STAC APIs to query:

Environment Variables

• VITE_API_URL: URL to the STAC FastAPI Collection Discovery API

Runtime Configuration

Use the Settings button in the API Configuration panel to:

• Add/Remove APIs: Configure which STAC API endpoints to search simultaneously
• Health Monitoring: View real-time health status and conformance information for each API
• Capability Detection: See which APIs support collection search and free-text search
• Default APIs: Reset to the APIs configured in config.ts

Default STAC APIs Configuration

The default STAC APIs that the application queries are configured in /src/config.ts in the DEFAULT_API_CONFIGURATIONS array. Edit this file to specify which STAC APIs should be available by default and optionally add custom filter functions:

export const DEFAULT_API_CONFIGURATIONS: ApiConfiguration[] = [
  {
    url: "https://your-stac-api.example.com/",
    // Optional: Filter collections by license
    filter: (collection) => {
      const license = collection.license;
      return license && license.toLowerCase().includes("cc");
    },
  },
];

Available filter examples:

• License-based filtering
• Provider-based filtering
• Date-based filtering (e.g., only recent collections)
• Spatial resolution filtering
• Keyword-based filtering

Usage

API Configuration & Health

1. Configure APIs: Click the Settings button in the API Configuration panel
2. Health Status: Monitor the status indicator (green=healthy, red=issues, orange=limited functionality)
3. Diagnostics: Use the Diagnostics tab to see detailed API health and conformance information

Search Collections

1. Basic Search: Enter search parameters in the left panel:

   • Bounding Box: Define spatial area of interest using the map or coordinates
   • Date Range: Specify temporal coverage with date pickers
   • Free Text: Add keywords or collection names (if supported by configured APIs)

2. View Results: Collections appear in the right panel table with:

   • Sortable columns (title, ID, API source)
   • Click "Details" button for comprehensive collection information
   • Results from all configured STAC APIs are aggregated and displayed together

Collection Details Modal

The comprehensive collection details modal provides:

• Core Information: Collection ID, source API, title, and description
• Spatial/Temporal Extents: Interactive maps showing collection coverage and formatted date ranges
• Providers: Enhanced display with roles, descriptions, and contact links
• Code Generation: Ready-to-use Python and R examples for STAC item searches with your specific search parameters
• Collapsible Sections:
  • Links: All collection relationships and associated resources
  • Raw JSON: Complete collection metadata for developers

Pagination & Results

• Progressive Loading: Results are loaded from the Collection Discovery API
• Load More: When available, a "Load More" button appears to fetch additional results from the backend
• Pagination Support: The backend handles pagination across multiple STAC APIs seamlessly
• Result Persistence: New results are appended without losing your current position

Advanced Features

• Conformance Checking: Backend performs automatic detection of STAC API capabilities
• Error Handling: Backend provides graceful handling of API outages with partial results from healthy endpoints
• Client-Side Filtering: Apply custom filters per API based on deployment-specific requirements configured in config.ts
• Responsive Design: Full functionality on desktop, tablet, and mobile devices