Returns a composite blended weather payload for a single location. A single call covers current conditions, hourly forecast, daily forecast, active alerts, convective outlooks, and astronomical data by default; other sections (location echo, geographic metadata, narrative text, forecaster guidance) are available via the include parameter.

Location selector

Exactly one of the following must be provided:

• lat and lon — latitude/longitude pair.
• zip — 5-digit US ZIP code.
• location — free-text location name (e.g., "Boston, MA", "94043", "Denver"). Resolved by the same upstream geocoder that powers the dedicated /v1/geocode/{search,autosuggest,reverse} endpoints; clients that need geocoding without a weather fetch should call those directly.

Sending more than one selector, or none, returns 400.

Units

• imperial (default): °F, mph, inHg, mi, in.
• metric: °C, kph, hPa, km, mm.

SI is not exposed in v1; partners that need SI should convert client-side.

Include semantics

include is a comma-separated list. Unknown tokens are silently dropped. See the API-level "Include tokens" table in the info.description for the full token catalog, defaults, and stability markers.

Coverage

Coverage is the 50 US states and DC, for every caller. A location outside it (another country, Puerto Rico, Guam and the other territories, or open water beyond about 3 nm offshore) returns 404 with type https://smarterweather.com/errors/outside-coverage and next_steps (recommended = coverage); in POST /v1/weather/batch that row's error.code is outside_coverage. Do not retry the same point. A zip or location resolves to its first match inside coverage (so Carolina is Carolina, RI, not Carolina, PR); one whose every match is outside coverage returns outside-coverage, and one that matches no US place returns 404 not-found, both with next_steps. Partial-coverage scenarios inside coverage are reported via meta.warnings[] with a structured code so clients can respond programmatically.

Response density, sampling and sparse fieldsets

Three independent, opt-in controls shrink the hourly and daily rows. Without them the response is exactly the detailed body. They never add sections, never change current, alerts, outlooks, astro, location, meta (beyond meta.hourly_sampling) or attribution, and never change pricing.

view is a column preset: detailed (default) returns every column; concise returns a documented subset and never drops rows.

• concise hourly columns: time, temperature, feels_like, humidity, wind_speed, wind_gust, wind_direction, precip_probability, precip_amount, precip_type, snow_amount, thunderstorm_probability, cape, cloud_ceiling, snow_level, uv_index, conditions, icon, severe, thunder_possible.
• concise daily columns: date, relative_day, active_period, high, low, conditions, icon, severe, precip_probability, precip_total, snow_total, ice_total, wind_speed_max, wind_direction, humidity_avg, uv_index_max, cape_max, thunder_possible, threats, astro, day.precip_probability, night.precip_probability.
• include wins over the preset: with include=uncertainty, hourly[].uncertainty and daily[].uncertainty stay; with include=climate, daily[].climate stays.
• The preset only grows. A column may be added to concise (announced in the changelog); none is ever removed from it.

hourly_step and hourly_step_from thin hourly rows, after hourly_hours sets the window and independently of view and fields. Rows whose offset from hourly[0].time is below hourly_step_from hours are all kept; from there on, only rows at hourly_step_from + k * hourly_step hours are kept. A row's offset is the whole hours between its time and hourly[0].time, both floored to the hour, so a partial first hour (14:30, then 15:00, ...) is offset 0 and the full hours after it are 1, 2, ... Offsets come from timestamps, not array indexes, so a gap in the series does not shift the grid. hourly_step=3&hourly_step_from=24 keeps the first day at full resolution and every third hour after it (48 hours become 32 rows, 72 become 40, 168 become 72). When thinning drops at least one row, meta.hourly_sampling echoes the effective parameters so a thinned series is distinguishable from a short forecast.

fields selects exact members of hourly and daily rows, as section.name paths (hourly.temperature,daily.high). It is exact for every section it names and beats view there; a section it does not name follows view. hourly[].time and daily[].date are always returned. fields never implies include: a path whose section, or uncertainty / climate object, is not in the effective include is a 400. Unknown names are a 400 that lists the valid names, never a silent drop (unlike include, which drops unknown tokens).

Presence semantics. A selected (or preset) field is present, and null when its value is unavailable, exactly as in detailed. A field the schema marks optional can be absent for its zero value, exactly as in detailed. A field that was not selected is absent. A field that does not exist is a 400 at request time, so a 200 never hides an unknown name. Every shaped response is a key-subset of the detailed response for the same request.

{
  "location": {
    "name": "Boston",
    "region": "MA",
    "country": "US",
    "timezone": "America/New_York",
    "county": "Suffolk",
    "zip": "02108"
  },
  "current": {
    "conditions": "Partly Cloudy",
    "icon": "partly-cloudy-day"
  },
  "daily": [
    {
      "date": "2026-04-20",
      "threats": [
        {
          "type": "severe"
        }
      ],
      "climate": {
        "normal_high": 78,
        "normal_low": 58,
        "high_departure": 4,
        "low_departure": -2
      }
    }
  ],
  "alerts": [
    {
      "id": "urn:oid:2.49.0.1.840.0.d1e1a911ed0a8ca7b56a9e6a3c5d6ba0035c88fb.001.1",
      "event": "Wind Advisory"
    }
  ],
  "outlooks": [
    {
      "product_id": "spc_otlk_day1",
      "type": "severe",
      "risk_label": "Slight"
    }
  ],
  "gis": {
    "nearest_radar": {
      "id": "BOX",
      "name": "Boston"
    },
    "nearest_station": {
      "id": "KJFK"
    }
  },
  "attribution": {
    "sources": [
      "NOAA/NWS",
      "NBM",
      "GFS",
      "HRRR",
      "RTMA",
      "MRMS",
      "EPA AirNow"
    ],
    "notice": "Data sourced from NOAA/NWS and EPA AirNow public products. Derived products produced by Smarter Weather."
  },
  "nowcast": {
    "interval_seconds": 300
  },
  "climate": {
    "station": {
      "station_id": "USW00094728",
      "name": "NEW YORK CNTRL PK",
      "state": "NY",
      "latitude": 40.7789,
      "longitude": -73.9692,
      "elevation_m": 42.7,
      "distance_km": 3.4
    },
    "meta": {
      "normals_period": "1991-2020",
      "source": "station",
      "normals_method": "official"
    },
    "days": [
      {
        "date": "2026-07-28",
        "month": 7,
        "day": 28,
        "normal_high": 84.2,
        "normal_low": 69.8,
        "normal_mean": 77,
        "normal_high_stddev": 5.4,
        "normal_low_stddev": 5,
        "normal_mean_stddev": 4.7,
        "normal_precip": 0.11,
        "years": 30,
        "completeness_flag": "C"
      }
    ],
    "location": {
      "name": "Boston",
      "region": "MA",
      "country": "US",
      "timezone": "America/New_York",
      "county": "Suffolk",
      "zip": "02108"
    }
  },
  "metar": {
    "station_id": "KORD"
  },
  "meta": {
    "schema_version": "1.0.0",
    "freshness": [
      {
        "source": "rtma",
        "product_id": "rtma_conus_2p5km"
      }
    ],
    "warnings": [
      {
        "code": "partial_fetch",
        "section": "alerts",
        "product_id": "airquality_combined",
        "fields": [
          "aqi",
          "aqi_category",
          "pm25",
          "ozone",
          "pm10"
        ]
      }
    ]
  }
}