| Copyright | (c) 2023 Finley McIlwaine |
|---|---|
| License | MIT (see LICENSE) |
| Maintainer | Finley McIlwaine <finleymcilwaine@gmail.com> |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Data.EBird.Client
Description
Synopsis
- askEBird :: ClientM a -> IO (Either ClientError a)
- recentObservations :: Text -> RegionCode -> RecentObservationsParams -> ClientM [Observation 'Simple]
- recentNotableObservations :: Text -> RegionCode -> RecentNotableObservationsParams -> ClientM [SomeObservation]
- recentNearbyObservations :: Text -> Double -> Double -> RecentNearbyObservationsParams -> ClientM [Observation 'Simple]
- recentNearbySpeciesObservations :: Text -> SpeciesCode -> Double -> Double -> RecentNearbySpeciesObservationsParams -> ClientM [Observation 'Simple]
- recentNearestSpeciesObservations :: Text -> SpeciesCode -> Double -> Double -> RecentNearestSpeciesObservationsParams -> ClientM [Observation 'Simple]
- recentNearbyNotableObservations :: Text -> Double -> Double -> RecentNearbyNotableObservationsParams -> ClientM [SomeObservation]
- historicalObservations :: Text -> RegionCode -> EBirdDate -> HistoricalObservationsParams -> ClientM [SomeObservation]
- recentChecklists :: Text -> RegionCode -> RecentChecklistsParams -> ClientM [ChecklistFeedEntry]
- top100 :: Text -> Region -> EBirdDate -> Top100Params -> ClientM [Top100ListEntry]
- checklistFeed :: Text -> Region -> EBirdDate -> ChecklistFeedParams -> ClientM [ChecklistFeedEntry]
- regionalStatistics :: Text -> Region -> EBirdDate -> ClientM RegionalStatistics
- speciesList :: Text -> Region -> ClientM [SpeciesCode]
- viewChecklist :: Text -> Text -> ClientM Checklist
- regionHotspots :: RegionCode -> RegionHotspotsParams -> ClientM [Hotspot]
- nearbyHotspots :: Double -> Double -> NearbyHotspotsParams -> ClientM [Hotspot]
- hotspotInfo :: Text -> ClientM LocationData
- taxonomy :: TaxonomyParams -> ClientM [Taxon]
- taxonomicForms :: Text -> SpeciesCode -> ClientM SpeciesCodes
- taxaLocaleCodes :: Text -> TaxaLocaleCodesParams -> ClientM [SPPLocaleListEntry]
- taxonomyVersions :: ClientM [TaxonomyVersionListEntry]
- taxonomicGroups :: SPPGrouping -> TaxonomicGroupsParams -> ClientM [TaxonomicGroupListEntry]
- regionInfo :: Text -> Region -> RegionInfoParams -> ClientM RegionInfo
- subregionList :: Text -> RegionType -> RegionCode -> ClientM [RegionListEntry]
- adjacentRegions :: Text -> Region -> ClientM [RegionListEntry]
- module Data.EBird.Client.Generated
- data ClientError
Execute client functions
askEBird :: ClientM a -> IO (Either ClientError a) Source #
Send a request to the official eBird API.
eBird API client functions
Observations queries
Arguments
| :: Text | eBird API key |
| -> RegionCode | Region(s) to get observations from |
| -> RecentObservationsParams | Optional parameters default: |
| -> ClientM [Observation 'Simple] |
Get a list of recent observations within a region. Results only include the most recent observation for each species in the region.
For example, get up to 10 recent observations from the last 5 days in Park
County, Wyoming (using -XOverloadedLabels and -XOverloadedStrings):
askEBird $
recentObservations key
"US-WY-029"
(def & #maxResults ?~ 10 & #back ?~ 5)
See the eBird API documentation for the corresponding endpoint.
recentNotableObservations Source #
Arguments
| :: Text | eBird API key |
| -> RegionCode | Region(s) to get observations from |
| -> RecentNotableObservationsParams | Optional parameters |
| -> ClientM [SomeObservation] |
Get a list of recent notable observations within a region. Results only include the most recent observation for each species in the region.
For example, get up to 10 recent notable observations from the last 30 days
in Park County, Wyoming (using -XOverloadedLabels and
-XOverloadedStrings):
askEBird $
recentNotableObservations key
"US-WY-029"
(def & #maxResults ?~ 10 & #back ?~ 30)
See the eBird API documentation for the corresponding endpoint.
recentNearbyObservations Source #
Arguments
| :: Text | eBird API key |
| -> Double | Latitude of the location to get observations near |
| -> Double | Longitude of the location to get observations near |
| -> RecentNearbyObservationsParams | Optional parameters |
| -> ClientM [Observation 'Simple] |
Get a list of recent observations within some radius of some latitude/longitude.
For example, get up to 5 nearby observations within 10km of Cody, Wyoming
(using -XOverloadedLabels and -XOverloadedStrings):
askEBird $
recentNearbyObservations key
44.526340 (-109.056534)
(def & #maxResults ?~ 5 & #radius ?~ 10)
See the eBird API documentation for the corresponding endpoint.
recentNearbySpeciesObservations Source #
Arguments
| :: Text | eBird API key |
| -> SpeciesCode | Species to get observations of (e.g. "bohwax" for Bohemian Waxwing) |
| -> Double | Latitude of the location to get observations near |
| -> Double | Longitude of the location to get observations near |
| -> RecentNearbySpeciesObservationsParams | Optional parameters |
| -> ClientM [Observation 'Simple] |
Get a list of recent observations of a species within some radius of some latitude/longitude.
For example, get up to 5 nearby observations of Peregrine Falcons within 50km
of Cody, Wyoming (using -XOverloadedLabels and -XOverloadedStrings):
askEBird $
recentNearbySpeciesObservations key
"perfal"
44.526340 (-109.056534)
(def & #radius ?~ 50 & #maxResults ?~ 5)
See the eBird API documentation for the corresponding endpoint.
recentNearestSpeciesObservations Source #
Arguments
| :: Text | eBird API key |
| -> SpeciesCode | Species to get observations of (e.g. "bohwax" for Bohemian Waxwing) |
| -> Double | Latitude of the location to get observations near |
| -> Double | Longitude of the location to get observations near |
| -> RecentNearestSpeciesObservationsParams | Optional parameters |
| -> ClientM [Observation 'Simple] |
Get a list of recent observations of some species nearest to some latitude/longitude.
For example, get the 5 nearest observations of Black-throated Gray Warblers
within 50km of Capitol Reef National Park (using -XOverloadedLabels and
-XOverloadedStrings):
askEBird $
recentNearestSpeciesObservations key
"btywar"
38.366970 (-111.261504)
(def & #radius ?~ 50 & #maxResults ?~ 5)
See the eBird API documentation for the corresponding endpoint.
recentNearbyNotableObservations Source #
Arguments
| :: Text | eBird API key |
| -> Double | Latitude of the location to get observations near |
| -> Double | Longitude of the location to get observations near |
| -> RecentNearbyNotableObservationsParams | Optional parameters |
| -> ClientM [SomeObservation] |
Get a list of recent notable observations of some near some latitude/longitude.
For example, get 5 notable observations within 25km of Capitol Reef National
Park (using -XOverloadedLabels and -XOverloadedStrings):
askEBird $
recentNearbyNotableObservations key
38.366970 (-111.261504)
(def & #radius ?~ 25 & #maxResults ?~ 5)
See the eBird API documentation for the corresponding endpoint.
historicalObservations Source #
Arguments
| :: Text | eBird API key |
| -> RegionCode | Region(s) to get observations from |
| -> EBirdDate | Date to get observations on, from year 1800 to present |
| -> HistoricalObservationsParams | Optional parameters default: |
| -> ClientM [SomeObservation] |
Get a list of observations for each species seen on a specific date.
For example, get a list of 10 fully detailed observations for each species
seen on July 11th, 2023 in Park County, Wyoming (using -XOverloadedLabels
and -XOverloadedStrings):
askEBird $
historicalObservations key
"US-WY-029"
"2023-07-11"
(def & #maxResults ?~ 10 & #detail ?~ Full)
See the eBird API documentation for the corresponding endpoint.
Product queries
Arguments
| :: Text | eBird API key |
| -> RegionCode | Region(s) to get Checklists from |
| -> RecentChecklistsParams | Optional parameters default: |
| -> ClientM [ChecklistFeedEntry] |
Get a list recently submitted checklists within a region.
For example, get up to 3 recent checklists submitted in Park County, Wyoming
(using -XOverloadedLabels and -XOverloadedStrings):
askEBird $
recentChecklists key
"US-WY-029"
(def & #maxResults ?~ 3)
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Text | eBird API key |
| -> Region | Region to fetch the ranking for Note: Only country, subnational1, or location regions are supported for this endpoint of the eBird API. |
| -> EBirdDate | Date to get the top 100 on |
| -> Top100Params | Optional parameters default: |
| -> ClientM [Top100ListEntry] |
Get a list of top contributors for a region on a specific date, ranked by number of species observed or number of checklists submitted.
For example, get the top 10 contributors by number of species observed on
July 11th, 2023 in Wyoming (using -XOverloadedLabels and
-XOverloadedStrings):
askEBird $
top100 key
"US-WY"
"2023-07-11"
(def & #maxResults ?~ 10)
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Text | eBird API key |
| -> Region | Region to fetch the checklist feed for |
| -> EBirdDate | Date to get the checklist feed on |
| -> ChecklistFeedParams | Optional parameters default: |
| -> ClientM [ChecklistFeedEntry] |
Get a list of checklists submitted within a region on a specific date.
For example, get a feed of 10 checklists submitted in Park County, Wyoming on
July 11th, 2023 (using -XOverloadedLabels and -XOverloadedStrings):
askEBird $
checklistFeed key
"US-WY-029"
"2023-07-11"
(def & #maxResults ?~ 10)
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Text | eBird API key |
| -> Region | Region to fetch the statistics for |
| -> EBirdDate | Date to get the statistics on |
| -> ClientM RegionalStatistics |
Get the RegionalStatistics for a region on a specific date.
For example, get the statistics for Wyoming on July 11th, 2023 (using
-XOverloadedStrings):
askEBird $
regionalStatistics key
"US-WY"
"2023-07-11"
See the eBird API documentation for the corresponding endpoint.
Get a list of all species ever seen in a Region.
For example, get all species ever seen in Park County, Wyoming (using
-XOverloadedStrings):
askEBird $ speciesList key "US-WY-029"
Note that the endpoint for this query is simple enough that speciesList is
equivalent to the generated speciesList_.
See the eBird API documentation for the corresponding endpoint.
Get information about a checklist.
For example, get information for a checklist with submission ID
"S144646447" (using -XOverloadedStrings):
askEBird $ viewChecklist key S144646447
Note that the endpoint for this query is simple enough that viewChecklist
is equivalent to the generated viewChecklist_.
See the eBird API documentation for the corresponding endpoint.
Hotspot queries
Arguments
| :: RegionCode | Region(s) to get hotspots in |
| -> RegionHotspotsParams | Optional parameters default: |
| -> ClientM [Hotspot] |
Get all hotspots in a list of one or more regions (RegionCode).
For example, get the hotspots in Albany County, Wyoming and Park County,
Wyoming that have been visited in the last 5 days (using -XOverloadedLabels
and -XOverloadedStrings):
askEBird $ regionHotspots "US-WY-001,US-WY-029" (def & #back ?~ 5)
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Double | Latitude of the location to get hotspots near |
| -> Double | Longitude of the location to get hotspots near |
| -> NearbyHotspotsParams | Optional parameters default: |
| -> ClientM [Hotspot] |
Get all hotspots within a radius of some latitude/longitude.
For example, get the hotspots within 30km of Cody, Wyoming that have been
visited in the last 5 days (using -XOverloadedLabels
and -XOverloadedStrings):
askEBird $
nearbyHotspots
44.526340 (-109.056534)
(def & #radius ?~ 30 & #back ?~ 5)
See the eBird API documentation for the corresponding endpoint.
Get information about a hotspot.
For example, get information for a hotspot with location ID
"L2373040" (using -XOverloadedStrings):
askEBird $ hotspotInfo L2373040
Note that the endpoint for this query is simple enough that hotspotInfo
is equivalent to the generated hotspotInfo_.
See the eBird API documentation for the corresponding endpoint.
Taxonomy queries
Arguments
| :: TaxonomyParams | Optional parameters default: |
| -> ClientM [Taxon] |
Get any version of the eBird taxonomy, with optional filtering based on taxonomy categories and species.
For example, get the taxa for species in the "hybrid" category:
askEBird $ taxonomy (def & #categories ?~ "hybrid")
See the eBird API documentation for the corresponding endpoint.
Get the list of subspecies of a given species recognized in the eBird taxonomy.
For example, get subspecies of Canada Goose (using
-XOverloadedStrings):
askEBird $ taxonomicForms key "cangoo"
Note that the endpoint for this query is simple enough that taxonomicForms
is equivalent to the generated taxonomicForms_.
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Text | eBird API key |
| -> TaxaLocaleCodesParams | Optional parameters default: |
| -> ClientM [SPPLocaleListEntry] |
Get the supported locale codes and names for species common names, with the last time they were updated.
For example:
askEBird $ taxaLocaleCodes key def
See the eBird API documentation for the corresponding endpoint.
taxonomyVersions :: ClientM [TaxonomyVersionListEntry] Source #
Get all versions of the taxonomy, with a flag indicating which is latest.
For example:
askEBird taxonomyVersions
Note that the endpoint for this query is simple enough that taxonomyVersions
is equivalent to the generated taxonomyVersions_.
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: SPPGrouping |
|
| -> TaxonomicGroupsParams | Optional parameters default: |
| -> ClientM [TaxonomicGroupListEntry] |
Get the list of species groups, in either Merlin or eBird grouping.
For example, get the taxonomic groups using eBird grouping order (using
-XOverloadedStrings):
askEBird $ taxonomicGroups "ebird" def
See the eBird API documentation for the corresponding endpoint.
Region queries
Arguments
| :: Text | eBird API key |
| -> Region | Region to get information for |
| -> RegionInfoParams | Optional parameters default: |
| -> ClientM RegionInfo |
Get a RegionInfo for an eBird region.
For example, get information about the Park County, Wyoming region (using
-XOverloadedLabels and -XOverloadedStrings):
askEBird $ regionInfo key "US-WY-029" def
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Text | eBird API key |
| -> RegionType | Type of subregions to fetch |
| -> RegionCode | Parent |
| -> ClientM [RegionListEntry] |
Get a list of subregions of a given region type within a given region.
Keep in mind that many combinations of subregion and parent region are
invalid, e.g. CountryType regions within "US-WY".
For example, get county sub regions of Wyoming (using -XOverloadedStrings):
askEBird $ subregionList key Subnational2Type "US-WY"
Note that the endpoint for this query is simple enough that subregionList
is equivalent to the generated subregionList_.
See the eBird API documentation for the corresponding endpoint.
Arguments
| :: Text | eBird API key |
| -> Region | Region to fetch the adjacent regions of |
| -> ClientM [RegionListEntry] |
Get a list of regions adjacent to a given region. Subnational2 region
codes are only currently supported in the United States, New Zealand, or
Mexico.
For example, get regions adjacent to Wyoming (using -XOverloadedStrings):
askEBird $ adjacentRegions key "US-WY"
Note that the endpoint for this query is simple enough that adjacentRegions
is equivalent to the generated adjacentRegions_.
See the eBird API documentation for the corresponding endpoint.
Less convenient, generated queries
module Data.EBird.Client.Generated
Convenient re-exports
data ClientError #
A type representing possible errors in a request
Note that this type substantially changed in 0.12.