USGS Water — daily discharge quickstart¶

Pull a daily discharge (00060) time series for the Potomac River near Washington, DC (USGS site 01646500) and plot it. Uses api="legacy", which serves anonymous requests reliably.

Setup¶

Consolidate the imports up front: earthlens provides the unified EarthLens entry point, and matplotlib draws the discharge series. USGS Water is a tabular backend — no credentials are required.

In [ ]:

import matplotlib.pyplot as plt

from earthlens.earthlens import EarthLens

import matplotlib.pyplot as plt from earthlens.earthlens import EarthLens

1 · Fetch the discharge series¶

USGS Water returns its records as a table, so earthlens treats it as a tabular backend: download() writes a CSV and hands back a DataFrame.

Build the request¶

Describe what we want — the daily discharge variable, the 2023 Q1 date window, a small bounding box over the Potomac, and the specific USGS site and service. Building the request first keeps it easy to read and re-run.

In [ ]:

gauge = EarthLens(
    data_source="usgs-water",
    variables=["discharge"],
    start="2023-01-01",
    end="2023-03-31",
    aoi=[-77.2, 38.9, -77.0, 39.0],
    path="_nb_out",
    service="daily",
    sites="01646500",
    api="legacy",
)

gauge = EarthLens( data_source="usgs-water", variables=["discharge"], start="2023-01-01", end="2023-03-31", aoi=[-77.2, 38.9, -77.0, 39.0], path="_nb_out", service="daily", sites="01646500", api="legacy", )

Download into a DataFrame¶

With the request built, download() fetches the series into memory (and writes the backing CSV). We keep it on its own line so the call is easy to read; head() previews the first few rows.

In [ ]:

df = gauge.download(progress_bar=False)
df.head()

df = gauge.download(progress_bar=False) df.head()

2 · Plot the series¶

Plot the discharge value against its datetime to see the Potomac's winter flow through the first quarter of 2023.

In [ ]:

ax = df.plot(x="datetime", y="value", legend=False, figsize=(9, 3))
ax.set_ylabel("Discharge (ft3/s)")
ax.set_title("Potomac River daily discharge")
plt.tight_layout()

ax = df.plot(x="datetime", y="value", legend=False, figsize=(9, 3)) ax.set_ylabel("Discharge (ft3/s)") ax.set_title("Potomac River daily discharge") plt.tight_layout()