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.

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.

3. API Endpoints

3.1 Configuration Management

• GET /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 /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 Management

• GET /datasets

  • Purpose: Lists available datasets with metadata (e.g., dataset name, description).
  • Response: Returns metadata for each dataset.
  • Use Case: Enables the user to browse and select datasets without loading full data details.

• GET /datasets/{dataset_id}

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

3.3 Data Visualization and Time Navigation

• GET /datasets/{dataset_id}/events

  • Purpose: Lists events within the selected dataset.
  • Response: Returns metadata for each event (e.g., timestamps, event descriptions).
  • Use Case: Supports time navigation in the frontend, allowing users to view available events for selected datasets.

• GET /datasets/{dataset_id}/events/{event_id}

  • Purpose: Retrieve data for a specific event within a dataset.
  • Use Case: Used for visualizing a particular time point within a dataset on the map.

3.4 Map Layer Management

• GET /layers/{dataset_id}/{event_id}
  • Purpose: Fetches specific map layer data for a dataset event.
  • Query Parameters: layer_type specifies the type of layer (e.g., "fire perimeter").
  • Use Case: Enables the user to toggle between different layers (e.g., fire perimeters, satellite imagery) for enhanced visualization.

3.5 Progress and Download Status

• GET /progress/{dataset_id}
  • Purpose: Provides the current status of data download or processing.
  • Response: JSON with percentage_complete.
  • Use Case: Displays a progress bar in the frontend during data download or processing.

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

• ID Precision: Each dataset and event has a unique identifier. Precision is critical because dataset_id helps select the dataset, while event_id allows users to choose specific time points within a dataset for visualization.
• Layer Types: The layer_type query parameter allows users to choose different map layers (e.g., "fire perimeter"), supporting customizable visualization options.

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 /config and POST /config endpoints.
• Dataset and Event Management: Provides endpoints for listing and accessing specific datasets and events.
• Map Layer Management: Allows for flexible map layer selection and toggling, enhancing the user’s data visualization experience.
• Real-Time Progress: Displays progress during data download or processing via the GET /progress/{dataset_id} endpoint.

---

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.