omnilab/usgs-water API reference

Omnilab\UsgsWater

UsgsWaterSource class

final class UsgsWaterSource extends HttpSource UsgsWaterSource.php:34

The USGS's water data, through the Water Data OGC APIs (api.waterdata.usgs.gov/ogcapi/v1), which replace the WaterServices (waterservices.usgs.gov, shut down on 2027-02-22): the series of a monitoring location - streamflow, gage height, water temperature, any parameter by its USGS code - as recorded (the "continuous" values, every 5 or 15 minutes) or as the USGS's daily statistics; a monitoring location itself, an entity with its place, drainage area and the series it keeps; the monitoring locations by name.

No key needed; an api.data.gov key (api_key) raises the rate limit.

const BASE_URI = 'https://api.waterdata.usgs.gov/ogcapi/v1/'

const MAX_LIMIT = 50000

The most features a call answers: a larger limit is a 400.

const PARAMETERS = ['discharge' => '00060', 'gage_height' => '00065', 'water_temperature' => '00010', 'specific_conductance' => '00095', 'dissolved_oxygen' => '00300', 'ph' => …

The names series() reads for the USGS's parameter codes; any other five-digit code is read as it is.

const STATISTICS = [Series::MEAN => '00003', Series::MAX => '00001', Series::MIN => '00002', Series::SUM => '00006']

The USGS's statistic code for each aggregation of a day.

UsgsWaterSource::__construct()

public function __construct(HttpClientInterface $http, readonly float $radius = 25.0, string $baseUri = self::BASE_URI, array $headers = [], float $throttle = 0.0)

$radius

how far from a Point the nearest monitoring location is looked for, in kilometres

UsgsWaterSource::getName()

public function getName(): string

UsgsWaterSource::capabilities()

public function capabilities(): array

UsgsWaterSource::entity()

public function entity(Identifier|string $id): ?Entity

A monitoring location (USGS-01646500, usgs.site:01646500, its page): its name, type, place and altitude, drainage area, state and county, hydrologic unit, and each series it keeps with the period it covers.

Two calls; null when unknown.

UsgsWaterSource::search()

public function search(Query $query): Page

The monitoring locations of the USGS whose name holds the text (case aside: the names are upper case), one page at a time, the next by the API's cursor.

UsgsWaterSource::series()

public function series(SeriesQuery $query): array

The series of a monitoring location, one per variable asked ("discharge", "gage_height", "water_temperature"... or a USGS parameter code, "00060"), at a station named (usgs.site) or at the nearest monitoring location of a Point that keeps the first variable over the period (within the configured radius):

• SeriesQuery::DAILY: the USGS's daily values, the mean of each day unless the query aggregates otherwise (MAX, MIN, SUM: the USGS's own statistics, computed in the location's local days);
• any other step (HOURLY by default, PT15M, PT5M...): the values as recorded, the one at each step's start without an aggregation, the step's MAX, MIN, MEAN or SUM with one.

The period defaults to the last seven days; a date without a time is the whole day, in the query's time zone (UTC by default).

UsgsWaterSourceFactory class

final class UsgsWaterSourceFactory extends SourceFactory UsgsWaterSourceFactory.php:22

The USGS's water data (Water Data OGC APIs): the series of a monitoring location, as recorded or daily, the location itself, a search by name - no key needed.

options: mailto: 'support@glitchr.io' # in the User-Agent api_key: ~ # an api.data.gov key for the USGS's water APIs: a higher rate limit (sent as X-Api-Key) radius_km: 25 # how far from a Point the nearest monitoring location is looked for throttle: 0 # seconds between two calls base_uri: 'https://api.waterdata.usgs.gov/ogcapi/v1/'

Options