Route summary

Route summary is the route-specific drilldown surface. Use it after destination discovery or when the caller already knows which route they want to inspect.

Parameters

Path and query parameters are documented together so the request surface stays easy to scan.

route

Path Required

string

Canonical runtime route value such as SR-18. Unknown or unsupported canonical route values return 404 ROUTE_NOT_FOUND.

jurisdiction

Query Optional

string

Optional for the active Big Bear MVP. If omitted, the effective jurisdiction defaults to US-CA. If provided, it must canonicalize to US-CA.

Name	Location	Required	Type	Description
route	Path	Yes	string	Canonical runtime route value such as SR-18. Unknown or unsupported canonical route values return 404 ROUTE_NOT_FOUND.
jurisdiction	Query	No	string	Optional for the active Big Bear MVP. If omitted, the effective jurisdiction defaults to US-CA. If provided, it must canonicalize to US-CA.

Example request

Use the same endpoint across all three snippets. The tabs switch only the client syntax.

cURL

curl -sS "https://api-staging.mountainswitch.co/v1/routes/SR-18/summary" \
  -H "Accept: application/json"

TypeScript

const response = await fetch(
  "https://api-staging.mountainswitch.co/v1/routes/SR-18/summary",
  {
    headers: {
      Accept: "application/json",
    },
  },
);

const payload = await response.json();

Python

import requests

response = requests.get(
    "https://api-staging.mountainswitch.co/v1/routes/SR-18/summary",
    headers={"Accept": "application/json"},
)

payload = response.json()

Example response

The example response shows the documented JSON envelope with endpoint data in data and request metadata in _meta.

200 OK application/json

{
  "data": {
    "route": "SR-18",
    "jurisdictions_covered": ["US-CA"],
    "worst_status": "restricted",
    "worst_chain_control_severity": 3,
    "worst_chain_control_code": "chains_awd_exempt",
    "worst_chain_control_raw": "R-2",
    "active_restrictions": 14,
    "total_segments": 32,
    "summary": "Chain or traction restrictions are reported on SR-18. Chains or traction devices required. AWD with snow tires exempt.",
    "sections": [
      {
        "alert_type": "chain_control",
        "source": "ca-chain-controls",
        "segments": [
          {
            "id": "ca-chain-controls:2012",
            "route": "SR-18",
            "direction": "N",
            "segment_description": "Lower Waterman Cyn to Vista Point",
            "overall_status": "restricted",
            "chain_control_severity": 3,
            "chain_control_code": "chains_awd_exempt",
            "chain_control_raw": "R-2",
            "status_description": "Chains or traction devices required. AWD with snow tires exempt.",
            "start_lat": 34.2101,
            "start_lon": -117.2847,
            "end_lat": null,
            "end_lon": null,
            "valid_until": null
          }
        ]
      },
      {
        "alert_type": "lane_closure",
        "source": "ca-lane-closures",
        "segments": [
          {
            "id": "ca-lane-closures:LC12345-LOG001-20260319-SR-18",
            "route": "SR-18",
            "direction": "E",
            "segment_description": "Rim of the World Dr to SR-138",
            "overall_status": "restricted",
            "chain_control_severity": 0,
            "chain_control_code": "none",
            "chain_control_raw": null,
            "status_description": "Curb/Gutter/Sidewalk Work on SR-18 East. 1 of 2 lanes closed. Estimated delay: 15 min.",
            "start_lat": 34.243,
            "start_lon": -117.189,
            "end_lat": 34.255,
            "end_lon": -117.175,
            "valid_until": "2026-03-19T22:01:00Z"
          }
        ]
      }
    ]
  },
  "_meta": {
    "sources": [
      {
        "source": "ca-chain-controls",
        "freshness": "healthy",
        "live_eligible": true,
        "covers_query": true,
        "source_updated_at": "2026-03-19T12:43:00Z",
        "fetched_at": "2026-03-19T12:45:00Z"
      },
      {
        "source": "ca-lane-closures",
        "freshness": "healthy",
        "live_eligible": true,
        "covers_query": true,
        "source_updated_at": "2026-03-19T12:40:00Z",
        "fetched_at": "2026-03-19T12:45:00Z"
      }
    ],
    "query_coverage": "full",
    "request_id": "req_route_summary_docs",
    "response_generated_at": "2026-03-19T12:47:30Z",
    "pagination": null
  }
}

