# Field Imagery API

*/Software/Field_Imagery_API*

## Solution Overview

Field Imagery API accepts a GeoJSON polygon and a time range, returning normalized optical, Synthetic Aperture Radar (SAR), and multispectral imagery for that specific land boundary. It handles backend connections to disparate commercial satellite constellations and drone registries, clipping raw raster files to the requested coordinates. The output is a REST payload containing high-resolution image URLs, cloud-cover metadata, and pre-calculated vegetation indices formatted for machine processing.

Autonomous agronomy agents and construction-monitoring platforms consume this endpoint to track physical site changes without maintaining custom ingestion pipelines. It standardizes authentication, rate-limiting, and spatial reprojection across vendors, removing the requirement to write distinct adapters for Sentinel-2, Planet, or localized drone uploads. The buyer queries one endpoint and receives a temporal image stack aligned pixel-to-pixel, regardless of the original sensor's orbital path or raw file format.

As a Headless SaaS primitive, this system sits above raw earth-observation data lakes and below the computer vision models that extract business logic. It supplies the raw visual grounding that Services-as-Software platforms use to calculate crop yield or verify concrete pours. Because the API guarantees structural formatting but cannot eliminate atmospheric interference, downstream agents often route heavily obstructed captures to a human site manager to manually adjust the requested capture window or dispatch a sub-cloud drone.

## Headless Saas Data Model

**Entities**:
- Name: CaptureRequest · Description: A requested geographic boundary and time range for imagery extraction
- Name: Workspace · Description: Tenant account managing authentication and quotas for API consumers
- Name: ImageLayer · Description: A single normalized imagery capture within the temporal stack
- Name: SensorSource · Description: Configuration and metadata for a specific earth-observation sensor or constellation
- Name: CalculatedIndex · Description: Pre-calculated vegetation or physical index derived from an image layer
**Relations**:
- To: CaptureRequest · From: Workspace · Label: initiates · Cardinality: one-to-many
- To: ImageLayer · From: CaptureRequest · Label: contains temporal frames · Cardinality: one-to-many
- To: ImageLayer · From: SensorSource · Label: captures · Cardinality: one-to-many
- To: CalculatedIndex · From: ImageLayer · Label: computes · Cardinality: one-to-many
**Tenant Anchor**: Workspace
**Primary Resource**: CaptureRequest

## Api Definition

**Protocols**:
- REST
- SDK
- MCP
- Webhooks
**Consumed By**:
- [Agronomy Yield Agent](/Agents/Agronomy_Yield_Agent)
- [Construction Progress Agent](/Agents/Construction_Progress_Agent)
- [Site Verification Agent](/Agents/Site_Verification_Agent)
**Integrations**:
- [Planet](/Products/Planet)
- [Sentinel-2](/Products/Sentinel-2)
- [Amazon S3](/Products/Amazon_S3)
**Consumption Model**: An agent posts a CaptureRequest with a GeoJSON boundary via REST, then processes the resulting ImageLayer stack once a webhook confirms the spatial reprojection is complete.
**Workflow Wrappers**:
- Name: Extract Normalized Stack · Wraps: Queries satellite constellations, clips raster files to a GeoJSON boundary, and aligns pixels.
- Name: Compute Site Indices · Wraps: Processes raw multispectral imagery to calculate and attach vegetation and physical index rasters.

## Api Function Cascade

**Ai Role**: AI operates as a headless, straight-through component within the extraction pipeline, utilizing generative vision models to automatically mask atmospheric anomalies without human intervention, while deterministic code handles spatial reprojection and index calculations.
**Cascade**:
- Kind: Code · Note: Receives GeoJSON boundary via REST API · Step: Ingest Boundary Request · Verb: ingest · Realizes: Process Geospatial Data Request · Oversight: none
- Kind: Code · Note: Fetches raw multispectral rasters from Planet and Sentinel-2 · Step: Query Constellation APIs · Verb: retrieve · Realizes: Retrieve Satellite Imagery · Oversight: none
- Kind: Code · Note: Performs spatial reprojection and clips to requested geometry · Step: Align And Clip Rasters · Verb: transform · Realizes: Process Geospatial Imagery · Oversight: none
- Kind: Generative · Note: Computer vision model masks clouds, haze, and shadows · Step: Segment Atmospheric Artifacts · Verb: extract · Realizes: Filter Image Artifacts · Oversight: none
- Kind: Code · Note: Computes vegetation and physical index rasters from multispectral bands · Step: Calculate Site Indices · Verb: calculate · Realizes: Analyze Spectral Signatures · Oversight: none
- Kind: Code · Note: Delivers the normalized stack to Amazon S3 and notifies the consuming agent · Step: Emit Completion Webhook · Verb: emit · Realizes: Dispatch Webhook Notification · Oversight: none
**Optimizes**:
- [Processing Latency](/Metrics/Processing_Latency)
- [Raster Alignment Accuracy](/Metrics/Raster_Alignment_Accuracy)
- [Cloud Masking Precision](/Metrics/Cloud_Masking_Precision)
- [Spatial Resolution Yield](/Metrics/Spatial_Resolution_Yield)

## Headless Saas Representative Offer

**Warranty**: Maintains a 99.9% API uptime SLA and guarantees accurate spatial reprojection, providing usage credits if image retrieval or processing fails.
**Price Band**: ~$0.10 to $1.50 per square kilometer of processed imagery, depending on spatial resolution and the selected satellite constellation.
**Pricing Kind**: UsageMeter
**Deliverables**:
- Clipped multispectral raster files aligned to requested GeoJSON boundaries
- Computed vegetation and physical site index layers
- Webhook notifications for processing completion
**Delivery Mode**: Self-serve, API-metered access provisions instantly, allowing agents to immediately post capture requests and consume raster outputs.
**Business Function**: ProvideService
**Agent Checkout Support**:
- agentic-commerce-protocol
- stored-credential

