ebird

package module
v0.0.0-...-ccec19e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 28, 2024 License: BSD-2-Clause Imports: 15 Imported by: 0

README

ebird

builds.sr.ht status godoc reference

Documentation

Index

Constants

View Source
const (
	// RegionNameOnly returns fetches the name
	RegionNameOnly = "nameonly"
	// RegionNameQual returns a qualified name
	RegionNameQual = "namequal"
	// RegionDetailed returns detailed information
	RegionDetailed = "detailed"
	// RegionDetailedNoQual returns unqualified detailed information
	RegionDetailedNoQual = "detailednoqual"
	// RegionRevDetailed returns ?? detailed information
	RegionRevDetailed = "revdetailed"
	// RegionFull returns all the information
	RegionFull = "full"
)
View Source
const (
	// RegionSubnational1 represents sub-national region
	RegionSubnational1 = "subnational1"
	// RegionSubnational2 represents a sub national region (2)
	RegionSubnational2 = "subnational2"
	// RegionCountry represents a country
	RegionCountry = "country"
)
View Source
const (
	// GroupMerlin puts like birds together, with Falcons next to Hawks.
	GroupMerlin = "merlin"
	// GroupEbird follows Taxonomic ordering more closely.
	GroupEbird = "ebird"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Checklist

type Checklist struct {
	AllObsReported bool    `json:"allObsReported"`
	ChecklistID    string  `json:"checklistId"`
	CreationDt     string  `json:"creationDt"`
	DurationHrs    float64 `json:"durationHrs"`
	LastEditedDt   string  `json:"lastEditedDt"`
	LocID          string  `json:"locId"`
	NumObservers   int64   `json:"numObservers"`
	Obs            []struct {
		HideFlags      []interface{} `json:"hideFlags"`
		HowManyAtleast int64         `json:"howManyAtleast"`
		HowManyAtmost  int64         `json:"howManyAtmost"`
		HowManyStr     string        `json:"howManyStr"`
		ObsAux         []struct {
			AuxCode         string `json:"auxCode"`
			EntryMethodCode string `json:"entryMethodCode"`
			FieldName       string `json:"fieldName"`
			ObsID           string `json:"obsId"`
			SpeciesCode     string `json:"speciesCode"`
			SubID           string `json:"subId"`
			Value           string `json:"value"`
		} `json:"obsAux"`
		ObsDt            string `json:"obsDt"`
		ObsID            string `json:"obsId"`
		Present          bool   `json:"present"`
		ProjID           string `json:"projId"`
		SpeciesCode      string `json:"speciesCode"`
		SubID            string `json:"subId"`
		Subnational1Code string `json:"subnational1Code"`
	} `json:"obs"`
	ObsDt                string `json:"obsDt"`
	ObsTimeValid         bool   `json:"obsTimeValid"`
	ProjID               string `json:"projId"`
	ProtocolID           string `json:"protocolId"`
	SubID                string `json:"subId"`
	SubmissionMethodCode string `json:"submissionMethodCode"`
	Subnational1Code     string `json:"subnational1Code"`
	UserDisplayName      string `json:"userDisplayName"`
}

Checklist is a single checklist for one or more users

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client accesses the eBird API

func NewClient

func NewClient(key string, httpClient *http.Client) (*Client, error)

NewClient creates and sets up a new client with an API key defined as key. If key is an empty string, The environment variable EBIRD_API_TOKEN is used as the API key.

func (*Client) AdjacentRegions

func (c *Client) AdjacentRegions(ctx context.Context, region string) ([]Region, error)

AdjacentRegions returns regions directly adjacent to a specific region

func (*Client) Checklist

func (c *Client) Checklist(ctx context.Context, id string) (Checklist, error)

Checklist retrieves a single checklist from ebird.

func (*Client) ChecklistFeed

func (c *Client) ChecklistFeed(ctx context.Context, region string, when time.Time, max int) ([]Feed, error)

ChecklistFeed returns a list of checklists for a specific region on a specific day. region must be a eBird locId or subnational 2 code, or ISO/eBird subnational1 or country code.

func (*Client) HistoricObs

func (c *Client) HistoricObs(ctx context.Context, region string, when time.Time, opts ObsOpts) ([]Obs, error)

HistoricObs return observations for a region on a specific day. Hour, minute, and second/sub-second values in when are ignored

func (*Client) HotspotInfo

func (c *Client) HotspotInfo(ctx context.Context, hotspot string) (HotspotInfo, error)

HotspotInfo returns metadata on a hotspot (including all Hotspot info), given a Hotspot LocationID.

func (*Client) NearbyHotspots

func (c *Client) NearbyHotspots(ctx context.Context, x, y float64) ([]Hotspot, error)

NearbyHotspots fetches hotspots near a given point in WGS84 (assumed) longitude and latitude.

func (*Client) NearestSpeciesObs

func (c *Client) NearestSpeciesObs(ctx context.Context, x, y float64, species string, opts ObsOpts) ([]Obs, error)

NearestSpeciesObs returns observations near a point for a specific species.

func (*Client) RecentChecklists

func (c *Client) RecentChecklists(ctx context.Context, region string, max int) ([]Checklist, error)

RecentChecklists returns a list of checklists for a given region.

func (*Client) RecentNearbyObs

func (c *Client) RecentNearbyObs(ctx context.Context, x, y float64, dist int, notable bool, locale string, opts ObsOpts) ([]Obs, error)

RecentNearbyObs returns observations within a distance of the point specified. If notable is true, then the notable endpoint is used.

func (*Client) RecentNearbySpeciesObs

func (c *Client) RecentNearbySpeciesObs(ctx context.Context, x, y float64, dist int, species string, opts ObsOpts) ([]Obs, error)

RecentNearbySpeciesObs returns the recent observations near a point given a distance for a specific species.

func (*Client) RecentRegionObs

func (c *Client) RecentRegionObs(ctx context.Context, region string, notable bool, opts ObsOpts) ([]Obs, error)

RecentRegionObs returns observations for a given region.

region can be any eBird locId or subnational2 code, or ISO/eBird subnational1 or country code.

RecentRegionObs respects the Back, Category, MaxResults, IncludeProvisional, Hotspot, and Region members of ObsOpts.

If notable is true, only notable results are returned.

func (*Client) RecentRegionSpeciesObs

func (c *Client) RecentRegionSpeciesObs(ctx context.Context, region, species string, opts ObsOpts) ([]Obs, error)

RecentRegionSpeciesObs returns observations for a given species within a region.

region can be any eBird locId or subnational2 code, or ISO/eBird subnational1 or country code.

species is any species code in the current eBird taxonomy.

RecentRegionSpeciesObs respects the Back, MaxResults, IncludeProvisional, Hotspot, and Region members of ObsOpts.

func (*Client) RegionHotspots

func (c *Client) RegionHotspots(ctx context.Context, region string) ([]Hotspot, error)

RegionHotspots fetches all the hotspots in the region specified.

func (*Client) RegionInfo

func (c *Client) RegionInfo(ctx context.Context, region string, format RegionFormat, delim string) (RegionInfo, error)

RegionInfo gets the name and codes for a specific region with format

func (*Client) RegionStats

func (c *Client) RegionStats(ctx context.Context, region string, when time.Time) (Stats, error)

RegionStats gives summary statistics for a region on a given day.

func (*Client) SpeciesList

func (c *Client) SpeciesList(ctx context.Context, region string) ([]string, error)

func (*Client) SubregionList

func (c *Client) SubregionList(ctx context.Context, regionType RegionType, parentRegion string) ([]Region, error)

SubregionList returns all sub-regions for a given region.

func (*Client) Taxonomy

func (c *Client) Taxonomy(ctx context.Context, species []string) ([]Taxa, error)

Taxonomy downloads the full or specific subsets of the eBird taxonomy. API key not required for CSV download.

func (*Client) TaxonomyForms

func (c *Client) TaxonomyForms(ctx context.Context, species string) ([]string, error)

TaxonomyForms returns all subspecific forms of a given taxa.

func (*Client) TaxonomyGroups

func (c *Client) TaxonomyGroups(ctx context.Context, group Group, locale string) ([]TaxaGroup, error)

TaxonomyGroups return taxonomic species groups. The results are in the orderd by group, and in the locale specified. Available locales are:

en (default) de en es_CU es_ES fr he pt tr

func (*Client) TaxonomyVersions

func (c *Client) TaxonomyVersions(ctx context.Context) ([]TaxaVersion, error)

TaxonomyVersions returns a list of all versions of the taxonomy, with a flag indicating which is the latest.

func (*Client) Top100

func (c *Client) Top100(ctx context.Context, region string, when time.Time, sort bool, max int) ([]User, error)

Top100 returns the top 100 users for a region. regionCode can be any eBird locId or ISO/eBird subnational1 or country code.

Note: Responses from live data, cached every 15 minutes

type Feed

type Feed struct {
	Loc struct {
		CountryCode      string  `json:"countryCode"`
		CountryName      string  `json:"countryName"`
		HierarchicalName string  `json:"hierarchicalName"`
		IsHotspot        bool    `json:"isHotspot"`
		Lat              float64 `json:"lat"`
		Latitude         float64 `json:"latitude"`
		Lng              float64 `json:"lng"`
		LocID            string  `json:"locId"`
		LocName          string  `json:"locName"`
		Longitude        float64 `json:"longitude"`
		Name             string  `json:"name"`
		Subnational1Code string  `json:"subnational1Code"`
		Subnational1Name string  `json:"subnational1Name"`
		Subnational2Code string  `json:"subnational2Code"`
		Subnational2Name string  `json:"subnational2Name"`
	} `json:"loc"`
	LocID           string `json:"locId"`
	NumSpecies      int64  `json:"numSpecies"`
	ObsDt           string `json:"obsDt"`
	ObsTime         string `json:"obsTime"`
	SubID           string `json:"subId"`
	UserDisplayName string `json:"userDisplayName"`
}

type Group

type Group string

Group determines which group order column is used for sorting.

type Hotspot

type Hotspot struct {
	CountryCode string `json:"countryCode"`
	// X is the longitude of the hotspot
	X float64 `json:"lng"`
	// Y is the latitude of the hotspot
	Y                float64 `json:"lat"`
	LocationID       string  `json:"locId"`
	LocationName     string  `json:"locName"`
	SubnationalCode1 string  `json:"subnational1Code"`
	SubnationalCode2 string  `json:"subnational2Code"`
}

Hotspot holds location information for eBird hotspots

type HotspotInfo

type HotspotInfo struct {
	Hotspot
	Name             string `json:"name"`
	CountryName      string `json:"countryName"`
	IsHotspot        bool   `json:"isHotspot"`
	HierarchacalName string `json:"hierarchicalName"`
}

HotspotInfo has all Hotspot data, plus some ancillary location information.

type Obs

type Obs struct {
	// CommonName is the name of the species observed
	CommonName string `json:"comName"`
	// ScientificName is the latin name of the species observed
	ScientificName string `json:"sciName"`
	// SpeciesCode is the ABA(?) species code
	SpeciesCode string `json:"speciesCode"`
	// HowMany is the number observed
	HowMany int64 `json:"howMany"`
	// Latitude of the observation
	Latitude float64 `json:"lat"`
	// Longitude of the observation
	Longitude float64 `json:"lng"`
	// LocID is the ebird location ID
	LocID string `json:"locId"`
	// LocName is the ebird location name
	LocName string `json:"locName"`
	// LocPrivate means the observation is private
	LocPrivate bool `json:"locationPrivate"`
	// ObsDT is the time of the observation
	ObsDT string `json:"obsDt"`
	// Reviewed designates if the observation has been reviewed
	Reviewed bool `json:"obsReviewed"`
	// Valid designates if the observation is valid
	Valid bool `json:"obsValid"`
}

Obs represents a single ebird observation

func (Obs) When

func (obs Obs) When() time.Time

When returns a true time.Time for the ObsDT which is marshalled/unmarshalled as a string.

type ObsOpts

type ObsOpts struct {
	// Back the number of days back to look for observations
	//
	// Default: 14
	// Min: 1
	// Max: 30
	// Query Parameter: back
	Back int

	// Category useful for limiting results to certain taxonomic categories.
	// Multiple categories may be comma-separated.
	//
	// Default: all categories
	// Categories: domestic,form,hybrid,intergrade,issf,slash,species,spuh
	// Query Parameter: cat
	Categories []string

	// MaxResults sets the maximum number of result rows to return in this
	// request; to get all results do not include this parameter by setting it to
	// zero or less.
	//
	// Default: no maximum
	// Minimum: 1
	// Maximum: 10000
	// Query Parametser: maxResults
	MaxResults int

	// IncludeProvisional set to true if you'd like flagged records that have not
	// yet been reviewed to be included in the results
	//
	// Default: false
	// Query Parameter: includeProv
	IncludeProv bool

	// HostspotsOnly set to true if results should be limited to sightings at
	// birding hotspots.
	//
	// Default: false
	// Query Parameter: hotspot
	HotspotsOnly bool

	// Region use ONLY if your regionCode is a locId, in order to specify
	// multiple locations. locIds may be comma-separated for simplicity. Maximum
	// 10 locIds.
	//
	// Maximum count: 10
	// QueryParameter: r
	Region []string
}

ObsOpts are common options for the data/obs API

type Region

type Region struct {
	Code string `json:"code"`
	Name string `json:"name"`
}

Region holds the name and the code for an eBird region

type RegionFormat

type RegionFormat string

RegionFormat specifies what data to return for a region

type RegionInfo

type RegionInfo struct {
	Bounds struct {
		MaxX float64 `json:"maxX"`
		MaxY float64 `json:"maxY"`
		MinX float64 `json:"minX"`
		MinY float64 `json:"minY"`
	} `json:"bounds"`
	Result string `json:"result"`
}

RegionInfo stores the MBR and name of a region

type RegionType

type RegionType string

RegionType specifies what type of region is being requested for SubregionList.

type Stats

type Stats struct {
	NumChecklists   int64 `json:"numChecklists"`
	NumContributors int64 `json:"numContributors"`
	NumSpecies      int64 `json:"numSpecies"`
}

Stats holds summary statistics for checklists.

type Taxa

type Taxa struct {
	ScientificName      string   `json:"sciName"`
	CommonName          string   `json:"comName"`
	SpeciesCode         string   `json:"speciesCode"`
	Category            string   `json:"category"`
	TaxaOrder           float64  `json:"taxonOrder"`
	CommonNameCodes     []string `json:"comNameCodes"`
	ScientificNameCodes []string `json:"sciNameCodes"`
	BandingCodes        []string `json:"bandingCodes"`
	Order               string   `json:"order"`
	FamilyCommon        string   `json:"familyComName"`
	FamilyScientific    string   `json:"familySciName"`
	ReportAs            string   `json:"reportAs"`
	Extinct             bool     `json:"extinct"`
	ExtinctYear         int      `json:"extinctYear"`
}

Taxa holds names and various metadata for bird species

func LoadTaxa

func LoadTaxa() ([]Taxa, error)

type TaxaGroup

type TaxaGroup struct {
	GroupName        string      `json:"groupName"`
	GroupOrder       int         `json:"groupOrder"`
	TaxonOrderBounds [][]float64 `json:"taxonOrderBounds"`
}

TaxaGroup represents taxanomic group names and orders.

type TaxaVersion

type TaxaVersion struct {
	AuthorityVersion float64 `json:"authorityVer"`
	Latest           bool    `json:"latest"`
}

TaxaVersion represents a taxonomy and a flag indicating if it is the latest.

type User

type User struct {
	// NumCompleteChecklists is always zero when checklistSort parameter is false.
	NumCompleteChecklists int `json:"numCompleteChecklists"`
	// NumSpecies is always zero when checklistSort parameter is true. Invalid
	// observations ARE included in this total.
	NumSpecies int `json:"numSpecies"`
	// ProfileHandle is the handle to reach it via ebird.org/ebird/profile, if
	// it's been enabled.
	ProfileHandle string `json:"profileHandle"`
	RowNum        int    `json:"rowNum"`
	DisplayName   string `json:"userDisplayName"`
	ID            string `json:"userId"`
}

User holds info related to a single ebird user

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL