Crosby News Weather API

openapi: 3.2.0
info:
  title: crosbynews.com Weather API
  version: 1.7.0
  description: 'Crosby, Texas community data: current conditions, hourly and 7-day forecast, active alerts, the EPA UV index, and a measured air-quality index (EPA/AirNow monitors, with an Open-Meteo modeled fallback) from the U.S. National Weather Service, EPA/AirNow, and Open-Meteo; river/bayou flood levels; the Atlantic tropical outlook; the Houston Health Department''s measured daily pollen and mold count; the Harris County burn-ban status from the Texas A&M Forest Service; road incidents and lane closures from Houston TranStar; recent local news headlines; and the Crosby ISD school calendar. Public, no authentication.'
  contact:
    url: https://crosbynews.com/
  license:
    name: Public domain (NWS source data)
    url: https://www.weather.gov/disclaimer
servers:
- url: https://crosbynews.com
security: []
tags:
- name: Weather
paths:
  /api/weather:
    get:
      operationId: getWeather
      summary: Current conditions, forecast, and alerts for Crosby, TX
      parameters:
      - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: Weather snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Weather'
        '304':
          $ref: '#/components/responses/NotModified'
        '502':
          description: Upstream (NWS) unavailable
      tags:
      - Weather
components:
  parameters:
    IfNoneMatch:
      name: If-None-Match
      in: header
      required: false
      description: A previously returned weak ETag. When it still matches the cached snapshot, the endpoint answers 304 with no body — the cheap way to poll.
      schema:
        type: string
  responses:
    NotModified:
      description: Not Modified — the caller's If-None-Match matches the current snapshot, so no body is sent. The ETag is derived from the cache's refresh stamp, so it changes exactly when the payload would.
  schemas:
    HourlyPeriod:
      type: object
      additionalProperties: true
      properties:
        number:
          type: integer
        name:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        isDaytime:
          type: boolean
        temperature:
          type: number
        temperatureUnit:
          type: string
        temperatureTrend:
          type:
          - string
          - 'null'
        shortForecast:
          type: string
        windSpeed:
          type: string
        windDirection:
          type: string
        windGust:
          type: string
        probabilityOfPrecipitation:
          type: object
          additionalProperties: true
          properties:
            value:
              type:
              - number
              - 'null'
            unitCode:
              type: string
        icon:
          type: string
          format: uri
        feelsLike:
          type:
          - number
          - 'null'
          description: Heat index or wind chill in °F, computed from temperature/humidity/wind using NWS's own formulas. Not an NWS field — null when neither applies.
    Alert:
      type: object
      properties:
        event:
          type: string
        headline:
          type: string
        severity:
          type: string
        description:
          type: string
        instruction:
          type: string
        expires:
          type: string
          format: date-time
    Period:
      type: object
      additionalProperties: true
      properties:
        number:
          type: integer
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        name:
          type: string
        isDaytime:
          type: boolean
        temperature:
          type: number
        temperatureUnit:
          type: string
        shortForecast:
          type: string
        detailedForecast:
          type: string
        windSpeed:
          type: string
        windDirection:
          type: string
        probabilityOfPrecipitation:
          type: object
          additionalProperties: true
          properties:
            value:
              type:
              - number
              - 'null'
            unitCode:
              type: string
        icon:
          type: string
          format: uri
    Weather:
      type: object
      properties:
        location:
          type: string
        coordinates:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
        source:
          type: string
        updated:
          type: string
          format: date-time
        sun:
          type:
          - object
          - 'null'
          description: Today's sunrise/sunset for Crosby, computed astronomically in-Worker (standard sunrise equation) — not an NWS field.
          properties:
            sunrise:
              type: string
              format: date-time
            sunset:
              type: string
              format: date-time
        uv:
          type:
          - object
          - 'null'
          description: UV index from the U.S. EPA's UV forecast for Crosby's ZIP (77532) — not an NWS field. null when the EPA fetch failed or the current hour is outside the product's daytime window.
          properties:
            current:
              type:
              - integer
              - 'null'
              description: UV index for the current hour (Central time).
            currentCategory:
              type:
              - string
              - 'null'
              description: Low / Moderate / High / Very High / Extreme.
            peakToday:
              type:
              - integer
              - 'null'
              description: Highest forecast UV index for today, held until midnight CT after EPA's product rolls to the next day (about 7 PM CT). Null only when today's midday hours are unavailable.
            peakCategory:
              type:
              - string
              - 'null'
            source:
              type: string
        airQuality:
          $ref: '#/components/schemas/AirQuality'
        current:
          anyOf:
          - $ref: '#/components/schemas/HourlyPeriod'
          - type: 'null'
        hourly:
          type: array
          items:
            $ref: '#/components/schemas/HourlyPeriod'
        forecast:
          type: array
          items:
            $ref: '#/components/schemas/Period'
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
    AirQuality:
      type:
      - object
      - 'null'
      description: 'US Air Quality Index. `measured: true` = EPA/AirNow official monitors for the Houston-Galveston-Brazoria reporting area (the nearest official area, which includes Crosby — there''s no monitor in Crosby itself). `measured: false` = Open-Meteo modeled forecast for Crosby''s coordinates, the fallback when AirNow isn''t reporting. `modeled` is the inverse of `measured` (kept for back-compat). null when both failed.'
      properties:
        usAqi:
          type: integer
          description: US AQI, 0–500 scale (the max of the pollutant sub-indices).
        category:
          type: string
          description: Good / Moderate / Unhealthy for Sensitive Groups / Unhealthy / Very Unhealthy / Hazardous.
        dominantPollutant:
          type:
          - string
          - 'null'
          description: The pollutant driving the overall AQI.
        dominantMonitor:
          type:
          - string
          - 'null'
          description: Monitor site reporting the dominant pollutant (measured path).
        monitors:
          type:
          - object
          - 'null'
          description: Per-pollutant reporting monitor site names (measured path).
        reportingAgency:
          type:
          - string
          - 'null'
          description: Agency operating the monitors (e.g. TCEQ).
        subIndices:
          type:
          - object
          - 'null'
          description: Per-pollutant AQI (ozone/pm25/pm10/…). Present for both sources.
        pm2_5:
          type:
          - number
          - 'null'
          description: PM2.5 concentration in concentrationUnit (modeled source only; null when measured).
        pm10:
          type:
          - number
          - 'null'
        ozone:
          type:
          - number
          - 'null'
        concentrationUnit:
          type: string
        measured:
          type: boolean
        modeled:
          type: boolean
          description: Inverse of measured; retained for back-compat.
        reportingArea:
          type:
          - string
          - 'null'
          description: AirNow reporting area (measured source only).
        observed:
          type:
          - string
          - 'null'
          description: Local observation time (measured source only).
        source:
          type: string
        nearbyMonitor:
          type:
          - object
          - 'null'
          description: Cross-reference reading from the nearest DEDICATED ozone monitor (Channelview C15, ~8.5 mi), so a locally elevated ozone value can't hide behind the closest-per-pollutant headline above. Hourly, EPA/AirNow. null when that monitor didn't report in the last refresh window, or when the headline AQI is itself unavailable.
          properties:
            site:
              type: string
            pollutant:
              type: string
              description: Always "ozone" — PM is already covered by the headline monitors.
            usAqi:
              type: integer
            category:
              type: string
            distanceMiles:
              type: number
              description: Straight-line distance from Crosby.
            observed:
              type:
              - string
              - 'null'
              format: date-time
            reportingAgency:
              type:
              - string
              - 'null'
            note:
              type: string