---
title: "Consecutive hours that meet activity criteria."
method: GET
path: "/v1/windows"
tags: ["Weather"]
---

# Consecutive hours that meet activity criteria.

`GET /v1/windows`

## Request

- Base URL: `https://api.smarterweather.com`
- URL: `https://api.smarterweather.com/v1/windows`
- Auth: HTTP bearer

Returns runs of forecast hours that satisfy the caller's
criteria, the REST twin of MCP `find_best_window`. The scan is
deterministic. An optional `activity` string may attach a
favorability `rating` and `limiting_factor` to one window when
activity rating is enabled for the service. When rating is off,
or the scorer does not return a usable verdict, `rating` and
`limiting_factor` are omitted and the windows stay in
chronological order.

When a rating lands, the rated window is first and the remaining
windows follow by duration (longer first).

Location selectors match `GET /v1/weather`: exactly one of
`lat`+`lon`, `zip`, or `location`.

A location outside the 50 US states and DC returns `404`
`outside-coverage` with `next_steps`, as on `GET /v1/weather`.
An empty scan inside coverage may return `windows: []` with
`message` when no forecast series is available.

`activity` does not change the metered weight of the call.

## Query parameters

- `lat` number, double
- `lon` number, double
- `zip` string
- `location` string
- `units` 'imperial' | 'metric'
- `hours` integer
- `activity_duration_hours` integer
- `daylight_only` boolean
- `max_precipitation_probability` number, double
- `min_temperature` number, double
- `max_temperature` number, double
- `max_wind_speed` number, double
- `max_wind_gust` number, double
- `min_visibility` number, double
- `min_ceiling` number, double
- `activity` string

## Response `200`

Windows that meet the criteria, possibly empty.

- WindowsResponse
  - `location` Location, required: Resolved location.
    - `lat` number, double, required
    - `lon` number, double, required
    - `name` string, required: Human-readable place name, usually without the state; see `region`. The resolved place name, else the city, else the nearest city. Empty when none is known.
    - `region` string: State or region abbreviation.
    - `country` string: ISO 3166-1 alpha-2 country code.
    - `timezone` string, required: IANA timezone identifier.
    - `county` string: County name (US only).
    - `zip` string: ZIP code (US only).
  - `units` 'imperial' | 'metric', required
  - `windows` WeatherWindow[], required
    - `start` string, date-time, required
    - `end` string, date-time, required: Timestamp of the last hour in the run.
    - `hours` integer, required: Count of passing hours in the run.
    - `rating` 'unworkable' | 'poor' | 'workable' | 'good' | 'ideal': Present only on the window a favorability score landed on.
    - `limiting_factor` 'wind' | 'precip' | 'temperature' | 'visibility' | 'storms' | 'none'
  - `criteria_applied` WindowCriteria, required: Criteria echoed back in the requested units. Omitted fields were not set.
    - `max_precipitation_probability` number, double
    - `min_temperature` number, double
    - `max_temperature` number, double
    - `max_wind_speed` number, double
    - `max_wind_gust` number, double
    - `min_visibility` number, double
    - `min_ceiling` number, double
  - `daylight_only` boolean, required
  - `activity_duration_hours` integer, required
  - `sun_times` object[]: Present when daylight filtering used sunrise and sunset. Polar dates (midnight sun, polar night) have neither and are left out.
    - `sunrise` string, date-time, required
    - `sunset` string, date-time, required
  - `message` string: Set when `windows` is empty because the point is outside NBM coverage or no forecast series was available.

## Other responses

- `400`: Bad request.
- `401`: Missing or invalid API key. Carries a `WWW-Authenticate` challenge and a `next_steps` extension. `recommended` is `device_flow`: the object is a complete no-install mint recipe.
- `403`: API key lacks the required scope. Carries a `WWW-Authenticate` challenge with `error="insufficient_scope"` and a `next_steps` extension.
- `404`: Resource not found: a location that cannot be resolved (unknown ZIP, unrecognised free-text location), no upstream data for the location, or a missing resource. On a route that checks coverage (its description says so), a location outside the 50 US states and DC returns type `https://smarterweather.com/errors/outside-coverage`; that and the location-not-found problem carry `next_steps` (`recommended = coverage`).
- `429`: Rate limit exceeded. Carries a `next_steps` extension (`recommended: upgrade`, plus `pricing` and `usage`) telling the caller how to lift the limit.
- `500`: Internal server error.
- `502`: Bad gateway. The service received an invalid response from an upstream data source. Transient; clients should retry with backoff.
- `503`: Service unavailable. An upstream dependency is unavailable or shedding load (type `service-unavailable`). Transient; retry with backoff and honor any `Retry-After` header.
- `504`: Gateway timeout. An upstream data source did not respond within the service's budget.

---

[API](https://skmtc.dev/smarterweather/apis/smarter-weather-api.md) · [All operations](https://skmtc.dev/smarterweather/apis/smarter-weather-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smarterweather/apis/smarter-weather-api/revisions/520d55a696e4?raw)