Data.EBird.API

A description of the eBird API as a servant API type.

Intended for use by those who wish to write their own clients for the eBird API using servant-client.

If you are interested in querying the eBird API using an existing client, check out the ebird-client library.

Servant API types

Note: The individual endpoint types are only exported for those who wish to implement partial clients for the eBird API. Comprehensive client implementations should use the EBirdAPI type.

Top-level API

type EBirdAPI = RecentObservationsAPI :<|> (RecentNotableObservationsAPI :<|> (RecentSpeciesObservationsAPI :<|> (RecentNearbyObservationsAPI :<|> (RecentNearbySpeciesObservationsAPI :<|> (RecentNearestSpeciesObservationsAPI :<|> (RecentNearbyNotableObservationsAPI :<|> (HistoricalObservationsAPI :<|> (RecentChecklistsAPI :<|> (Top100API :<|> (ChecklistFeedAPI :<|> (RegionalStatisticsAPI :<|> (SpeciesListAPI :<|> (ViewChecklistAPI :<|> (RegionHotspotsAPI :<|> (NearbyHotspotsAPI :<|> (HotspotInfoAPI :<|> (TaxonomyAPI :<|> (TaxonomicFormsAPI :<|> (TaxaLocaleCodesAPI :<|> (TaxonomyVersionsAPI :<|> (TaxonomicGroupsAPI :<|> (RegionInfoAPI :<|> (SubregionListAPI :<|> AdjacentRegionsAPI)))))))))))))))))))))))

The eBird API as a Haskell type.

type WithAPIKey = Header' '[Required] "x-ebirdapitoken" Text

Convenient synonym for requiring an x-ebirdapitoken on a route

Observations APIs

These endpoints can be found under the data/obs section of the eBird API documentation.

