omnilab/usgs Référence de l’API

Omnilab\Usgs

UsgsSource class

final class UsgsSource extends HttpSource UsgsSource.php:37

The USGS earthquake catalogue (ComCat), through its FDSN event web service (earthquake.usgs.gov/fdsnws/event/1): an event by its id (us7000pn9s) - its magnitude and type, place, depth, time, the felt reports and intensities, the tsunami flag, PAGER's alert level - and, over a box or around a point for a period, the earthquakes as series (their count per step; each one's magnitude or depth, or the step's maximum, mean...) or as occurrences, each an entity with its time and its place, one page at a time (occurrences()).

No key. One call per entity, per series query (every variable asked at once), per page of occurrences. The service answers at most 20,000 events a query (a page: as many).

const BASE_URI = 'https://earthquake.usgs.gov/fdsnws/event/1/'

const MAX_EVENTS = 20000

The most events one query answers: more is a 400 from the service.

const VARIABLES = ['count' => null, 'magnitude' => null, 'depth' => 'km']

The variables series() serves, with their unit.

const SORTS = [OccurrenceQuery::NEWEST => 'time', OccurrenceQuery::OLDEST => 'time-asc', 'magnitude' => 'magnitude', 'magnitude-asc' => 'magnitude-asc']

How occurrences() sorts: the query's sort, the service's orderby.

const ALERTS = ['green', 'yellow', 'orange', 'red']

PAGER's alert levels, the "alert" filter of occurrences().

UsgsSource::__construct()

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

$radius

the radius around a Point, in kilometres, for series() and for occurrences() when the query gives none

$minMagnitude

the smallest magnitude series() and occurrences() count when the query says none (null: every event the catalogue has)

UsgsSource::getName()

public function getName(): string

UsgsSource::capabilities()

public function capabilities(): array

UsgsSource::entity()

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

An event by its ComCat id (us7000pn9s, an alias such as at00sttln4) or its event page.

UsgsSource::series()

public function series(SeriesQuery $query): array

The earthquakes over the place for the period, as series, one per variable asked:

• "count": how many events each step (SeriesQuery::DAILY, HOURLY or another ISO 8601 duration), from the start of the period;
• "magnitude", "depth": each event's value at its time (no aggregation: an irregular series), or the step's MAX, MIN, MEAN or SUM.

A BBox is the box; a Point, the circle of the configured radius around it. The period defaults to the last 30 days; a date without a time is the whole day, in the query's time zone (UTC by default).

UsgsSource::occurrences()

public function occurrences(OccurrenceQuery $query): Page

The seismic events over the place for the period, each an entity with its time and its place, one page at a time - what the catalogue's list gives, without an event's products (entity() reads those: the uncertainties, the region, PAGER's review).

A BBox is the box (across the antimeridian too); a Point, the circle of the query's radius around it (the configured one by default); no place, the world. A period's end left out is open: from the catalogue's first event, up to now; a date without a time is its whole day, in UTC. Filters: OccurrenceQuery::MIN_MAGNITUDE (the configured one by default), MAX_MAGNITUDE, KIND (the event type, or a list: "earthquake", "quarry blast", "explosion"...) and "alert" (PAGER's level, or a list: green, yellow, orange, red). Sorts: newest (the service's default), oldest, magnitude (the largest first), magnitude-asc. Up to 20,000 a page; no total (the count would cost a call more).

UsgsSource::events()

public function events(Point|BBox $place, ?\DateTimeInterface $from = null, ?\DateTimeInterface $to = null, ?float $minMagnitude = null, int $limit = 100, string $orderBy = 'time'): array

since omnilab/usgs 1.x: use occurrences(), the contract's query by place and period - this answers its first page, the period 30 days back from its end by default, as before

The earthquakes over the place for the period, as entities.

$limit

the most events (the service's cap: 20,000)

$orderBy

"time" (newest first), "time-asc", "magnitude" (largest first), "magnitude-asc"

UsgsSourceFactory class

final class UsgsSourceFactory extends SourceFactory UsgsSourceFactory.php:21

The USGS earthquake catalogue: an event by its id, and the earthquakes of a place and a period as series or as occurrences - no key needed.

options: mailto: 'support@glitchr.io' # in the User-Agent radius_km: 100 # the circle around a Point, for series(), and for occurrences() when a query gives none min_magnitude: null # the smallest magnitude counted when a query says none (null: every event, down to the microquakes some networks report) throttle: 0 # seconds between two calls: the USGS publishes no figure base_uri: 'https://earthquake.usgs.gov/fdsnws/event/1/'

Options