Crosby News Fishing API

openapi: 3.2.0
info:
  title: crosbynews.com Fishing 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: Fishing
paths:
  /api/fishing:
    get:
      operationId: getFishing
      summary: Live fishing-water conditions (USGS) for the waters people fish near Crosby, TX
      parameters:
      - $ref: '#/components/parameters/IfNoneMatch'
      responses:
        '200':
          description: 'Per-station conditions from USGS real-time monitoring for the fished waters (Lake Houston, the San Jacinto forks, the Trinity River, and nearby bayous): temperature, dissolved oxygen, pH, and turbidity where measured, or water level for level-only stations. Nearby readings, not the exact spot.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fishing'
        '304':
          $ref: '#/components/responses/NotModified'
        '502':
          description: Fishing data unavailable
      tags:
      - Fishing
components:
  schemas:
    FishingStation:
      type: object
      properties:
        id:
          type: string
          description: USGS site number (e.g. 08072000).
        water:
          type:
          - string
          - 'null'
          description: The water body this station stands in, e.g. "Lake Houston".
        spot:
          type:
          - string
          - 'null'
          description: Where on that water, e.g. "FM 1960 bridge".
        knownFor:
          type:
          - string
          - 'null'
          description: Species the water is fished for, e.g. "bass, crappie, white bass, catfish". Editorial, not USGS.
        temperatureF:
          type:
          - number
          - 'null'
          description: Water temperature in °F, converted from the USGS Celsius reading. null when this station does not measure it.
        dissolvedOxygenMgL:
          type:
          - number
          - 'null'
          description: Dissolved oxygen, mg/L. The main fish-activity signal.
        ph:
          type:
          - number
          - 'null'
        turbidityFNU:
          type:
          - number
          - 'null'
          description: Turbidity in Formazin Nephelometric Units — water clarity.
        waterLevelFt:
          type:
          - number
          - 'null'
          description: Gauge height in feet. Level-only stations report this and nothing else.
        conditions:
          type: string
          description: One-line plain-language read of the station, e.g. "Healthy oxygen". Derived in-Worker from the readings above, not a USGS field. English only, even on /es.
        observed:
          type:
          - string
          - 'null'
          format: date-time
          description: When USGS observed the reading (station-local offset, as USGS reports it) — distinct from the top-level `updated`, which is when we fetched.
        officialUrl:
          type: string
          format: uri
          description: The station's USGS monitoring-location page.
    Fishing:
      type: object
      properties:
        location:
          type: string
        source:
          type: string
        note:
          type: string
          description: 'Standing caveat: nearest station per water body, a nearby reading rather than the exact fishing spot.'
        updated:
          type:
          - string
          - 'null'
          format: date-time
          description: When we last refreshed the cache (cron, every tick). Per-reading times are each station's `observed`.
        stations:
          type: array
          items:
            $ref: '#/components/schemas/FishingStation'
      required:
      - stations
  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.