API Documentation | Andromeda AI

Global Forecast

Retrieve the entire global risk matrix for a specific forecast date. The API utilizes a secure S3 pre-signed URL workflow to deliver large GeoJSON datasets dynamically over a 60-day forecasting window.

GET https://api.androai.us/risk-forecast?target_date=YYYY-MM-DD

Authentication

Requests must be authenticated using your provisioned API key passed in the headers.

x-api-key: YOUR_API_KEY_HERE
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
target_date	String	Yes	The specific future date to retrieve risk scores for, formatted as `YYYY-MM-DD` (up to T+60 days).

Response Workflow

To accommodate large spatial datasets without hitting API payload limits, the endpoint returns a JSON payload containing a secure, time-limited S3 download URL valid for 1 hour.

{
    "status": "success",
    "target_date": "2026-08-25",
    "download_url": "https://marine-insurance-730460775114-us-east-1-an.s3.amazonaws.com/revision-6/results/2026/08/25/inference_2026-08-25.geojson?AWSAccessKeyId=...",
    "expires_in_seconds": 3600
}

GeoJSON Output Schema

Executing a GET request against the download_url will download a standard GeoJSON FeatureCollection formatted with the CRS84 coordinate reference system. Each feature polygon contains the following properties:

Property	Type	Description
time	String	The date of the forecast (e.g., YYYY-MM-DD).
score_fishing	Float	Calculated risk probability score (0.0 to 1.0) for fishing activity.
score_dark	Float	Calculated risk probability score (0.0 to 1.0) for dark vessel (AIS turned off) activity.
score_ghost	Float	Calculated risk probability score (0.0 to 1.0) for AIS spoofing (ghost) activity.
risk_level	String	Categorical aggregation of risk (e.g., "Low", "Medium", "High").
primary_contributing_factor	String	The most significant environmental or historical factor driving the risk score (e.g., lunar illumination correlation).
secondary_contributing_factor	String	The second leading factor driving the risk score (e.g., Net Primary Production/Chlorophyll density).
tertiary_contributing_factor	String	The third leading factor driving the risk score (e.g., historical fleet density).

Example S3 File Payload

{
  "type": "FeatureCollection",
  "name": "marine_insurance_sample_polygon",
  "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:OGC:1.3:CRS84" } },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "time": "2026-08-12",
        "score_fishing": 0.52,
        "score_dark": 0.0,
        "score_ghost": 0.0,
        "risk_level": "Medium",
        "primary_contributing_factor": "Transit forecasted during period of low lunar illumination, statistically correlating with increased activity.",
        "secondary_contributing_factor": "Sector located in zone of forecasted high Net Primary Production (NPP) or Chlorophyll, indicating prime environmental conditions for fishing fleet aggregation.",
        "tertiary_contributing_factor": "Baseline risk elevated due to historical density of fishing fleet activity in this grid cell."
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [ 21.222623642676179, 76.555020631590878 ],
            [ 21.222623642676179, 76.130851937815592 ],
            [ 19.425993074437137, 76.130851937815592 ],
            [ 19.425993074437137, 76.555020631590878 ],
            [ 21.222623642676179, 76.555020631590878 ]
          ]
        ]
      }
    }
  ]
}

Voyage Risk Report

Submit an array of coordinates (waypoints) and a departure date. The engine will calculate a land-avoiding oceanic route using standard vessel speeds and calculate the exact temporal risk intersecting the vessel path on each operational day.

POST https://api.androai.us/voyage-risk-report

JSON Payload Parameters

Parameter	Type	Required	Description
waypoints	Array[Array[Float]]	Yes	Nested array of minimum two coordinates formatted as `[longitude, latitude]`.
start_date	String	Yes	Estimated departure date formatted as `YYYY-MM-DD`.
email	String	Yes	User email address associated with the API key.

Example Request

curl -X POST "https://api.androai.us/voyage-risk-report" \
     -H "x-api-key: YOUR_API_KEY_HERE" \
     -H "Content-Type: application/json" \
     -d '{
           "waypoints": [[-74.0060, 40.7128], [-0.1276, 51.5072]],
           "start_date": "2026-08-25",
           "email": "underwriter@insurer.com"
         }'

JSON Response Structure

The API returns an array of coordinates representing the fully interpolated path (route_coordinates) alongside an isolated subset of grid cells where critical risk parameters were breached (high_risk_zones).

{
  "route_coordinates": [
    [-74.0060, 40.7128],
    [-72.1001, 42.3314],
    [-0.1276, 51.5072]
  ],
  "high_risk_zones": [
    {
      "voyage_day": 3,
      "date": "2026-08-27",
      "coordinates": {
        "lon": -45.1234,
        "lat": 48.9876
      },
      "compliance_justifications": {
        "risk_level": "High",
        "primary_contributing_factor": "High probability of dense fishing fleet operations projected within coastal Exclusive Economic Zone (EEZ), increasing collision and operational risk."
      }
    }
  ]
}

Claims Analysis Report

Submit a historical vessel track (waypoints) and an incident date. The forensic engine intersects the track against historical SAR, acoustic, and METOC data to identify cells that are statistically significant anomalies (Z-score > 2.0).

