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 California route set. If omitted, the effective jurisdiction defaults to US-CA. If provided, it must canonicalize to US-CA.

destination

Query Optional

string

Optional canonical destination slug for additive route-row scoping. When supplied, it must be a supported destination on the requested route.

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 California route set. If omitted, the effective jurisdiction defaults to US-CA. If provided, it must canonicalize to US-CA.
destination	Query	No	string	Optional canonical destination slug for additive route-row scoping. When supplied, it must be a supported destination on the requested route.

Example request

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

cURL

curl -sS "https://api.mountainswitch.co/v1/routes/SR-18/summary?destination=big-bear" \
  -H "Accept: application/json"

TypeScript

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

const payload = await response.json();

Python

import requests

response = requests.get(
    "https://api.mountainswitch.co/v1/routes/SR-18/summary?destination=big-bear",
    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"],
    "scoped_destination": "big-bear",
    "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 controls and lane restrictions are reported on SR-18.",
    "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,
            "type_of_closure": null,
            "type_of_work": null,
            "lanes_closed": null,
            "total_existing_lanes": null,
            "estimated_delay_minutes": null,
            "valid_until": null,
            "destination_scope": "destination_approach"
          }
        ]
      },
      {
        "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,
            "type_of_closure": "Lane",
            "type_of_work": "Curb/Gutter/Sidewalk Work",
            "lanes_closed": 1,
            "total_existing_lanes": 2,
            "estimated_delay_minutes": 15,
            "valid_until": "2026-03-19T22:01:00Z",
            "destination_scope": "outside_destination_approach"
          }
        ]
      }
    ]
  },
  "_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 active California route set this is currently always ["US-CA"].
scoped_destination: string | null; Echo of the requested destination slug when the caller supplies destination. Null on full-route responses with no destination context.
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[].type_of_closure: string | null; Lane-closure mechanism for non-open lane-closure rows; null on chain-control rows and open lane-closure rows.
sections[].segments[].type_of_work: string | null; Lane-closure work category for non-open lane-closure rows; null on chain-control rows and open lane-closure rows.
sections[].segments[].lanes_closed: number | null; Reported closed lane count for non-open lane-closure rows when available.
sections[].segments[].total_existing_lanes: number | null; Reported total lane count for non-open lane-closure rows when available.
sections[].segments[].estimated_delay_minutes: number | null; Reported delay in minutes for non-open lane-closure rows when available.
sections[].segments[].valid_until: string | null; Additive expected end time when the underlying row provides one.
sections[].segments[].destination_scope: "destination_approach" | "outside_destination_approach" | "unscoped" | null; Additive destination-relative scope for the segment. Null when destination is omitted; unscoped when the route-level evidence cannot prove approach vs outside.
_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, a repeated query parameter, or a destination that is not valid for the requested route.
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.
404	DESTINATION_NOT_FOUND	The provided destination slug is not supported.
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 California route set, 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 stale-but-usable or partial coverage. Read _meta.query_coverage, _meta.sources[].freshness, and _meta.sources[].live_eligible before treating the summary text as a fully verified live answer.

Destination scoping is additive, not a different endpoint

When destination is supplied, the API keeps the full-route summary shape and adds scoped_destination plus segment-level destination_scope values. Use destination pages for access-truth; use route summary for the broader route view.

Only full coverage summaries are cacheable

This endpoint follows the California fresh-full-only cache posture. The API caches responses only when _meta.query_coverage is full and every covering source is below the stale threshold. Stale-but-usable, partial, and none responses are no-store.