omnilab/usgs-water

The USGS's Water Data OGC APIs (https://api.waterdata.usgs.gov/ogcapi/v1/) for omnisense/omnilab: a monitoring location's discharge, gage height, water temperature or any parameter, as recorded, hourly or daily, at a usgs.site or the nearest location of a point, as series; the location itself as an entity; locations by name. No key needed.

Installation

composer require omnilab/usgs-water

use Omnilab\UsgsWater\UsgsWaterSourceFactory;

$water = (new UsgsWaterSourceFactory($httpClient))->create([
    'mailto' => 'support@glitchr.io',  // optional
    'api_key' => null,                 // optional: an api.data.gov key for the USGS's water APIs
    'radius_km' => 25,                 // optional: how far from a Point the nearest location is looked for
]);

With the Symfony bundle, the factory is registered as usgs-water when the bundle knows it; otherwise register UsgsWaterSourceFactory as a service.

Credentials

None needed. The APIs' rate limits count per key or per address; an api.data.gov key for the USGS's water APIs (from the USGS's signup page) raises them: give it as api_key, sent as X-Api-Key.

Options

The factory's options, with the defaults it applies (UsgsWaterSourceFactory):

Capabilities

capabilities() answers entity, search, series, historical, station; an operation it does not answer throws NotSupportedException before any call.

Which API

The Water Data OGC APIs (https://api.waterdata.usgs.gov/ogcapi/v1/, v1 the current version), not the WaterServices (waterservices.usgs.gov/nwis/iv): on 2026-10-15 the WaterServices still answer, but their own page says they will be "permanently shut down on February 22nd, 2027", slowed and interrupted on purpose from January 2027, and that "users must migrate to https://api.waterdata.usgs.gov". The collections read:

Every call asks f=json; the series name only the properties read (properties=time,value, parameter_code,unit_of_measure, skipGeometry=true), at most 50,000 a page (a larger limit is a 400), the next page by the next link, fifty pages at most for one query. The API does not promise an order: the points are sorted.

Its shapes

A monitoring location is an entity (and a station of the core's usgs.site scheme); what it measures is a series (Capability::STATION: a station named answers its own records). A Point answers the series of the nearest location within radius_km that keeps the first variable asked over the period (as recorded, or daily for SeriesQuery::DAILY); a BBox is refused. search() finds the USGS's locations by name.

Calls

The units in parentheses are those the API gave Little Falls' series on 2026-10-15. A series' unit is the API's unit_of_measure, as it writes it (ft^3/s, ft, degC). The step:

• SeriesQuery::DAILY: the USGS's daily values, the mean unless the query aggregates otherwise (Series::MAX, MIN, SUM: the USGS's own daily statistics, computed in the location's local days; a day is given at its midnight in the query's zone);
• any other step (HOURLY, the default; PT15M, PT5M...): the values as recorded on the step's grid from the start of the period - without an aggregation the value recorded at each step's start (null when none was), with one the step's MAX, MIN, MEAN or SUM.

A variable it does not read, another aggregation, a box or another scheme's station are refused before any call. An unknown location is null (404); a Point with no location near: a series without points per variable, at the point. A 429 is a RateLimitedException; a 400 (InvalidParameterValue) a ProviderException with the API's description.

What an entity holds

id (usgs.site:USGS-01646500), label (its name), domain earth, kind monitoring location, place (its latitude and longitude; its altitude in metres, converted from feet), url (its page on waterdata.usgs.gov), and:

A location of a search holds the same but the series it keeps (entity() reads them).

The Collector

The APIs give no id of another base. Into USGS Water: omnilab/wikidata reads an item's USGS monitoring location number (P13020) into the usgs.site scheme, so the Collector follows a Wikidata item into this source - and offers a location's id to Wikidata, which looks items up by it.

What the APIs do not give here

The field measurements, the peaks, the water-quality samples (the Water Quality API), the statistics over years, the time series' revisions and methods, the reference lists (parameter codes, site types...), other agencies' locations (USEPA-...), the CQL2 filters beyond the name and a bounding box, and the WaterServices are not read.

Example

<?php

require __DIR__.'/vendor/autoload.php';

use Omnilab\Model\Series;
use Omnilab\Source\Query;
use Omnilab\Source\SeriesQuery;
use Omnilab\UsgsWater\UsgsWaterSourceFactory;
use Symfony\Component\HttpClient\HttpClient;

$water = (new UsgsWaterSourceFactory(HttpClient::create()))->create(['mailto' => 'you@example.org', 'api_key' => getenv('USGS_WATER_API_KEY') ?: null]);

$potomac = $water->entity('USGS-01646500');
echo $potomac->label, ' (', $potomac->id, '): ', $potomac->place, ', drainage ', $potomac->property('drainage_area'), ', ', count($potomac->properties('variable')), " series kept\n";

[$discharge] = $water->series(new SeriesQuery(['discharge'], $potomac->id, new DateTimeImmutable('2026-10-20'), new DateTimeImmutable('2026-10-26'), SeriesQuery::DAILY, Series::MEAN));
printf("%s (%s), daily means: %s\n", $discharge->label, $discharge->unit, implode(', ', $discharge->values()));

$page = $water->search(new Query('potomac river', limit: 3));
printf("%s locations named \"potomac river\"; the first %d: %s\n", $page->total ?? '?', count($page), implode('; ', array_map(static fn ($l) => $l->label, $page->items)));

POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA (usgs.site:USGS-01646500): 38.949777777778,-77.127638888889, drainage 11560 mi², 65 series kept
POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA (USGS-01646500) (ft^3/s), daily means: 5480, 4820, 4260, 3790, 3500, 3230, 
? locations named "potomac river"; the first 3: NORTH BRANCH POTOMAC RIVER NEAR KEMPTON, MD; NORTH BRANCH POTOMAC RIVER NEAR WILSON, MD; NORTH BRANCH POTOMAC RIVER AT WILSON, MD

(as answered on 2026-10-27, without a key; the 26th's daily mean was not published yet: a null, the last value of the list)

# config/packages/omnilab.yaml
omnilab:
    sources:
        water: { factory: usgs-water, options: { mailto: '%env(OMNILAB_MAILTO)%', api_key: '%env(default::USGS_WATER_API_KEY)%' } }

Errors

Every call goes through HttpSource: a 404 or a 410 (and a 204) is null - an empty page for a list -; a 429 is a RateLimitedException (retryAfter from Retry-After); a 5xx, a time-out or a host that does not answer an UnavailableException; any other 4xx a ProviderException with its status and what the service said; an answer that is not JSON a ProviderException, a web page answered for JSON an UnavailableException.

Before any call (NotSupportedException): a variable that is neither served nor a parameter code of five digits, an aggregation the daily statistics do not have, a box, a station of another scheme. A series that would take more than fifty pages of 50,000 values is a ProviderException ("narrow the period"). An unknown location is the API's 404, null.

Verified, and not

Against the real APIs on 2026-10-15: the Potomac River near Washington at Little Falls by its id, its number and its page (11,560 mi², 37.04 ± 0.17 ft NAVD88, 65 series kept, its daily discharge since 1930-03-01); an unknown location (404, null); its discharge and gage height on 2026-10-14 hourly in one call (14,000 to 24,300 ft³/s, 4.38 to 5.26 ft), every five minutes (288 values), the hours' maxima; its daily mean discharge from 2026-10-01 to 10-07 (2,650 to 1,610 ft³/s, answered out of order); a point beside it giving it as the nearest location with discharge; a search by name, two pages by the cursor. The fixtures in Tests/Fixtures/ are its answers.

Again on 2026-10-27: the Potomac at Little Falls by its id (65 series kept), its daily mean discharge from 10-20 to 10-26, a search by name (the example above).

Not verified: a key (none created) and the rate limits (no 429 met; without a key the answers carried no X-RateLimit-* header); a series of more than 50,000 values (the next link is followed as the API's documentation shows).

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by the U.S. Geological Survey. Its water data are in the U.S. public domain; credit the USGS ("U.S. Geological Survey, Water Data for the Nation"); recent values are provisional, as the README's Terms of use says. Whoever runs the package is responsible for any use made of what it returns: see the README's Responsibility section.