type RecentObservationsAPI = "v2" :> ("data" :> ("obs" :> (WithAPIKey :> (Capture "regionCode" RegionCode :> ("recent" :> (QueryParam "back" Integer :> (QueryParam "cat" TaxonomyCategories :> (QueryParam "hotspot" Bool :> (QueryParam "includeProvisional" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "r" RegionCode :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [Observation 'Simple]))))))))))))

Recent observations within a region. Note that this endpoint only ever returns Simple detail observations.

See the eBird API documentation for this route.

type RecentNotableObservationsAPI = "v2" :> ("data" :> ("obs" :> (WithAPIKey :> (Capture "regionCode" RegionCode :> ("recent" :> ("notable" :> (QueryParam "back" Integer :> (QueryParam "detail" DetailLevel :> (QueryParam "hotspot" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "r" RegionCode :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [SomeObservation]))))))))))))

Recent notable observations within a region. Since this endpoint can return both Simple and Full detail observations, depending on the value provided for the "detail" query parameter, we existentially quantify the detail level of the resulting observations.

See the eBird API documentation for this route.

type RecentSpeciesObservationsAPI = "v2" :> ("data" :> ("obs" :> (WithAPIKey :> (Capture "regionCode" RegionCode :> ("recent" :> (Capture "speciesCode" SpeciesCode :> (QueryParam "back" Integer :> (QueryParam "hotspot" Bool :> (QueryParam "includeProvisional" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "r" RegionCode :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [Observation 'Simple]))))))))))))

Recent observations of a species within a region. Note that this endpoint only ever returns Simple detail observations.

See the eBird API documentation for this route.

type RecentNearbyObservationsAPI = "v2" :> ("data" :> ("obs" :> ("geo" :> ("recent" :> (WithAPIKey :> (QueryParam' '[Required] "lat" Double :> (QueryParam' '[Required] "lng" Double :> (QueryParam "dist" Integer :> (QueryParam "back" Integer :> (QueryParam "cat" TaxonomyCategories :> (QueryParam "hotspot" Bool :> (QueryParam "includeProvisional" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "sort" SortObservationsBy :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [Observation 'Simple])))))))))))))))

Recent observations within some radius of some latitude/longitude.

See the eBird API documentation for this route.

type RecentNearbySpeciesObservationsAPI = "v2" :> ("data" :> ("obs" :> ("geo" :> ("recent" :> (WithAPIKey :> (Capture "species" SpeciesCode :> (QueryParam' '[Required] "lat" Double :> (QueryParam' '[Required] "lng" Double :> (QueryParam "dist" Integer :> (QueryParam "back" Integer :> (QueryParam "cat" TaxonomyCategories :> (QueryParam "hotspot" Bool :> (QueryParam "includeProvisional" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "sort" SortObservationsBy :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [Observation 'Simple]))))))))))))))))

Recent observations of a species within some radius of some latitude/longitude.

See the eBird API documentation for this route.

type RecentNearestSpeciesObservationsAPI = "v2" :> ("data" :> ("nearest" :> ("geo" :> ("recent" :> (WithAPIKey :> (Capture "species" SpeciesCode :> (QueryParam' '[Required] "lat" Double :> (QueryParam' '[Required] "lng" Double :> (QueryParam "dist" Integer :> (QueryParam "back" Integer :> (QueryParam "hotspot" Bool :> (QueryParam "includeProvisional" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [Observation 'Simple]))))))))))))))

Nearest recent observations including a species.

See the eBird API documentation for this route.

type RecentNearbyNotableObservationsAPI = "v2" :> ("data" :> ("obs" :> ("geo" :> ("recent" :> ("notable" :> (WithAPIKey :> (QueryParam' '[Required] "lat" Double :> (QueryParam' '[Required] "lng" Double :> (QueryParam "dist" Integer :> (QueryParam "detail" DetailLevel :> (QueryParam "back" Integer :> (QueryParam "hotspot" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [SomeObservation]))))))))))))))

Recent notable observations of a within some radius of some latitude/longitude.

See the eBird API documentation for this route.

type HistoricalObservationsAPI = "v2" :> ("data" :> ("obs" :> (WithAPIKey :> (Capture "regionCode" RegionCode :> ("historic" :> (Capture "year" Integer :> (Capture "month" Integer :> (Capture "day" Integer :> (QueryParam "cat" TaxonomyCategories :> (QueryParam "detail" DetailLevel :> (QueryParam "hotspot" Bool :> (QueryParam "includeProvisional" Bool :> (QueryParam "maxResults" Integer :> (QueryParam "rank" SelectObservation :> (QueryParam "r" RegionCode :> (QueryParam "sppLocale" SPPLocale :> Get '[JSON] [SomeObservation]))))))))))))))))

A list of all observations for each taxa seen in some RegionCode on a specific date. The specific observations returned are determined by the rank parameter - first observation of the species (SelectFirstObservation, default) or last observation (SelectLastObservation).

See the eBird API documentation for this route.

Product APIs

These endpoints can be found under the product section of the eBird API documentation.

type RecentChecklistsAPI = "v2" :> ("product" :> ("lists" :> (WithAPIKey :> (Capture "regionCode" RegionCode :> (QueryParam "maxResults" Integer :> Get '[JSON] [ChecklistFeedEntry])))))

A list of recent checklists submitted in a region.

See the eBird API documentation for this route.

type Top100API = "v2" :> ("product" :> ("top100" :> (WithAPIKey :> (Capture "regionCode" Region :> (Capture "year" Integer :> (Capture "month" Integer :> (Capture "day" Integer :> (QueryParam "rankedBy" RankTop100By :> (QueryParam "maxResults" Integer :> Get '[JSON] [Top100ListEntry])))))))))

A list of the top 100 contributors on a given date, ranked by species count or checklist count.

See the eBird API documentation for this route.

type ChecklistFeedAPI = "v2" :> ("product" :> ("lists" :> (WithAPIKey :> (Capture "regionCode" Region :> (Capture "year" Integer :> (Capture "month" Integer :> (Capture "day" Integer :> (QueryParam "sortKey" SortChecklistsBy :> (QueryParam "maxResults" Integer :> Get '[JSON] [ChecklistFeedEntry])))))))))

A list of checklists submitted in a region on a date.

See the eBird API documentation for this route.

type RegionalStatisticsAPI = "v2" :> ("product" :> ("stats" :> (WithAPIKey :> (Capture "regionCode" Region :> (Capture "year" Integer :> (Capture "month" Integer :> (Capture "day" Integer :> Get '[JSON] RegionalStatistics)))))))

A list of checklists submitted on a date.

See the eBird API documentation for this route.

type SpeciesListAPI = "v2" :> ("product" :> ("spplist" :> (WithAPIKey :> (Capture "regionCode" Region :> Get '[JSON] [SpeciesCode]))))

A list of all species ever seen in a region.

See the eBird API documentation for this route.

type ViewChecklistAPI = "v2" :> ("product" :> ("checklist" :> ("view" :> (WithAPIKey :> (Capture "subId" Text :> Get '[JSON] Checklist)))))

The details and observations for a checklist.

See the eBird API documentation for this route.

Hotspot APIs

These endpoints can be found under the ref/hotspot section of the eBird API documentation.

type RegionHotspotsAPI = "v2" :> ("ref" :> ("hotspot" :> (Capture "regionCode" RegionCode :> (QueryParam "back" Integer :> (QueryParam "fmt" CSVOrJSONFormat :> Get '[JSON] [Hotspot])))))

The hotspots within a list of one or more regions.

NOTE: This endpoint switches the content type of the response based on a query parameter, not an "Accept" header, and for some reason it chooses to make the default content type CSV. Any client for this endpoint should hardcode the "fmt" parameter to JSONFormat.

See the eBird API documentation for this route.

type NearbyHotspotsAPI = "v2" :> ("ref" :> ("hotspot" :> ("geo" :> (QueryParam' '[Required] "lat" Double :> (QueryParam' '[Required] "lng" Double :> (QueryParam "back" Integer :> (QueryParam "dist" Integer :> (QueryParam "fmt" CSVOrJSONFormat :> Get '[JSON] [Hotspot]))))))))

The hotspots within a radius of some latitude/longitude.

NOTE: This endpoint switches the content type of the response based on a query parameter, not an "Accept" header, and for some reason it chooses to make the default content type CSV. Any client for this endpoint should hardcode the "fmt" parameter to JSONFormat.

See the eBird API documentation for this route.

type HotspotInfoAPI = "v2" :> ("ref" :> ("hotspot" :> ("info" :> (Capture "locId" Text :> Get '[JSON] LocationData))))

Information about a hotspot.

See the eBird API documentation for this route.

Taxonomy APIs

These endpoints can be found under the ref/taxonomy section of the eBird API documentation.

type TaxonomyAPI = "v2" :> ("ref" :> ("taxonomy" :> ("ebird" :> (QueryParam "cat" TaxonomyCategories :> (QueryParam "fmt" CSVOrJSONFormat :> (QueryParam "locale" SPPLocale :> (QueryParam "species" SpeciesCodes :> (QueryParam "version" Text :> Get '[JSON] [Taxon]))))))))

The eBird taxonomy, in part or in full.

NOTE: This endpoint switches the content type of the response based on a query parameter, not an "Accept" header, and for some reason it chooses to make the default content type CSV. Any client for this endpoint should hardcode the "fmt" parameter to JSONFormat.

See the eBird API documentation for this route.

type TaxonomicFormsAPI = "v2" :> ("ref" :> ("taxon" :> ("forms" :> (WithAPIKey :> (Capture "speciesCode" SpeciesCode :> Get '[JSON] SpeciesCodes)))))

The list of subspecies of a given species recognized in the taxonomy.

See the eBird API documentation for this route.

type TaxaLocaleCodesAPI = "v2" :> ("ref" :> ("taxa-locales" :> ("ebird" :> (WithAPIKey :> (Header "Accept-Language" SPPLocale :> Get '[JSON] [SPPLocaleListEntry])))))

The supported locale codes and names for species common names.

See the eBird API documentation for this route.

type TaxonomyVersionsAPI = "v2" :> ("ref" :> ("taxonomy" :> ("versions" :> Get '[JSON] [TaxonomyVersionListEntry])))

The complete list of taxonomy versions, with a flag indicating which is the latest.

See the eBird API documentation for this route.

type TaxonomicGroupsAPI = "v2" :> ("ref" :> ("sppgroup" :> (Capture "speciesGrouping" SPPGrouping :> (QueryParam "groupNameLocale" SPPLocale :> Get '[JSON] [TaxonomicGroupListEntry]))))

The list of species groups, e.g. terns, finches, etc.

See the eBird API documentation for this route.

Region APIs

These endpoints can be found under the ref/region section of the eBird API documentation, except for the AdjacentRegionsAPI, which would be under the ref/geo section of the eBird API documentation.

type RegionInfoAPI = "v2" :> ("ref" :> ("region" :> ("info" :> (WithAPIKey :> (Capture "regionCode" Region :> (QueryParam "regionNameFormat" RegionNameFormat :> Get '[JSON] RegionInfo))))))

Get a RegionInfo for a Region.

See the eBird API documentation for this route.

type SubregionListAPI = "v2" :> ("ref" :> ("region" :> ("list" :> (WithAPIKey :> (Capture "regionType" RegionType :> (Capture "regionCode" RegionCode :> Get '[JSON] [RegionListEntry]))))))

Get a list of subregions of a certain RegionType within a RegionCode.

See the eBird API documentation for this route.

type AdjacentRegionsAPI = "v2" :> ("ref" :> ("adjacent" :> (WithAPIKey :> (Capture "regionCode" Region :> Get '[JSON] [RegionListEntry]))))

Adjacent regions to a given region. Only Subnational2 region codes in the United States, New Zealand, or Mexico are currently supported.

See the eBird API documentation for this route.

eBird checklists

module Data.EBird.API.Checklists

eBird observations

module Data.EBird.API.Observations

eBird products

module Data.EBird.API.Product

eBird hotspots

module Data.EBird.API.Hotspots

eBird regions

module Data.EBird.API.Regions

eBird taxonomy

module Data.EBird.API.Taxonomy

Date and time utilities

module Data.EBird.API.Util.Time

EBirdString class

module Data.EBird.API.EBirdString