Developers

Conditions

Overview

GET

/v1/conditions

Conditions

Conditions is the detailed filtering and debugging surface for live road-condition rows. Use it when a caller needs segment-level detail, list pagination, or explicit filter control after destination or route discovery.

Parameters

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

jurisdiction

Query Optional

string

Canonical jurisdiction code. When route is supplied for an active Big Bear MVP route and jurisdiction is omitted, the effective jurisdiction defaults to US-CA.

route

Query Optional

string

Canonical route filter. Comma-separated values are allowed. For the active Big Bear MVP, supported examples include SR-18, SR-38, SR-138, and SR-330.

overall_status

Query Optional

string

Comma-separated overall_status filter using open, advisory, restricted, or closed.

chain_control_severity_gte

Query Optional

integer

Minimum chain-control severity filter in the range 0 through 4.

include_open

Query Optional

boolean

Defaults to false. Set true to include open rows alongside the default non-open live filter.

is_active

Query Optional

boolean

Defaults to true. Set false to return only inactive rows. Inactive queries are not suppressed by current source health.

cursor

Query Optional

string

Opaque pagination cursor from the previous page. Invalid cursors return INVALID_PARAMETER.

limit

Query Optional

integer

Page size. Default 50, maximum 200.

Name	Location	Required	Type	Description
jurisdiction	Query	No	string	Canonical jurisdiction code. When route is supplied for an active Big Bear MVP route and jurisdiction is omitted, the effective jurisdiction defaults to US-CA.
route	Query	No	string	Canonical route filter. Comma-separated values are allowed. For the active Big Bear MVP, supported examples include SR-18, SR-38, SR-138, and SR-330.
overall_status	Query	No	string	Comma-separated overall_status filter using open, advisory, restricted, or closed.
chain_control_severity_gte	Query	No	integer	Minimum chain-control severity filter in the range 0 through 4.
include_open	Query	No	boolean	Defaults to false. Set true to include open rows alongside the default non-open live filter.
is_active	Query	No	boolean	Defaults to true. Set false to return only inactive rows. Inactive queries are not suppressed by current source health.
cursor	Query	No	string	Opaque pagination cursor from the previous page. Invalid cursors return INVALID_PARAMETER.
limit	Query	No	integer	Page size. Default 50, maximum 200.

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/conditions?route=SR-18&overall_status=restricted,closed" \
  -H "Accept: application/json"

TypeScript

const response = await fetch(
  "https://api-staging.mountainswitch.co/v1/conditions?route=SR-18&overall_status=restricted,closed",
  {
    headers: {
      Accept: "application/json",
    },
  },
);

const payload = await response.json();

Python

import requests

response = requests.get(
    "https://api-staging.mountainswitch.co/v1/conditions",
    params={
        "route": "SR-18",
        "overall_status": "restricted,closed",
    },
    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": [
    {
      "id": "ca-chain-controls:2012",
      "source": "ca-chain-controls",
      "source_record_id": "2012",
      "jurisdiction": "US-CA",
      "route": "SR-18",
      "direction": "N",
      "segment_description": "Lower Waterman Cyn thru Vista Point",
      "start_lat": 34.2101,
      "start_lon": -117.2847,
      "end_lat": null,
      "end_lon": null,
      "county": "SBd",
      "elevation": 4500,
      "type_of_work": null,
      "type_of_closure": null,
      "estimated_delay_minutes": null,
      "lanes_closed": null,
      "total_existing_lanes": null,
      "overall_status": "restricted",
      "chain_control_severity": 3,
      "chain_control_code": "chains_awd_exempt",
      "chain_control_raw": "R-2",
      "alert_type": "chain_control",
      "vehicle_restrictions": [],
      "status_description": "Chains or traction devices required. AWD with snow tires exempt.",
      "road_surface": null,
      "visibility": null,
      "speed_limit": null,
      "is_active": true,
      "source_updated_at": "2026-03-19T12:43:00Z",
      "fetched_at": "2026-03-19T12:45:00Z",
      "valid_from": "2026-03-19T12:43:00Z",
      "valid_until": null
    }
  ],
  "_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"
      }
    ],
    "query_coverage": "full",
    "request_id": "req_conditions_docs",
    "response_generated_at": "2026-03-19T12:47:30Z",
    "pagination": {
      "cursor": "eyJpZCI6ImNhLWNoYWluLWNvbnRyb2xzOjIwMTIiLCJvIjoyLCJzIjozfQ==",
      "has_more": true
    }
  }
}

