Pathfinder safety router (hex + route)

The Pathfinder layer of the safety router exposes H3-based risk scoring, viewport bulk hex queries, breakdowns, safest-route computation, and precinct GeoJSON. Use this page as the contract for field names and limits. Create keys and browser Origin allowlists in Path (wolf-path-portal); call the HTTP API with X-API-Key.

End-to-end journeys

1. Hex map colouring (batch scores)

1. GET /health — optional connectivity check.
2. GET /hexes/config — read data.colors (palette) and data.resolution (H3 resolution, e.g. 8). Cache for the session.
3. POST /hexes/score — body includes intent, activeCodes, modifiers, hexIds (H3 cell strings).

Response: JSON array (order matches hexIds). Each row includes h3 (or h), safetyScore (0–100), colorIndex (0–16 for palette lookup).

Client mapping: fillColor = colors[colorIndex]; if you show legend bands 1–17, map display label from server colorIndex consistently (see Colour bands).

Bulk viewport dots: GET /hexes/all with query west, south, east, north — slim items use h, ci, la, ln, optional ss, etc. See Slim hex object keys.

1b. Lat/lng → hex scores (POST /hexes/lookup)

Use when you have a coordinate but no H3 library: the server converts lat/lng to resolution 8 and returns scores for a GridDisk around that cell.

• Body: lat, lng (required); optional ring (default 0), detail (default false), resolution (only 8 accepted).
• ring: H3 distance k on the grid (allowed 0–41). Number of cells returned = 3k² + 3k + 1 (e.g. k=5 → 91, k=41 → 5167). Values outside 0–41 return 400.
• detail: true: includes per-hex breakdown objects; responses can become very large at high ring.

2. Single-hex drill-down

1. GET /hexes/breakdown?h3={id}&intent={intent} — one cell per request.

Response: crimeTypes[] (per-type rows), aggregates such as normalizedRisk, safetyScore, colorIndex, hasData, modifier fields as applicable.

Use this for analytics or drill-down UIs. For colouring many cells on a map, prefer POST /hexes/score.

3. Safest route + corridor

1. GET /route/config — tier colours for corridor styling when available.
2. POST /route — origin / destination (lat, lng), method, intent, toggles, snapToRoads, alternatives, etc.

Response: best.geometry (path on the road network), best.hexPathWithTiers when present, top-level hexPath, metrics, segment stats as returned.

Optional: POST /evaluate with a LineString geometry; POST /evaluate-hex-path with hexPath array to score an ordered corridor.

4. Precincts

1. GET /health — may include precinct-related counts when loaded.
2. GET /precincts/status — cache / availability.
3. GET /precincts/all-scores — JSON scores where exposed.
4. GET /precincts — GeoJSON FeatureCollection (often gzip); can be large — paginate or filter client-side if you subset features for performance.

Authentication and base URL

Request limits

Note: Admin tools (e.g. internal Pathfinder API Lab) may apply UI-only caps (e.g. fewer map dots for performance). Those are not router limits.

Endpoint reference (quick lookup)

Slim hex object keys (GET /hexes/all, warm-cache and filtered paths)

These fields appear on “slim” items when the API returns a compact list of scored cells:

ci vs ss: ci drives discrete colour bands (0–16, or N/A at -1). ss supports intent-specific continuous or per-intent safety values for colouring and labels when you need more than a single band.

Route response (POST /route)

When the corridor algorithm runs, responses should include:

• best.geometry — LineString (or compatible) geometry for the recommended path on the road network.
• hexPath — Ordered list of H3 cells along the corridor (when computed).
• best.hexPathWithTiers — Cells paired with tier values for corridor colouring (when computed). Same-cell shortcuts should still populate tier/path metadata when the backend can derive them.

UX expectation: If both road geometry and hex path data exist, clients should draw the line and the hex corridor (not a line-only “colour strip” without cells). Line-only fallback is acceptable when hex path fields are absent.

Colour bands and legend

• Server colorIndex / ci is 0–16 inclusive on the graph; breakdown payloads may use -1 for “no data” (writeHexBreakdownNoData).
• Document whether your app shows display labels 1–17 mapped from 0–16, or 1–16 plus a separate N/A for -1 — pick one convention and keep it consistent in the legend.