POST https://api.androai.us/claims-analysis-report

JSON Payload Parameters

Parameter	Type	Required	Description
waypoints	Array[Array[Float]]	Yes	Nested array of minimum two coordinates formatted as `[longitude, latitude]` representing the actual historical vessel path.
target_date	String	Yes	The date of the incident or claim formatted as `YYYY-MM-DD`.
email	String	Yes	User email address. A detailed PDF forensic report will be dispatched to this address.

Example Request

curl -X POST "https://api.androai.us/claims-analysis-report" \
     -H "x-api-key: YOUR_API_KEY_HERE" \
     -H "Content-Type: application/json" \
     -d '{
           "waypoints": [[-74.0060, 40.7128], [-73.9352, 40.7306], [-73.8701, 40.7380]],
           "target_date": "2026-08-12",
           "email": "claims@insurer.com"
         }'

JSON Response Structure

The API returns the verified coordinate path (route_coordinates) and an array of anomalous intersection points (high_risk_zones). Each zone lists variables whose deviation from the daily mean exceeded an absolute Z-score of 2.0.

{
  "route_coordinates": [
    [-74.0060, 40.7128],
    [-73.9352, 40.7306],
    [-73.8701, 40.7380]
  ],
  "high_risk_zones": [
    {
      "date": "2026-08-12",
      "coordinates": {
        "lat": 40.7306,
        "lon": -73.9352
      },
      "anomalies": [
        {
          "variable": "swh",
          "z_score": 2.85,
          "raw_value": 6.4
        },
        {
          "variable": "residual_ghost",
          "z_score": 2.15,
          "raw_value": 0.88
        }
      ]
    }
  ]
}

Actuarial Methodology: Long-Tail Modeling

In accordance with standard meteorological models, deterministic forecasts physically degrade after the 10 to 14-day Lorenz Limit. To ensure robust, regulatory-compliant underwriting, risk forecasts from Day 11 through Day 60 are modeled using Climatological Reversion.

Rather than carrying forward a static weather anomaly infinitely, the underlying neural network applies an exponential decay function to smoothly revert localized anomalies back to the global or seasonal historical mean:

X_t = (X_t-1 - μ) · e^-λ + μ

Variable Definitions

X_t : Calculated value for the target day.
X_t-1 : Forecasted value from the previous day.
μ : Baseline climatological historical mean.
λ : Environmental decay constant.

Memory Class	Decay (λ)	Variables	Methodology
Long Memory	0.05	Sea Surface Temperature (SST), Ice Coverage, Mixed Layer Depth (MLD), Colored Dissolved Organic Matter (CDOM), Net Primary Production (NPP), NO2, SO2, Aerosol, Dust	Applied to high-thermal mass variables where anomalies persist for weeks, slowly reverting to the seasonal historical mean.
Short Memory	0.30	Chlorophyll-a, Wave Height (SWH), Currents, Surface Salinity, Magnetic Disturbance (Kp-Index)	Applied to highly chaotic variables that rapidly return to the global baseline.
Historical Memory	0.80	Synthetic Aperture Radar (SAR), Acoustic Signatures	Observational decay based on physical transit limits and sensor evasion probabilities.
Deterministic	0.00	Bathymetry, Distance to Shore, Lunar Illumination	Celestial physics and static geography are modeled with 100% certainty through T+60.

Claims Analysis Layers

The Forensic Claims Analysis dashboard utilizes statistical Z-scores (standard deviations from the daily mean) to highlight anomalies. Below is a reference of the available operational, acoustic, and environmental variables.

Anomalies & Densities

Variables	Description
residual_fishing residual_dark residual_ghost	The calculated delta between observed real-world density and forecast. Positive values indicate high anomaly.
density_fishing density_dark density_ghost	The normalized count (0.0 to 1.0) of confirmed vessels in the grid cell for that specific day.

Acoustic & SAR Indicators

Variables	Description
acoustic_loudness	Peak amplitude/decibel level captured by hydrophone networks in the Pacific Northwest (Strait of Juan de Fuca) region, correlated spatially and temporally to the sector using acoustic physics.
acoustic_frequency	The primary Hz frequency of the detected anomaly within the Pacific Northwest monitoring region. Engine and propeller cavitation typically register distinct frequency ranges.
sar_memory_score	A rolling confidence score denoting the recent presence of a physical vessel detected via Synthetic Aperture Radar (SAR) without a corresponding AIS transmission.

Oceanographic & Atmospheric

Variables	Description
swh sst sss mld u_current v_current depth ice_coverage	Physical oceanography variables denoting operational constraints and structural risk markers (e.g., Significant Wave Height, Sea Surface Temperature, Ocean Currents, Ice Coverage).
chl_a cdom npp	Biogeochemical indicators correlated with fishing operations and marine biomass density (Chlorophyll-a, Colored Dissolved Organic Matter, Net Primary Production).
no2 so2 aod dust moonlight_intensity kp_index	Atmospheric emissions, celestial influence, and systemic interference impacting evasion operations or GPS/AIS reliability.