Sign up
All data sources

USGS Water Services

Unknown authusgs-water

USGS National Water Information System (NWIS) - real-time and historical water data. Streamflow, gage height, groundwater levels, and monitoring site information. CRITICAL USAGE RULES: 1. No authentication required 2. searchSites takes exactly ONE location filter: bbox ("west,south,east,north") OR countyCd (5-digit FIPS) OR stateCd (2-letter). Empty result = no sites matched. 3. Use site IDs from searchSites() for data queries (getGroundwaterLevels also accepts bbox directly) 4. Parameter codes: 00060=discharge, 00065=gage height, 72019=depth to water 5. Period format: P1D=1 day, P7D=7 days, P30D=30 days. getDailyValues defaults to P30D when no dates given.

Get this contract as JSONConnect this source →

Provenance

PublisherUSGS Water Services

Freshness & coverage

FreshnessFreshness not declared
GeographicNot declared
TemporalNot declared
AuthenticationNo credentials required

Methods (6)

  • getServiceInfo

    read

    Describe USGS Water methods, location filters, parameter codes, and period formats.

    Input schema
    {
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

  • getInstantaneousValues

    read

    Real-time readings (streamflow, gage height) for named USGS sites.

    Required paramssites or site or siteCode or siteId
    Input schema
    {
  "type": "object",
  "properties": {
    "sites": {
      "type": "string",
      "description": "Comma-separated USGS site IDs. Get IDs from searchSites."
    },
    "site": {
      "type": "string",
      "description": "Single site ID (alias for sites)."
    },
    "siteCode": {
      "type": "string",
      "description": "Alias for sites."
    },
    "siteId": {
      "type": "string",
      "description": "Alias for sites."
    },
    "parameterCd": {
      "type": "string",
      "description": "Comma-separated parameter codes (00060=discharge, 00065=gage height)."
    },
    "period": {
      "type": "string",
      "description": "ISO duration lookback such as P1D, P7D, P30D (default P1D). This endpoint takes period only — no start/end dates."
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "sites"
          ]
        },
        {
          "required": [
            "site"
          ]
        },
        {
          "required": [
            "siteCode"
          ]
        },
        {
          "required": [
            "siteId"
          ]
        }
      ]
    }
  ]
}

  • getDailyValues

    read

    Daily statistical values for named USGS sites (defaults to the last 30 days).

    Required paramssites or site or siteCode or siteId
    Input schema
    {
  "type": "object",
  "properties": {
    "sites": {
      "type": "string",
      "description": "Comma-separated USGS site IDs. Get IDs from searchSites."
    },
    "site": {
      "type": "string",
      "description": "Single site ID (alias for sites)."
    },
    "siteCode": {
      "type": "string",
      "description": "Alias for sites."
    },
    "siteId": {
      "type": "string",
      "description": "Alias for sites."
    },
    "parameterCd": {
      "type": "string"
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "period": {
      "type": "string",
      "description": "ISO duration lookback; defaults to P30D when no dates are given."
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "sites"
          ]
        },
        {
          "required": [
            "site"
          ]
        },
        {
          "required": [
            "siteCode"
          ]
        },
        {
          "required": [
            "siteId"
          ]
        }
      ]
    }
  ]
}

  • getSiteInfo

    read

    Monitoring-site metadata for named USGS sites.

    Required paramssites
    Input schema
    {
  "type": "object",
  "properties": {
    "sites": {
      "type": "string",
      "description": "Comma-separated USGS site IDs."
    }
  },
  "additionalProperties": false,
  "required": [
    "sites"
  ]
}

  • searchSites

    read

    Find USGS monitoring sites by ONE location filter: bbox, countyCd, or stateCd (bbox wins if several are given).

    Required paramsbbox or boundingBox or countyCd or countyCode or stateCd or state
    Input schema
    {
  "type": "object",
  "properties": {
    "stateCd": {
      "type": "string",
      "description": "2-letter state code."
    },
    "state": {
      "type": "string",
      "description": "Alias for stateCd."
    },
    "siteType": {
      "type": "string",
      "description": "e.g. GW for groundwater, ST for stream."
    },
    "parameterCd": {
      "type": "string"
    },
    "bbox": {
      "type": "string",
      "description": "west,south,east,north (decimal degrees)."
    },
    "bBox": {
      "type": "string"
    },
    "boundingBox": {
      "type": "string",
      "description": "Alias for bbox."
    },
    "countyCd": {
      "type": "string",
      "description": "5-digit county FIPS code."
    },
    "countyCode": {
      "type": "string",
      "description": "Alias for countyCd."
    },
    "maxResults": {
      "type": "integer"
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "bbox"
          ]
        },
        {
          "required": [
            "boundingBox"
          ]
        },
        {
          "required": [
            "countyCd"
          ]
        },
        {
          "required": [
            "countyCode"
          ]
        },
        {
          "required": [
            "stateCd"
          ]
        },
        {
          "required": [
            "state"
          ]
        }
      ]
    }
  ]
}

  • getGroundwaterLevels

    read

    Groundwater levels for named USGS sites, or for an area via bbox.

    Required paramssites or site or siteCode or siteId or bbox or bBox
    Input schema
    {
  "type": "object",
  "properties": {
    "sites": {
      "type": "string",
      "description": "Comma-separated USGS site IDs."
    },
    "site": {
      "type": "string",
      "description": "Single site ID (alias for sites)."
    },
    "siteCode": {
      "type": "string",
      "description": "Alias for sites."
    },
    "siteId": {
      "type": "string",
      "description": "Alias for sites."
    },
    "startDate": {
      "type": "string"
    },
    "endDate": {
      "type": "string"
    },
    "bbox": {
      "type": "string",
      "description": "west,south,east,north — resolves groundwater sites in the box first (capped at 20)."
    },
    "bBox": {
      "type": "string",
      "description": "Alias for bbox."
    },
    "siteType": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "anyOf": [
        {
          "required": [
            "sites"
          ]
        },
        {
          "required": [
            "site"
          ]
        },
        {
          "required": [
            "siteCode"
          ]
        },
        {
          "required": [
            "siteId"
          ]
        },
        {
          "required": [
            "bbox"
          ]
        },
        {
          "required": [
            "bBox"
          ]
        }
      ]
    }
  ]
}