Response fields

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

data: Array<object>; Paginated list of road-condition rows that match the current filters.
data[].id: string; Stable road-condition identifier used by GET /v1/conditions/:id.
data[].source: string; Adapter identifier that produced the row.
data[].source_record_id: string; Upstream adapter record identifier preserved for debugging.
data[].jurisdiction: string; Canonical API jurisdiction code for the row.
data[].route: string; Canonical route value for the row.
data[].direction: string | null; Normalized direction for the row when available.
data[].segment_description: string; Human-readable segment description from the normalized row.
data[].start_lat: number; Start latitude for the row.
data[].start_lon: number; Start longitude for the row.
data[].end_lat: number | null; End latitude, or null for point-like rows such as chain controls.
data[].end_lon: number | null; End longitude, or null for point-like rows such as chain controls.
data[].county: string | null; County code when the row carries county metadata.
data[].elevation: number | null; Elevation for the row when the source provides it.
data[].type_of_work: string | null; Additive lane-closure work classification. Chain-control rows return null.
data[].type_of_closure: string | null; Additive lane-closure type. Chain-control rows return null.
data[].estimated_delay_minutes: number | null; Additive lane-closure delay estimate when present.
data[].lanes_closed: number | null; Additive lane-closure closed-lane count when present.
data[].total_existing_lanes: number | null; Additive lane-closure total lane count when present.
data[].overall_status: string; Segment overall status, such as advisory, restricted, or closed.
data[].chain_control_severity: number; Canonical chain-control severity for the row.
data[].chain_control_code: string; Canonical chain-control code for the row.
data[].chain_control_raw: string | null; Raw chain-control code from the upstream source when present.
data[].alert_type: string; Alert category, such as chain_control or lane_closure.
data[].vehicle_restrictions: Array<unknown>; Vehicle-restriction detail from the normalized row.
data[].status_description: string; Human-readable summary for the row.
data[].road_surface: string | null; Road-surface detail when the source provides it.
data[].visibility: string | null; Visibility detail when the source provides it.
data[].speed_limit: number | null; Speed-limit detail when the source provides it.
data[].is_active: boolean; Current active-state flag for the row.
data[].source_updated_at: string; Row-level source update timestamp.
data[].fetched_at: string; Row-level fetch timestamp.
data[].valid_from: string | null; Validity-window start timestamp when present.
data[].valid_until: string | null; Validity-window end timestamp when present.
_meta.sources: Array<object>; Current adapter coverage records for the query scope.
_meta.query_coverage: "full" | "partial" | "none"; Coverage signal for the current list 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.cursor: string | null; Opaque cursor for the next page, or null when the page is exhausted.
_meta.pagination.has_more: boolean; Indicates whether another page of results exists.

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 invalid cursor, malformed boolean, repeated query parameter, or other unsupported query value.
400	INVALID_JURISDICTION	The provided jurisdiction value does not canonicalize to a known jurisdiction code.
404	ROUTE_NOT_FOUND	A supplied route filter 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.

Live conditions exclude open rows by default

GET /v1/conditions defaults to active non-open rows only. Use include_open=true to widen the live result set, or set is_active=false to query only inactive rows.

Current source health filters live list results

For live conditions queries, rows from sources with live_eligible=false are excluded even if older D1 rows still exist. Those sources still appear in _meta.sources and still affect _meta.query_coverage.

Pagination and caching are endpoint-level contracts