## Headless Saas Crud Surface

**Auth Model**: API Key
**Endpoints**:
- GET /capture-requests — list all capture requests
- GET /capture-requests/{id} — fetch a single capture request
- POST /capture-requests — submit a new capture request
- PATCH /capture-requests/{id} — update a capture request
- GET /workspaces — list all workspaces
- GET /workspaces/{id} — fetch a workspace
- POST /workspaces — create a new workspace
- PATCH /workspaces/{id} — update a workspace
- GET /capture-requests/{id}/image-layers — list image layers for a capture request
- GET /image-layers/{id} — fetch a specific image layer
- POST /capture-requests/{id}/image-layers — ingest a normalized imagery capture
- PATCH /image-layers/{id} — update image layer details
- GET /sensor-sources — list sensor sources
- GET /sensor-sources/{id} — fetch a sensor source
- POST /sensor-sources — configure a new sensor source
- PATCH /sensor-sources/{id} — update a sensor source
- GET /image-layers/{id}/calculated-indexes — list calculated indexes for an image layer
- GET /calculated-indexes/{id} — fetch a specific calculated index
- POST /image-layers/{id}/calculated-indexes — store a new calculated index
- PATCH /calculated-indexes/{id} — update a calculated index
**Multitenancy**: Row-level isolation
**Webhook Events**:
- capture_request.completed
- capture_request.failed
- image_layer.ingested
- calculated_index.computed

## Headless Saas Erd

```mermaid
erDiagram
    Workspace {
        UUID id PK "tenant key"
        VARCHAR name
        BOOLEAN isActive
    }
    CaptureRequest {
        UUID id PK
        UUID workspaceId FK
        JSONB geoJsonBoundary
        TIMESTAMP startDate
        TIMESTAMP endDate
        VARCHAR status
    }
    ImageLayer {
        UUID id PK
        UUID captureRequestId FK
        UUID sensorSourceId FK
        TIMESTAMP captureTime
        DECIMAL cloudCoverPercent
        VARCHAR clippedRasterUrl
    }
    SensorSource {
        UUID id PK
        VARCHAR name
        VARCHAR sensorCategory
        VARCHAR provider
        DECIMAL resolutionMeters
    }
    CalculatedIndex {
        UUID id PK
        UUID imageLayerId FK
        VARCHAR indexType
        VARCHAR rasterUrl
        DECIMAL averageValue
    }

    Workspace ||--o{ CaptureRequest : "initiates"
    CaptureRequest ||--o{ ImageLayer : "contains temporal frames"
    SensorSource ||--o{ ImageLayer : "captures"
    ImageLayer ||--o{ CalculatedIndex : "computes"
```

## Neighborhood

### Composed into

- [Uglydamage](/Startups/Uglydamage) — composes · Startups

### Optimizes

- [Spatial Resolution Yield](/Metrics/Spatial_Resolution_Yield) — optimizes · Metrics
- [Cloud Masking Precision](/Metrics/Cloud_Masking_Precision) — optimizes · Metrics
- [Processing Latency](/Metrics/Processing_Latency) — optimizes · Metrics
- [Raster Alignment Accuracy](/Metrics/Raster_Alignment_Accuracy) — optimizes · Metrics

### What it uses

- [Sentinel-2](/Products/Sentinel-2) — uses · Products
- [Amazon S3](/Software/Amazon_S3) — uses · Software
- [Planet](/Products/Planet) — uses · Products

### Who consumes this

- [Agronomy Yield Agent](/Agents/Agronomy_Yield_Agent) — consumed by · Agents
- [Construction Progress Agent](/Agents/Construction_Progress_Agent) — consumed by · Agents
- [Site Verification Agent](/Agents/Site_Verification_Agent) — consumed by · Agents

### Similar Software

- [Crop Yield Prediction](/Software/Crop_Yield_Prediction) — similar · Software
- [Damage Detection Vision API](/Software/Damage_Detection_Vision_API) — similar · Software
- [Open Banking APIs](/Resources/Client_financial_data/Software/Open_Banking_APIs) — similar · Software
- [Real-Time Tracking API](/Software/Real-Time_Tracking_API) — similar · Software
- [Contract Intelligence API](/Software/Contract_Intelligence_API) — similar · Software

### Similar Agents

- [Crop Yield Forecasting Agent](/Agents/Crop_Yield_Forecasting_Agent) — similar · Agents
- [Photographic Audit API](/Agents/Photographic_Audit_API) — similar · Agents
- [Agnostic Ingestion API](/Agents/Agnostic_Ingestion_API) — similar · Agents
- [Ag-Risk Assessment Agent](/Agents/Ag-Risk_Assessment_Agent) — similar · Agents
- [Gateway Ingestion API](/Agents/Gateway_Ingestion_API) — similar · Agents
- [Declarative Provisioning API](/Agents/Declarative_Provisioning_API) — similar · Agents

### Similar Partners

- [Agronomic software vendors](/Partners/Agronomic_software_vendors) — similar · Partners
- [Geospatial data providers](/Partners/Geospatial_data_providers) — similar · Partners
- [GIS software vendors](/Partners/GIS_software_vendors) — similar · Partners

### Similar Startups

- [Agrobase](/Startups/Agrobase) — similar · Startups
- [Aggave](/Startups/Aggave) — similar · Startups

### Similar Resources

- [Agronomic field data](/Resources/Agronomic_field_data) — similar · Resources

### Similar Customers

- [Local crop farmers](/Customers/Local_crop_farmers) — similar · Customers

### Similar Markets

- [Commodity Precision Ag Platforms](/Markets/Commodity_Precision_Ag_Platforms) — similar · Markets