How to interpret a voyage-risk API response

A voyage-risk response is tempting to flatten into one number and a color. That makes a clean table, but it throws away the parts that explain whether the result changed, what caused it, and how much trust to place in it.

The API returns a decision object. This is how to read it.

Score and risk level

score is the composite route-risk value on a 0 to 100 scale. risk_level maps the number into a stable band for display and workflow rules. Use the numeric score for sorting and change detection. Use the level when a user needs a fast label.

Neither field should make an automatic go or no-go decision. The response is decision-support intelligence, and the right action still depends on cargo, vessel, insurance, customer commitments, and the operator's policy.

The assessment has a timestamp

assessed_at says when the underlying route and intelligence sources were evaluated. Always display it. If you compare assessments, compare records produced with the same methodology_version and keep both timestamps.

A useful product message says elevated, assessed 18 minutes ago or up 9 points since booking. A bare elevated label gives the user no way to judge freshness or movement.

Drivers explain the number

The drivers array is ranked by contribution. Each item identifies a source, a plain-language label and summary, an event count where relevant, and a contribution band. The first two or three drivers usually belong next to the score; the full list can sit in a detail panel.

{
  "source": "jwc",
  "label": "Listed-area exposure",
  "summary": "The computed route intersects a current listed area.",
  "event_count": 1,
  "contribution_band": "high",
  "relative_rank": 1
}

Do not infer hidden model weights from the rank. Rank answers a narrower question: which observed factors contributed most to this assessment?

Confidence is not another risk score

confidence describes data completeness for the assessment. A high-risk route can have high confidence. A low score can have reduced confidence when an expected source is unavailable. Those are different axes.

In the UI, keep confidence visually separate from the risk band. For example:

• Elevated risk, confidence 1.00: the available sources support the assessment.
• Moderate risk, confidence 0.72: the result is usable with a visible data-quality warning.

Your own acceptance threshold should match the workflow. A planning dashboard may show partial data with a warning. An automated exception rule may require all critical sources to be healthy.

Read missing sources and source status together

missing_sources is the concise list of unavailable inputs. source_status gives the per-source state. Store both. They let support staff distinguish a genuinely quiet route from an assessment made while one feed was degraded.

A source issue should never become a green result by omission. If a required source is missing, keep the score visible if your policy allows it, but mark the data state and prevent stronger automated claims.

The route is part of the evidence

The response includes normalized port codes, distance, and route geometry. This matters because maritime exposure follows the sea path, not a country-to-country lookup. Two services between the same countries can use different ports or chokepoints and produce different results.

Plot the geometry when a user needs to inspect why a driver applies. If space is tight, at least show the normalized port pair and distance so the user can catch a location-mapping error.

Keep methodology versions with history

methodology_version identifies the response contract and scoring method. Store it with every observation. If ArcNautical changes a model version later, you can explain whether a movement came from new intelligence, a route change, or a methodology update.

A sensible display hierarchy

On a shipment or lane page, put the risk level, score, assessed time, trend, confidence, and top drivers in the first view. Put the source matrix, full driver list, route geometry, methodology, and disclaimer in the detail view. That gives an operations user a fast read without hiding the audit trail.

You can inspect this exact shape without a key. The public playground computes a real route assessment, does not create a retained customer record, and shows both the formatted result and raw JSON.