Conditions always paginate. Cache only applies to first-page responses with _meta.query_coverage === full. Partial and none responses are no-store.

Subsection

GET

/v1/conditions/:id

Condition by ID

Use the single-record conditions lookup for deep links, operator debugging, and record-scoped observability. This endpoint returns one stored row even when current source health is stale or down, but the coverage rules remain explicit.

Parameters

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

Path Required

string

Stable condition identifier from GET /v1/conditions. Unknown identifiers return 404 CONDITION_NOT_FOUND.

Name	Location	Required	Type	Description
id	Path	Yes	string	Stable condition identifier from GET /v1/conditions. Unknown identifiers return 404 CONDITION_NOT_FOUND.

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/conditions/ca-chain-controls:2012" \
  -H "Accept: application/json"

TypeScript

const response = await fetch(
  "https://api-staging.mountainswitch.co/v1/conditions/ca-chain-controls:2012",
  {
    headers: {
      Accept: "application/json",
    },
  },
);

const payload = await response.json();

Python

import requests

response = requests.get(
    "https://api-staging.mountainswitch.co/v1/conditions/ca-chain-controls:2012",
    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": {
    "id": "ca-chain-controls:2012",
    "source": "ca-chain-controls",
    "source_record_id": "2012",
    "jurisdiction": "US-CA",
    "route": "SR-18",
    "direction": "N",
    "segment_description": "Lower Waterman Cyn thru Vista Point",
    "start_lat": 34.2101,
    "start_lon": -117.2847,
    "end_lat": null,
    "end_lon": null,
    "county": "SBd",
    "elevation": 4500,
    "type_of_work": null,
    "type_of_closure": null,
    "estimated_delay_minutes": null,
    "lanes_closed": null,
    "total_existing_lanes": null,
    "overall_status": "restricted",
    "chain_control_severity": 3,
    "chain_control_code": "chains_awd_exempt",
    "chain_control_raw": "R-2",
    "alert_type": "chain_control",
    "vehicle_restrictions": [],
    "status_description": "Chains or traction devices required. AWD with snow tires exempt.",
    "road_surface": null,
    "visibility": null,
    "speed_limit": null,
    "is_active": true,
    "source_updated_at": "2026-03-19T12:43:00Z",
    "fetched_at": "2026-03-19T12:45:00Z",
    "valid_from": "2026-03-19T12:43:00Z",
    "valid_until": null
  },
  "_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"
      }
    ],
    "query_coverage": "full",
    "request_id": "req_condition_by_id_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.

data: object; Single stored road-condition row for the requested identifier.
data.id: string; Stable record identifier for the returned road-condition row.
data.source: string; Adapter that owns the returned row.
data.route: string; Canonical route value for the returned row.
data.overall_status: string; Current stored overall_status for the row.
data.chain_control_severity: number; Canonical chain-control severity for the row.
data.chain_control_code: string; Canonical chain-control code for the row.
data.chain_control_raw: string | null; Raw chain-control code from the upstream source when present.
data.status_description: string; Human-readable status line for the row.
data.is_active: boolean; Stored active-state flag for the row.
data.valid_until: string | null; Validity-window end timestamp when present.
_meta.sources: Array<object>; Exactly one source entry: the adapter named by the returned record's source field.
_meta.query_coverage: "full" | "partial" | "none"; Record-scoped coverage derived from the single source only.
_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 the single-record endpoint is not paginated.

Errors

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

Status	Code	When it happens
404	CONDITION_NOT_FOUND	No stored condition row exists for the requested id.
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.

This endpoint is record-scoped observability

GET /v1/conditions/:id may return a stored row even when the source is currently stale or down. Check _meta.query_coverage before treating the row as proof that a restriction is live right now.

Single-record coverage is derived from one source

The response includes exactly one _meta.sources entry and derives query_coverage from that source only. Down returns none. live_eligible=false or stale returns partial.

Single-record lookups are always no-store

GET /v1/conditions/:id is never written to the response KV cache and must always return Cache-Control: no-store.