Actuaries are not GIS analysts. This is not a criticism — it is a design constraint that geospatial data providers consistently fail to account for. A data product that requires ESRI expertise, coordinate reference system knowledge, or familiarity with raster band interpretation will never be adopted by the underwriting teams that could benefit from it most. If the output is a GeoTIFF, you've already lost 90% of your potential insurance buyer base. The entire purpose of a geospatial data API for insurance is to remove geospatial complexity from the consumption path.
What Insurance Rating Engines Actually Consume
Before designing an API for insurance integration, it helps to understand the data environment it needs to integrate into. A typical crop insurance rating workflow runs on some combination of: a commercial rating platform (handling actuarial factor retrieval, premium calculation, policy record management), internal actuarial databases (county loss-cost factors, APH yield records, rate adjustment schedules), and the RMA's Actuarial Data Master (ADM) feed that provides county actuarial factors and approved yield data.
These systems exchange structured data — primarily relational database records with typed fields: county FIPS, crop code, practice code, coverage level, APH yield, loss-cost factor. They are not built to ingest spatial objects. An API integration that returns a GeoJSON FeatureCollection requires the consuming system to extract the properties dictionary, parse numeric fields, and discard the geometry — work that has to be custom-coded for each integration unless the API provides a structured, non-spatial output format as the primary delivery mode.
The right design is to treat the GeoJSON geometry as an optional attribute of the response, not the primary payload structure. A policy field query should return a JSON object with clearly typed fields: county FIPS, field identifier, crop type, NDVI at last observation date, cumulative NDVI anomaly, P50 yield estimate, P10/P90 bounds, observation timestamp, and cloud cover flag. The GeoJSON polygon for the field boundary should be an optional include parameter — useful for display in a mapping application, not required for premium calculation.
Authentication and Rate Limits: The Enterprise Insurance Context
Crop insurance policy applications generate bursts of data requests — a large portfolio review might trigger several hundred field-level yield queries in rapid succession during a loss adjustment event or a pre-season portfolio audit. The API authentication and rate-limit architecture needs to be designed for this access pattern, not for a user who makes one or two requests per session.
API key authentication with IP allowlisting is the standard for enterprise insurance integrations where queries are made from server-to-server in a rating workflow, not from individual actuary browser sessions. Rate limits should be set at the workflow level — requests per hour for a given API key — not at individual IP levels, because enterprise rating workflows may distribute API calls across multiple application servers behind a NAT. A limit of 500 requests per minute is reasonable for enterprise tier customers running portfolio-scale analysis.
The insurance context also requires deterministic responses: a field ID queried at the same timestamp should return the same yield estimate regardless of when the query is made, until the next model update. Race conditions in loss adjustment workflows — where two adjusters query the same field 30 minutes apart and get different yield estimates because a model update ran between queries — create compliance and documentation problems. Explicit model versioning with a version parameter in the request and a model_run_timestamp in the response solves this cleanly.
The Field ID Problem: Bridging to Existing Policy Records
The hardest integration challenge for most insurance teams is not the API protocol — it's connecting the geospatial field identifier to the existing policy record structure. Insurance policies are keyed to CLU (Common Land Unit) numbers from FSA records, or in some cases to county parcel APN numbers. Satellite-derived field polygons have their own identifier system.
An API designed for insurance integration needs to support lookup by existing identifiers that insurers already use. Three lookup modes are essential:
- Geometry lookup: POST a field polygon GeoJSON, receive the Terraxiq field ID and yield attributes for the matching or overlapping field. This handles the initial enrollment of a new portfolio.
- FSA CLU lookup: Query by FSA state code + county code + farm number + tract number + field number (the standard CLU identifier components). Terraxiq cross-references the CLU to our field polygon layer and returns the matching yield data.
- County-level aggregate: Query by county FIPS and crop type, receive the county-level P50/P10/P90 yield distribution — equivalent to replacing the NASS county average with a satellite-derived version, no field polygon matching required.
The county-level aggregate endpoint is underappreciated. For underwriters who are not yet ready to integrate at the field polygon level, county-level satellite yield distributions provide a materially better input to loss-cost factor adjustments than waiting for NASS surveys — and require zero change to the existing policy record matching infrastructure.
Error Handling and Data Availability Communication
Insurance systems have zero tolerance for silent data failures. A premium calculation that silently uses a stale or missing NDVI estimate because the API returned null without a clear error signal creates a compliance exposure. The API response schema needs to include explicit data availability signals:
{
"field_id": "txq_field_1872634",
"county_fips": "19015",
"crop": "corn",
"observation_date": "2024-07-18",
"ndvi_p50": 0.71,
"yield_p50_bushels": 174.2,
"yield_p10_bushels": 154.8,
"yield_p90_bushels": 188.6,
"data_quality": "temporal_composite",
"last_clear_obs_days_ago": 9,
"confidence": "medium",
"model_version": "v2024.2",
"model_run_timestamp": "2024-07-20T06:14:22Z"
}The data_quality field distinguishes between a direct clear-sky observation and a temporally composited estimate. The last_clear_obs_days_ago field tells the consuming system exactly how stale the optical observation is. The confidence field (low/medium/high) provides a single-field summary that downstream systems can use to flag estimates for actuary review without parsing the full quality metadata. These fields should be required, not optional — omitting them shifts the burden of data quality assessment onto the consuming team, which is exactly the GIS expertise problem we set out to solve.
Documentation as a First-Class Product
We're not saying a well-designed API eliminates the need for actuary education about satellite yield data. The most important GIS-literacy work we do with insurance customers happens in the first few months of integration — explaining what cumulative NDVI anomaly means, walking through how P10/P50/P90 bounds were empirically calibrated, showing the LOYO-CV validation metrics that back the confidence intervals. That education is necessary and ongoing.
What a well-designed API eliminates is the barrier to getting started. Documentation that shows a working cURL example, a Python code snippet that calls the county-level endpoint and returns a JSON object, and a clear explanation of what each response field means — calibrated for an actuary audience, not a GIS audience — is a first-class product deliverable, not an afterthought. The API documentation is the most read artifact of any data product adoption. It deserves the same design attention as the underlying model.