Response fields

This reference stays flat on purpose so the documented fields remain easy to scan.

route: string; Canonical route value for the requested summary.
jurisdictions_covered: string[]; Resolved jurisdiction coverage for the request. In the Big Bear MVP this is always ["US-CA"].
worst_status: string | null; Highest-priority overall_status across active eligible segments. When query_coverage is full and active_restrictions is 0, this remains open rather than null.
worst_chain_control_severity: number | null; Highest-severity eligible chain-control value participating in the summary.
worst_chain_control_code: string | null; Canonical chain-control code from the highest-priority eligible chain-control segment.
worst_chain_control_raw: string | null; Raw chain-control code from the same winning eligible chain-control segment.
active_restrictions: number; Count of all active non-open conditions across the route summary scope.
total_segments: number; Count of all segments that participated in the summary aggregation.
summary: string; Deterministic summary text derived from the structured route-summary fields.
sections: Array<object>; Per-source and per-alert-type groups ordered by severity and canonical tiebreak rules.
sections[].alert_type: string; Alert category such as chain_control or lane_closure.
sections[].source: string; Adapter source identifier such as ca-chain-controls or ca-lane-closures.
sections[].segments[].direction: string | null; Normalized route direction for the segment when available.
sections[].segments[].segment_description: string; Human-readable segment scope used for the route progression listing.
sections[].segments[].overall_status: string; Segment-level overall status, such as advisory, restricted, or closed.
sections[].segments[].chain_control_severity: number; Canonical chain-control severity for the segment row.
sections[].segments[].chain_control_code: string; Canonical chain-control code for the segment row.
sections[].segments[].chain_control_raw: string | null; Raw upstream chain-control code for the segment row when present.
sections[].segments[].status_description: string; Human-readable status line used by the summary and drilldown surfaces.
sections[].segments[].start_lat: number; Segment start latitude used in the summary payload.
sections[].segments[].start_lon: number; Segment start longitude used in the summary payload.
sections[].segments[].end_lat: number | null; Segment end latitude, or null for point-like rows such as chain controls.
sections[].segments[].end_lon: number | null; Segment end longitude, or null for point-like rows such as chain controls.
sections[].segments[].valid_until: string | null; Additive expected end time when the underlying row provides one.
_meta.sources: Array<object>; Current adapter coverage records for the route scope.
_meta.query_coverage: "full" | "partial" | "none"; Coverage signal for the route summary request.
_meta.request_id: string; Request identifier for debugging and support workflows.
_meta.response_generated_at: string; ISO timestamp describing when the API assembled the response.
_meta.pagination: null; Always null because route summary is a non-paginated data endpoint.

Errors

These rows keep the repo-wide rate-limit and infrastructure behavior visible without inventing endpoint-specific transport semantics.

Status	Code	When it happens
400	INVALID_PARAMETER	The request contains an unsupported jurisdiction value, a malformed query parameter, or a repeated query parameter.
400	INVALID_JURISDICTION	The provided jurisdiction value does not canonicalize to a known jurisdiction code.
404	ROUTE_NOT_FOUND	The canonical route value is unknown or unsupported for the resolved jurisdiction.
429	RATE_LIMIT_EXCEEDED	The caller exceeded the shared API rate limit.
503	SERVICE_UNAVAILABLE	D1 or another critical dependency is unavailable.

Notes

These notes capture the contract edges that matter most for consumers of the endpoint.

Route summary defaults omitted jurisdiction to US-CA

For the active Big Bear MVP, GET /v1/routes/:route/summary uses US-CA when jurisdiction is omitted. If a caller provides a different known jurisdiction, the request fails with INVALID_PARAMETER.

Check query_coverage before trusting the summary

The structured route summary can still be returned with partial coverage. Read _meta.query_coverage and _meta.sources before treating the summary text as a fully verified live answer.

Only full coverage summaries are cacheable

This endpoint follows the Big Bear full-only cache posture. The API caches responses only when _meta.query_coverage is full. Partial and none responses are no-store.