API endpoints

Wildfire Visualization Platform API Documentation

1. Introduction

This document provides an overview of the API endpoints and interactions for the Wildfire Visualization Platform. The platform enables users to access historical wildfire data, visualize map layers, and save configuration settings. It is designed to support effective communication between the frontend and backend, enabling data retrieval, visualization, and configuration management.
Note: All endpoints are prefixed with /api/.

2. API Overview

The API allows the frontend to communicate with the backend for data retrieval, configuration, and visualization, supporting a dynamic and interactive user experience. In our codebase, the terms "collections" and "datasets" are used interchangeably. In this documentation, we will refer to them as datasets.

3. API Endpoints

3.1 Configuration Management

• GET /api/config

  • Purpose: Retrieve saved configuration settings for the application.
  • Response: Returns a JSON object with the current configuration settings.
  • Use Case: Initializes the frontend with the user’s preferences and settings upon loading the application.

• POST /api/config

  • Purpose: Save or update configuration settings to persist user preferences.
  • Request Body: JSON object containing configuration details.

    {
      "defaultDataset": "dataset123",
      "layerPreferences": ["fire_perimeter", "satellite"],
      "mapSettings": {
        "zoomLevel": 5,
        "center": [45.0, -75.0]
      },
      "uiSettings": {
        "theme": "dark",
        "showLegend": true
      }
    }

  • Use Case: Allows the user to save preferences, ensuring configurations persist across sessions.

3.2 Dataset (Collection) Management

• GET /api/get-collections

  • Purpose: List available datasets (collections) with metadata (e.g., name, description). Supports optional filtering by bounding box.
  • Response: Returns metadata for each dataset.
  • Use Case: Enables users to browse and select datasets without loading full data details.

• GET /api/get-collections-by-name

  • Purpose: Retrieve datasets sorted by name. Accepts optional query parameters such as bbox and sortDirection (default 'asc').
  • Use Case: Allows users to view collections sorted alphabetically.

• GET /api/get-collections-by-date

  • Purpose: Retrieve datasets sorted by date. Accepts optional query parameters such as bbox and sortDirection (default 'asc').
  • Use Case: Allows users to view collections sorted by date.

• GET /api/metadata/{collectionId}

  • Purpose: Retrieve detailed metadata for a specific dataset.
  • Use Case: Used when a user selects a dataset to explore or visualize in detail.

• GET /api/fetch-collections-items/{collectionId}

  • Purpose: Fetch items (e.g., STAC items) for a given dataset.
  • Use Case: Retrieves detailed data associated with a dataset.

• GET /api/fetch-progress/{collectionId}

  • Purpose: Provide the current progress of data fetching or processing for a dataset.
  • Response: JSON object with collectionId and progress percentage.
  • Use Case: Displays a progress bar during data processing.

• GET /api/fetch-items-timestamps

  • Purpose: Retrieve an array of timestamps for items in datasets.
  • Use Case: Supports time navigation on the frontend.

• GET /api/get-item/{itemId}

  • Purpose: Retrieve details for a specific item.
  • Use Case: Displays item-level details on the frontend.

• GET /api/verify-collections

  • Purpose: Verify if a given endpoint contains datasets.
  • Use Case: Checks data validity before fetching collections.

• GET /api/fetch-collections

  • Purpose: Fetch collections from an external endpoint.
  • Use Case: Used for integrating external data sources.

• GET /api/reset-collections

  • Purpose: Reset the collections stored in the backend.
  • Use Case: Clears outdated datasets.

• GET /api/reset-items

  • Purpose: Reset items stored in the backend.
  • Use Case: Clears item-level data.

3.3 Map Layer and Datalayer Management

• GET /api/set-datalayer-geometry/{collectionId}

  • Purpose: Set the geometry for a datalayer view of a dataset.
  • Use Case: Updates the map layer based on dataset geometry.

• GET /api/reset-datalayer-view

  • Purpose: Reset the datalayer view to default settings.
  • Use Case: Clears custom datalayer configurations.

3.4 Connectivity and Verification

• GET /api/verify-internet-connection
  • Purpose: Verify the internet connection for a given endpoint.
  • Query Parameter: endpointUrl
  • Use Case: Checks connectivity before performing further actions.

4. API Usage Examples

Example 1: Retrieving Configuration Settings

GET /config Response: { "defaultDataset": "dataset123", "layerPreferences": ["fire_perimeter", "satellite"], "mapSettings": { ... }, "uiSettings": { ... } }

Example 2: Saving New Configuration Settings

POST /config Request Body: { "defaultDataset": "dataset456", "layerPreferences": ["fire_perimeter"], "mapSettings": { ... }, "uiSettings": { ... } } Response: 200 OK

Example 3: Listing Available Datasets

GET /datasets Response: [ { "dataset_id": "123", "name": "Wildfire 2020", "description": "Dataset for 2020 wildfires" }, { "dataset_id": "456", "name": "Wildfire 2021", "description": "Dataset for 2021 wildfires" } ]

5. Technical Considerations

• Endpoint Prefix: All endpoints are prefixed with /api/ to differentiate API calls from other routes.
• Terminology: The terms “collections” and “datasets” are used interchangeably.
• Response Formats: Endpoints generally return JSON objects. In case of errors, a JSON object with an "error" key is returned.
• Query Parameters: Some endpoints support query parameters (e.g., bbox, sortDirection, endpointUrl) to enable filtering, sorting, or verification.

6. Requirements Fulfillment

This API structure aligns with the System Requirements Document, meeting the following key requirements:

• Configuration Persistence: Ensures user settings persist through the GET /api/config and POST /api/config endpoints.
• Dataset and Event Management: Provides endpoints for listing and accessing specific datasets (collections) and their items.
• Map Layer Management: Allows for flexible map layer selection and toggling, enhancing the user’s data visualization experience.
• Real-Time Progress and Verification: Supports monitoring of data processing via GET /api/fetch-progress/{collectionId} and verifies connectivity with GET /api/verify-internet-connection.

---

This report serves as a complete overview of the API structure, with all endpoints described to support the frontend-backend interaction required for the wildfire visualization platform. Each endpoint is designed to optimize performance, maintain flexibility, and provide a comprehensive user experience.