API Documentation

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
date / 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).

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"
         }'

Claims Analysis Report

Submit a historical vessel track (waypoints) and an incident date. The forensic engine intersects the track against historical SAR, acoustic, METOC, and authoritative NGA NAVAREA & GDELT maritime event data to identify cells with statistically significant anomalies (Z-score > 2.0) and verify Force Majeure, GNSS jamming, or war-risk claims.

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.

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-10-25",
      "coordinates": {
        "lat": 25.5120,
        "lon": 56.2410
      },
      "anomalies": [
        {
          "variable": "event_severity_score",
          "z_score": 3.42,
          "raw_value": 0.90
        },
        {
          "variable": "residual_ghost",
          "z_score": 2.45,
          "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^-λ + μ

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) and authoritative government hazard bulletins to highlight anomalies. Below is a reference of the available operational, navigational hazard, 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.

Navigational & Geopolitical Hazard Indicators (NGA MSI & GDELT)

Variables	Description
event_severity_score	Decayed severity score (`0.0–0.95`, plus spatial `event_severity_score_z_score`) of active U.S. NGA NAVAREA broadcast warnings or geocoded GDELT CAMEO maritime incidents inside the grid cell on the incident date.
gnss_jamming_reported kinetic_or_piracy_hazard	Binary corroboration flags (`0` or `1`) indicating whether official NGA NAVAREA electronic warfare / GPS spoofing warnings or military/kinetic/piracy hazards were active in the cell—allowing claims adjusters to cross-check vessel "navigation failure" or war-risk deviation claims against both space weather (`kp_index`) and government bulletins.
primary_event_category forensic_event_summary	Deterministic hazard classification (`GNSS_JAMMING_SPOOFING`, `MILITARY_KINETIC_HAZARD`, `PIRACY_HOSTILE_ACT`, `NAVIGATION_BOTTLENECK`, `PORT_LABOR_DISPUTE`, or `NONE`) and the verbatim NGA NAVAREA message ID or GDELT CAMEO citation string for inclusion in claims settlement or denial documentation.

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.

Global Forecast

Authentication

Query Parameters

Response Workflow

GeoJSON Output Schema

Voyage Risk Report

JSON Payload Parameters

Example Request

Claims Analysis Report

JSON Payload Parameters

JSON Response Structure

Actuarial Methodology: Long-Tail Modeling

Claims Analysis Layers

Anomalies & Densities

Navigational & Geopolitical Hazard Indicators (NGA MSI & GDELT)

Acoustic & SAR Indicators

Oceanographic & Atmospheric

Submit Support Ticket