omnilab/ebird API reference

Omnilab\Ebird

EbirdSource class

final class EbirdSource extends HttpSource EbirdSource.php:35

eBird (the Cornell Lab of Ornithology), through the eBird API 2.0 (api.ebird.org/v2): a bird taxon by its species code, in the eBird/Clements taxonomy - its scientific and common names (in a locale), category, taxonomic order, family, banding codes -, keyless; and, with the user's eBird API key, a taxon by its name, a search of names, a checklist by its id, and the recent observations around a point or in a region, or a region's observations of one day (occurrences()).

The key is the user's to obtain from eBird (ebird.org/api/keygen, with an eBird account, under eBird's API terms) and to pass as the "key" option: it is sent as X-eBirdApiToken. Without it, the calls that need it are refused before any call.

const BASE_URI = 'https://api.ebird.org/v2/'

const MAX_RADIUS_KM = 50

eBird's limits: a radius of 50 km, 30 days back, 10,000 observations a call.

const MAX_DAYS_BACK = 30

const MAX_RESULTS = 10000

const REGION = 'region'

eBird's own filter: a region code (a country, FR; a subnational one, US-NY; a county, US-NY-109).

const PROVISIONAL = 'provisional'

eBird's own filter: include the observations not yet reviewed (provisional); false by default.

EbirdSource::__construct()

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

EbirdSource::getName()

public function getName(): string

EbirdSource::capabilities()

public function capabilities(): array

EbirdSource::entity()

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

A taxon by its species code (amerob, ebird:amerob, its page), keyless; by its scientific or common name (the key: taxon/find, then the taxonomy); a checklist by its id (S123456789, the key). One call, two for a name.

EbirdSource::search()

public function search(Query $query): Page

eBird's search of names (ref/taxon/find, the one of its site's search box: common and scientific names, in the locale), its order, one page; the key. A domain other than taxonomy answers nothing.

EbirdSource::occurrences()

public function occurrences(OccurrenceQuery $query): Page

Observations, with the key. Around a Point (the query's radius, the configured one - 25 km - by default, 50 at most): eBird's recent observations (data/obs/geo/recent), back from now to the query's start, 30 days at most - the latest observation of each species at each location, not every one. In a region (filter "region": FR, US-NY): its recent observations likewise, or, when the period is one day (from and to on the same date), that day's (historic). Filters: OccurrenceQuery::TAXON (a species code: that species only), region, provisional. No BBox, no sort (eBird's order), one page.

EbirdSourceFactory class

final class EbirdSourceFactory extends SourceFactory EbirdSourceFactory.php:22

eBird: bird taxa by species code (keyless), and with the user's eBird API key, taxa by name, a search, checklists and observations.

options: key: '%env(EBIRD_API_KEY)%' # the user's eBird API key (ebird.org/api/keygen); none: the taxonomy only locale: en # the common names' language (eBird's locales: en, fr, es, de...) radius_km: 25 # the circle around a Point, for occurrences() when the query gives none (50 at most) mailto: 'support@glitchr.io' # in the User-Agent throttle: 0 base_uri: 'https://api.ebird.org/v2/'

Options