omnilab/noaa API reference

Omnilab\Noaa

NoaaSource class

final class NoaaSource extends HttpSource NoaaSource.php:48

NOAA's weather and climate observations, as series at a point, through one of two APIs, each a source of its own ($api):

• NCEI (the default): the National Centers for Environmental Information's Access Data Service (www.ncei.noaa.gov/access/services/ data/v1), the station records of the whole world - GHCN-Daily by day, the Global Summary of the Month and of the Year - by the elements' own names (TMAX, TMIN, TAVG, PRCP, SNOW, SNWD, AWND...) in metric units, at the nearest station that has them over the period (its search service finds it), or at a GHCN station named in place of the point (Identifier ghcn:USW00094728);
• NWS: the National Weather Service's API (api.weather.gov), for a point of the United States: the observations of the nearest station (the last seven days) and the forecast of its 2.5 km grid (seven days ahead), joined when a period spans both, by the API's own names (temperature, dewpoint, relativeHumidity, windSpeed, quantitativePrecipitation...); at a station named in place of the point (nws.station:KNYC), that station's observations and the forecast of its grid.

A station is an entity too (entity()): its name, place and elevation, and for NCEI the period its records cover, each element's.

No key: both are open (NOAA's data are in the U.S. public domain). The NWS refuses a call without a User-Agent (403); the factory sends one. CDO v2, NCEI's older API, needs a token and serves the same datasets: it is not used.

const NCEI = 'ncei'

const NWS = 'nws'

const NCEI_URI = 'https://www.ncei.noaa.gov/access/services/'

const NWS_URI = 'https://api.weather.gov/'

const DATASETS = [SeriesQuery::DAILY => 'daily-summaries', 'P1M' => 'global-summary-of-the-month', 'P1Y' => 'global-summary-of-the-year']

NCEI's datasets, by the step that reads them.

const NCEI_UNITS = ['TMAX' => '°C', 'TMIN' => '°C', 'TAVG' => '°C', 'TOBS' => '°C', 'MNPN' => '°C', 'MXPN' => '°C', 'EMXT' => '°C', 'EMNT' => '°C', 'CLDD' => '°C', 'HTDD' => '°…

The units of NCEI's elements asked in metric (NCEI's documentation of GHCN-Daily and of the global summaries); an element not listed has no unit here (a count of days, a flag, a time).

const NCEI_DAILY_AGGREGATIONS = ['TMAX' => Series::MAX, 'TMIN' => Series::MIN, 'TAVG' => Series::MEAN, 'PRCP' => Series::SUM, 'SNOW' => Series::SUM, 'EVAP' => Series::SUM, 'AWND' => Series:…

What a day of GHCN-Daily's elements stands for.

const NWS_AMOUNTS = ['quantitativePrecipitation', 'snowfallAmount', 'iceAccumulation']

The NWS's amounts: a forecast interval's value is its total, given at its start (the other hours null).

const NWS_OBSERVATION_DAYS = 7

How far back the NWS keeps a station's observations, in days.

const NWS_PAGE = 500

The most observations the NWS answers a page.

NoaaSource::__construct()

public function __construct(HttpClientInterface $http, readonly string $api = self::NCEI, ?string $baseUri = null, readonly float $radius = 50.0, ?string $timezone = null, readonly ?string $now = null, array $headers = [], float $throttle = 0.0)

$api

NCEI or NWS

$radius

how far from a Point NCEI's nearest station is looked for, in kilometres

$now

the time taken for now (a test's), the real one when null

$timezone

the zone of the days and times when a query does not say: "local" (the NWS point's own zone; UTC for NCEI, whose days are the stations' own), "UTC", "America/New_York"...; null: local for the NWS, UTC for NCEI

NoaaSource::getName()

public function getName(): string

NoaaSource::capabilities()

public function capabilities(): array

NoaaSource::entity()

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

A station: NCEI's (ghcn:USW00094728) with the period its records cover and each element's, two calls; the NWS's (nws.station:KNYC), one. Null when unknown.

NoaaSource::series()

public function series(SeriesQuery $query): array

The series at a Point (the nearest station's records, or the NWS's grid) or at a station named in place of it (ghcn for NCEI, nws.station for the NWS). An unknown station: no series.

NoaaSource::seriesAt()

public function seriesAt(string $station, SeriesQuery $query): array

since omnilab/noaa 1.x: series() takes the station in place of the point, new SeriesQuery($variables, Identifier::of(Scheme::GHCN, $station), ...)

NCEI's series at a station named by its id.

NoaaSourceFactory class

final class NoaaSourceFactory extends SourceFactory NoaaSourceFactory.php:25

NOAA's observations as series: NCEI's station records of the world (api: ncei, the default) or the National Weather Service's observations and forecast for a point of the United States (api: nws, a source of its own) - no key.

options: api: ncei # or nws mailto: 'support@glitchr.io' # in the User-Agent, which the NWS requires radius_km: 50 # NCEI: how far from a Point the nearest station is looked for timezone: ~ # the zone of the days and times when a query does not say: local (the NWS point's own), UTC, America/New_York...; null: local for the NWS, UTC for NCEI throttle: 0 # seconds between two calls: neither API publishes a figure base_uri: ~ # https://www.ncei.noaa.gov/access/services/ (ncei), https://api.weather.gov/ (nws) now: ~ # the time taken for now (tests): the real one when not set

Options