Weather

Consecutive hours that meet activity criteria.

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.

get/v1/windows

Request

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

Query parameters

latnumber double

Latitude (WGS84 decimal degrees). Give it with lon. On a route that also takes zip or location, give only one location form.

lonnumber double

Longitude (WGS84 decimal degrees). Give it with lat. On a route that also takes zip or location, give only one location form.

zipstring

5-digit US ZIP code. Mutually exclusive with lat/lon and location.

locationstring

Free-text location name. Examples: "Boston, MA", "94043", "Denver". Resolved by the Smarter Weather geocoder. Mutually exclusive with lat/lon and zip.

units'imperial' | 'metric'

Unit system for numeric response fields. imperial (default) uses °F, mph, inHg, mi, in; metric uses °C, kph, hPa, km, mm. See the Units schema returned with every response for the exact label set.

hoursinteger

How far ahead to search, in hours.

activity_duration_hoursinteger

Minimum consecutive hours that must meet the criteria.

daylight_onlyboolean

When true (the default), hours outside sunrise–sunset are excluded when sun times are available. In polar night no hour is daylight, so windows is empty; under midnight sun every hour is. If sun times cannot be loaded, the daylight filter is skipped.

max_precipitation_probabilitynumber double

Drop hours whose precipitation probability exceeds this percent.

min_temperaturenumber double

Drop hours colder than this, in the selected units.

max_temperaturenumber double

Drop hours warmer than this, in the selected units.

max_wind_speednumber double

Drop hours with sustained wind above this, in the selected units.

max_wind_gustnumber double

Drop hours with a gust above this, in the selected units.

min_visibilitynumber double

Drop hours with visibility below this, in the selected units.

min_ceilingnumber double

Drop hours with a cloud ceiling below this, in the selected units.

activitystring

Free-text activity used only when activity rating is enabled. At most 200 characters. Accepted and ignored when rating is off.

Response

Windows that meet the criteria, possibly empty.

units'imperial' | 'metric' required
daylight_onlyboolean required
activity_duration_hoursinteger required
messagestring

Set when windows is empty because the point is outside NBM coverage or no forecast series was available.

Example response

{
  "location": {
    "name": "Boston",
    "region": "MA",
    "country": "US",
    "timezone": "America/New_York",
    "county": "Suffolk",
    "zip": "02108"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.