ebird

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 7, 2023 License: MIT Imports: 10 Imported by: 0

README

eBird client for Go

GoDoc

Overview

go-ebird is a Go client library designed for the eBird API. This library enables developers to seamlessly integrate bird observation data from eBird into their Go applications.

Features

  • Data Retrieval: Access bird observation data from eBird effortlessly.
  • Flexible Filtering: Filter data based on parameters such as location, date, and species.
  • Easy Integration: Integrate eBird data seamlessly into your Go applications.

Installation

Install go-ebird using go get:

go get -u github.com/siansiansu/go-ebird

Usage

package main

import (
  "context"
  "fmt"

  "github.com/siansiansu/go-ebird"
)

func main() {
  var ctx = context.Background()
  client, err := ebird.NewClient("YOUR_EBIRD_API_KEY")
  if err != nil {
    panic(err)
  }
  r, err := client.RecentNotableObservationsInRegion(ctx, "TW")
  if err != nil {
    panic(err)
  }
  for _, e := range r {
    fmt.Println(e.ComName, e.LocName, e.HowMany)
  }
}

Remember to replace "YOUR_EBIRD_API_KEY" with your actual eBird API key. You can obtain an API key by creating an account on the eBird website.

Refer to the GoDoc page for comprehensive documentation and more examples.

Contributing

Contributions are welcome! Report bugs or request features by opening an issue. If you want to contribute code, fork the repository and submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Constants

View Source 
const (
	// Base URL for eBird API 2.0 requests.
	// baseURL should always be specified with a trailing slash.
	APIEndpointBase = "https://api.ebird.org/v2/"

	// The data/obs end-points are used to fetch observations submitted to eBird in checklists.
	// https://documenter.getpostman.com/view/664302/S1ENwy59#4e020bc2-fc67-4fb6-a926-570cedefcc34
	APIEndpointHistoricObservationsOnDate          = "data/obs/%s/historic/%d/%d/%d"
	APIEndpointNearestObservationsOfSpecies        = "data/nearest/geo/recent/%s"
	APIEndpointRecentChecklistsFeed                = "product/lists/%s"
	APIEndpointRecentNearbyNotableObservations     = "data/obs/geo/recent/notable"
	APIEndpointRecentNearbyObservations            = "data/obs/geo/recent"
	APIEndpointRecentNearbyObservationsOfSpecies   = "data/obs/geo/recent/%s"
	APIEndpointRecentNotableObservationsInRegion   = "data/obs/%s/recent/notable"
	APIEndpointRecentObservationsInRegion          = "data/obs/%s/recent"
	APIEndpointRecentObservationsOfSpeciesInRegion = "data/obs/%s/recent/%s"

	// The product end-points make it easy to get the information shown in various pages on the eBird web site
	// https://documenter.getpostman.com/view/664302/S1ENwy59#af04604f-e406-4cea-991c-a9baef24cd78
	APIEndpointChecklistFeedOnDate      = "product/lists/%s/%d/%d/%d"
	APIEndpointRegionalStatisticsOnDate = "product/stats/%s/%d/%d/%d"
	APIEndpointSpeciesListForRegion     = "product/spplist/%s"
	APIEndpointTop100                   = "product/top100/%s/%d/%d/%d"
	APIEndpointViewChecklist            = "product/checklist/view/%s"

	// ref/geo
	// With the ref/geo end-point you can find a country's or region's neighbours.
	// https://documenter.getpostman.com/view/664302/S1ENwy59#c9947c5c-2dce-4c6d-9911-7d702235506c
	APIEndpointAdjacentRegions = "ref/adjacent/%s"

	// ref/hotspot
	// With the ref/hotspot end-points you can find the hotspots for a given country or region or nearby hotspots
	// https://documenter.getpostman.com/view/664302/S1ENwy59#c9947c5c-2dce-4c6d-9911-7d702235506c
	APIEndpointHotspotInfo      = "ref/hotspot/info/%s"
	APIEndpointHotspotsInRegion = "ref/hotspot/%s"
	APIEndpointNearbyHotspots   = "ref/hotspot/geo"

	// ref/taxonomy
	// https://documenter.getpostman.com/view/664302/S1ENwy59#36c95b76-e18e-4788-9c9e-e539045f9166
	APIEndpointEbirdTaxonomy    = "ref/taxonomy/ebird"
	APIEndpointTaxaLocaleCodes  = "ref/taxa-locales/ebird"
	APIEndpointTaxonomicForms   = "ref/taxon/forms/%s"
	APIEndpointTaxonomicGroups  = "ref/sppgroup/%s"
	APIEndpointTaxonomyVersions = "ref/taxonomy/versions"

	// ref/region
	// The ref/region end-points return information on regions.
	// https://documenter.getpostman.com/view/664302/S1ENwy59#e18ea3b5-e80c-479f-87db-220ce8d9f3b6
	APIEndointRegionInfo    = "ref/region/info/%s"
	APIEndointSubRegionInfo = "ref/region/list/%s/%s"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AdjacentRegions 

type AdjacentRegions struct {
	Code string `json:"code,omitempty"`
	Name string `json:"name,omitempty"`
}

type Bounds 

type Bounds struct {
	MinX float64 `json:"minX,omitempty"`
	MaxX float64 `json:"maxX,omitempty"`
	MinY float64 `json:"minY,omitempty"`
	MaxY float64 `json:"maxY,omitempty"`
}

type ChecklistFeedOnDate 

type ChecklistFeedOnDate struct {
	LocId           string      `json:"locId,omitempty"`
	SubId           string      `json:"subId,omitempty"`
	UserDisplayName string      `json:"userDisplayName,omitempty"`
	NumSpecies      int32       `json:"numSpecies,omitempty"`
	ObsDt           string      `json:"obsDt,omitempty"`
	ObsTime         string      `json:"obsTime,omitempty"`
	IsoObsDate      string      `json:"isoObsDate,omitempty"`
	SubID           string      `json:"subID,omitempty"`
	Loc             HotspotInfo `json:"loc,omitempty"`
}

type Client 

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

func NewClient 

func NewClient(key string, opts ...ClientOption) (*Client, error)

func (*Client) AdjacentRegions 

func (c *Client) AdjacentRegions(ctx context.Context, regionCode string, opts ...RequestOption) ([]AdjacentRegions, error)

func (*Client) ChecklistFeedOnDate 

func (c *Client) ChecklistFeedOnDate(ctx context.Context, regionCode string, y, m, d int, opts ...RequestOption) ([]ChecklistFeedOnDate, error)

func (*Client) EbirdTaxonomy 

func (c *Client) EbirdTaxonomy(ctx context.Context, opts ...RequestOption) ([]EbirdTaxonomy, error)

func (*Client) HistoricObservationsOnDate 

func (c *Client) HistoricObservationsOnDate(ctx context.Context, regionCode string, y, m, d int, opts ...RequestOption) ([]Observations, error)

func (*Client) HotspotInfo 

func (c *Client) HotspotInfo(ctx context.Context, locId string, opts ...RequestOption) (*HotspotInfo, error)

func (*Client) HotspotsInRegion 

func (c *Client) HotspotsInRegion(ctx context.Context, regionCode string, opts ...RequestOption) ([]HotspotsInRegion, error)

func (*Client) NearbyHotspots 

func (c *Client) NearbyHotspots(ctx context.Context, opts ...RequestOption) ([]NearbyHotspots, error)

func (*Client) NearestObservationsOfSpecies 

func (c *Client) NearestObservationsOfSpecies(ctx context.Context, speciesCode string, opts ...RequestOption) ([]Observations, error)

func (*Client) RecentChecklistsFeed 

func (c *Client) RecentChecklistsFeed(ctx context.Context, regionCode string, opts ...RequestOption) ([]RecentChecklistsFeed, error)

func (*Client) RecentNearbyNotableObservations 

func (c *Client) RecentNearbyNotableObservations(ctx context.Context, opts ...RequestOption) ([]Observations, error)

func (*Client) RecentNearbyObservations 

func (c *Client) RecentNearbyObservations(ctx context.Context, opts ...RequestOption) ([]Observations, error)

func (*Client) RecentNearbyObservationsOfSpecies 

func (c *Client) RecentNearbyObservationsOfSpecies(ctx context.Context, speciesCode string, opts ...RequestOption) ([]Observations, error)

func (*Client) RecentNotableObservationsInRegion 

func (c *Client) RecentNotableObservationsInRegion(ctx context.Context, regionCode string, opts ...RequestOption) ([]Observations, error)

func (*Client) RecentObservationsInRegion 

func (c *Client) RecentObservationsInRegion(ctx context.Context, regionCode string, opts ...RequestOption) ([]Observations, error)

func (*Client) RecentObservationsOfSpeciesInRegion 

func (c *Client) RecentObservationsOfSpeciesInRegion(ctx context.Context, regionCode, speciesCode string, opts ...RequestOption) ([]Observations, error)

func (*Client) RegionInfo 

func (c *Client) RegionInfo(ctx context.Context, regionCode string, opts ...RequestOption) (*RegionInfo, error)

func (*Client) RegionalStatisticsOnDate 

func (c *Client) RegionalStatisticsOnDate(ctx context.Context, regionCode string, y, m, d int, opts ...RequestOption) (*RegionalStatisticsOnDate, error)

func (*Client) SpeciesListForRegion 

func (c *Client) SpeciesListForRegion(ctx context.Context, regionCode string, opts ...RequestOption) ([]string, error)

func (*Client) SubRegionList 

func (c *Client) SubRegionList(ctx context.Context, regionType, parentRegionCode string, opts ...RequestOption) ([]SubRegionList, error)

func (*Client) TaxaLocaleCodes 

func (c *Client) TaxaLocaleCodes(ctx context.Context, opts ...RequestOption) ([]TaxaLocaleCodes, error)

func (*Client) TaxonomicForms 

func (c *Client) TaxonomicForms(ctx context.Context, speciesCode string, opts ...RequestOption) ([]string, error)

func (*Client) TaxonomicGroups 

func (c *Client) TaxonomicGroups(ctx context.Context, speciesGrouping string, opts ...RequestOption) ([]TaxonomicGroups, error)

func (*Client) TaxonomyVersions 

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

func (*Client) Top100 

func (c *Client) Top100(ctx context.Context, regionCode string, y, m, d int, opts ...RequestOption) ([]Top100, error)

func (*Client) ViewChecklist 

func (c *Client) ViewChecklist(ctx context.Context, subId string, opts ...RequestOption) (*ViewChecklist, error)

type ClientOption 

type ClientOption func(client *Client)

func WithAcceptLanguage 

func WithAcceptLanguage(lang string) ClientOption

func WithBaseURL 

func WithBaseURL(urlStr string) ClientOption

type EbirdTaxonomy 

type EbirdTaxonomy struct {
	SciName       string   `json:"sciName,omitempty"`
	ComName       string   `json:"comName,omitempty"`
	SpeciesCode   string   `json:"speciesCode,omitempty"`
	Category      string   `json:"category,omitempty"`
	TaxonOrder    float32  `json:"taxonOrder,omitempty"`
	BandingCodes  []string `json:"bandingCodes,omitempty"`
	ComNameCodes  []string `json:"comNameCodes,omitempty"`
	SciNameCodes  []string `json:"sciNameCodes,omitempty"`
	Order         string   `json:"order,omitempty"`
	FamilyCode    string   `json:"familyCode,omitempty"`
	FamilyComName string   `json:"familyComName,omitempty"`
	FamilySciName string   `json:"familySciName,omitempty"`
}

type Error 

type Error struct {
	Message string `json:"message"`
	Status  int    `json:"status"`
}

func (Error) Error 

func (e Error) Error() string

type HotspotInfo 

type HotspotInfo struct {
	LocId            string  `json:"locId,omitempty"`
	Name             string  `json:"name,omitempty"`
	Latitude         float32 `json:"latitude,omitempty"`
	Longitude        float32 `json:"longitude,omitempty"`
	CountryCode      string  `json:"countryCode,omitempty"`
	CountryName      string  `json:"countryName,omitempty"`
	Subnational1Name string  `json:"subnational1Name,omitempty"`
	Subnational1Code string  `json:"subnational1Code,omitempty"`
	Subnational2Code string  `json:"Subnational2Code,omitempty"`
	Subnational2Name string  `json:"Subnational2Name,omitempty"`
	IsHotspot        bool    `json:"isHotspot,omitempty"`
	LocID            string  `json:"locID,omitempty"`
	LocName          string  `json:"locName,omitempty"`
	Lat              float32 `json:"lat,omitempty"`
	Lng              float32 `json:"lng,omitempty"`
	HierarchicalName string  `json:"hierarchicalName,omitempty"`
}

type HotspotsInRegion 

type HotspotsInRegion struct {
	LocId             string  `json:"locId,omitempty"`
	LocName           string  `json:"locName,omitempty"`
	CountryCode       string  `json:"countryCode,omitempty"`
	Subnational1Code  string  `json:"subnational1Code,omitempty"`
	Subnational2Code  string  `json:"subnational2Code,omitempty"`
	Lat               float32 `json:"lat,omitempty"`
	Lng               float32 `json:"lng,omitempty"`
	LatestObsDt       string  `json:"latestObsDt,omitempty"`
	NumSpeciesAllTime int32   `json:"numSpeciesAllTime,omitempty"`
}

type Loc 

type Loc struct {
	LocId            string  `json:"locId,omitempty"`
	Name             string  `json:"name,omitempty"`
	Latitude         float32 `json:"latitude,omitempty"`
	Longitude        float32 `json:"longitude,omitempty"`
	CountryCode      string  `json:"countryCode,omitempty"`
	CountryName      string  `json:"countryName,omitempty"`
	Subnational1Name string  `json:"subnational1Name,omitempty"`
	Subnational1Code string  `json:"subnational1Code,omitempty"`
	Subnational2Code string  `json:"Subnational2Code,omitempty"`
	Subnational2Name string  `json:"Subnational2Name,omitempty"`
	IsHotspot        bool    `json:"isHotspot,omitempty"`
	LocName          string  `json:"locName,omitempty"`
	Lat              float32 `json:"lat,omitempty"`
	Lng              float32 `json:"lng,omitempty"`
	HierarchicalName string  `json:"hierarchicalName,omitempty"`
	LocID            string  `json:"locID,omitempty"`
}

type NearbyHotspots 

type NearbyHotspots struct {
	LocId             string  `json:"locId,omitempty"`
	LocName           string  `json:"locName,omitempty"`
	CountryCode       string  `json:"countryCode,omitempty"`
	Subnational1Code  string  `json:"subnational1Code,omitempty"`
	Lat               float32 `json:"lat" validate:"required"`
	Lng               float32 `json:"lng" validate:"required"`
	LatestObsDt       string  `json:"latestObsDt,omitempty"`
	NumSpeciesAllTime int32   `json:"numSpeciesAllTime,omitempty"`
}

type Obs 

type Obs struct {
	SpeciesCode      string   `json:"speciesCode,omitempty"`
	HideFlags        []string `json:"hideFlags,omitempty"`
	ObsDt            string   `json:"obsDt,omitempty"`
	Subnational1Code string   `json:"subnational1Code,omitempty"`
	HowManyAtleast   int32    `json:"howManyAtleast,omitempty"`
	HowManyAtmost    int32    `json:"howManyAtmost,omitempty"`
	SubId            string   `json:"subId,omitempty"`
	ProjId           string   `json:"projId,omitempty"`
	ObsId            string   `json:"obsId,omitempty"`
	HowManyStr       string   `json:"howManyStr,omitempty"`
	Present          bool     `json:"present,omitempty"`
}

type Observations 

type Observations struct {
	SpeciesCode     string  `json:"speciesCode,omitempty"`
	ComName         string  `json:"comName,omitempty"`
	SciName         string  `json:"sciName,omitempty"`
	LocId           string  `json:"locId,omitempty"`
	LocName         string  `json:"locName,omitempty"`
	ObsDt           string  `json:"obsDt,omitempty"`
	HowMany         int32   `json:"howMany,omitempty"`
	Lat             float32 `json:"lat,omitempty"`
	Lng             float32 `json:"lng,omitempty"`
	ObsValid        bool    `json:"obsValid,omitempty"`
	ObsReviewed     bool    `json:"obsReviewed,omitempty"`
	LocationPrivate bool    `json:"locationPrivate,omitempty"`
	SubId           string  `json:"subId,omitempty"`
	ExoticCategory  string  `json:"exoticCategory,omitempty"`
}

type RecentChecklistsFeed 

type RecentChecklistsFeed struct {
	LocId           string `json:"locId,omitempty"`
	SubId           string `json:"subId,omitempty"`
	UserDisplayName string `json:"userDisplayName,omitempty"`
	NumSpecies      int32  `json:"numSpecies,omitempty"`
	ObsDt           string `json:"obsDt,omitempty"`
	ObsTime         string `json:"obsTime,omitempty"`
	IsoObsDate      string `json:"isoObsDate,omitempty"`
	SubID           string `json:"subID,omitempty"`
	Loc             Loc    `json:"loc,omitempty"`
}

type RegionInfo 

type RegionInfo struct {
	Bounds    Bounds
	Result    string  `json:"result,omitempty"`
	Code      string  `json:"code,omitempty"`
	Type      string  `json:"type,omitempty"`
	Longitude float64 `json:"longitude,omitempty"`
	Latitude  float64 `json:"latitude,omitempty"`
}

type RegionalStatisticsOnDate 

type RegionalStatisticsOnDate struct {
	NumChecklists   int32 `json:"numChecklists,omitempty"`
	NumContributors int32 `json:"numContributors,omitempty"`
	NumSpecies      int32 `json:"numSpecies,omitempty"`
}

type RequestOption 

type RequestOption func(*requestOptions)

func Back 

func Back(amount int) RequestOption

Only fetch hotspots which have been visited up to 'back' days ago. Values: 1-30

func Cat 

func Cat(code string) RequestOption

Only fetch records from these taxonomic categories. Values: any available category, must be lowercase

func Delim 

func Delim(code string) RequestOption

The characters used to separate elements in the name. Values: (any characters)

func Dist 

func Dist(amount int) RequestOption

The search radius from the given position, in kilometers. Values: 0 - 500

func Fmt 

func Fmt(code string) RequestOption

Fetch the records in CSV or JSON format. Values: csv, json

func GroupNameLocale 

func GroupNameLocale(code string) RequestOption

Locale for species group names. English names are returned for any non-listed locale or any non-translated group name Values: bg,cs,da,de,en,es,es_AR,es_CL,es_CU,es_ES,es_MX,es_PA,fr,he, is,nl,no,pt_BR,pt_PT,ru,sr,th,tr, or zh

func Hotspot 

func Hotspot(code bool) RequestOption

Only fetch observations from hotspots. Values: true, false

func IncludeProvisional 

func IncludeProvisional(code bool) RequestOption

Include observations which have not yet been reviewed. Values: true, false

func Lat 

func Lat(amount int) RequestOption

Required. Latitude to 2 decimal places. Values: -90 - 90

func Lng 

func Lng(amount int) RequestOption

Required. Longitude to 2 decimal places. Values: -180 - 180

func Locale 

func Locale(code string) RequestOption

Use this language for common names. Values: any available locale

func MaxResults 

func MaxResults(amount int) RequestOption

Only fetch this number of contributors. Values: 1 - 100

func R 

func R(code string) RequestOption

Fetch observations from up to 10 locations. Values: any location code

func RankedBy 

func RankedBy(code string) RequestOption

Order by number of complete checklists (cl) or by number of species seen (spp). Values: spp, cl

func RegionNameFormat 

func RegionNameFormat(code string) RequestOption

Control how the name is displayed. Values: detailed, detailednoqual, full, namequal, nameonly, revdetailed

func SortKey 

func SortKey(code string) RequestOption

Order the results by the date of the checklist or by the date it was submitted. Values: obs_dt, creation_dt

func Species 

func Species(code string) RequestOption

Only fetch records for these species. Values: any species code

func SppLocale 

func SppLocale(code string) RequestOption

Use this language for species common names. Values: any available locale

func Version 

func Version(code string) RequestOption

Fetch a specific version of the taxonomy. any available version

type SubAux 

type SubAux struct {
	SubId           string `json:"subId,omitempty"`
	FieldName       string `json:"fieldName,omitempty"`
	EntryMethodCode string `json:"entryMethodCode,omitempty"`
	AuxCode         string `json:"auxCode,omitempty"`
}

type SubRegionList 

type SubRegionList struct {
	Code string `json:"code,omitempty"`
	Name string `json:"name,omitempty"`
}

type TaxaLocaleCodes 

type TaxaLocaleCodes struct {
	Code       string `json:"code,omitempty"`
	Name       string `json:"name,omitempty"`
	LastUpdate string `json:"lastUpdate,omitempty"`
}

type TaxonomicGroups 

type TaxonomicGroups struct {
	GroupName        string      `json:"groupName,omitempty"`
	GroupOrder       int32       `json:"groupOrder,omitempty"`
	TaxonOrderBounds [][]float32 `json:"taxonOrderBounds,omitempty"`
}

type TaxonomyVersions 

type TaxonomyVersions struct {
	AuthorityVer float32 `json:"authorityVer,omitempty"`
	Latest       bool    `json:"latest,omitempty"`
}

type Top100 

type Top100 struct {
	ProfileHandle         string `json:"profileHandle,omitempty"`
	UserDisplayName       string `json:"userDisplayName,omitempty"`
	NumSpecies            int32  `json:"numSpecies,omitempty"`
	NumCompleteChecklists int32  `json:"numCompleteChecklists,omitempty"`
	RowNum                int32  `json:"rowNum,omitempty"`
	UserId                string `json:"userId,omitempty"`
}

type ViewChecklist 

type ViewChecklist struct {
	ProjId                      string  `json:"projId,omitempty"`
	SubId                       string  `json:"subId,omitempty"`
	ProtocolId                  string  `json:"protocolId,omitempty"`
	LocId                       string  `json:"locId,omitempty"`
	GroupId                     string  `json:"groupId,omitempty"`
	DurationHrs                 float32 `json:"durationHrs,omitempty"`
	AllObsReported              bool    `json:"allObsReported,omitempty"`
	CreationDt                  string  `json:"creationDt,omitempty"`
	LastEditedDt                string  `json:"lastEditedDt,omitempty"`
	ObsDt                       string  `json:"obsDt,omitempty"`
	ObsTimeValid                bool    `json:"obsTimeValid,omitempty"`
	ChecklistId                 string  `json:"checklistId,omitempty"`
	NumObservers                int32   `json:"numObservers,omitempty"`
	EffortDistanceKm            float32 `json:"effortDistanceKm,omitempty"`
	EffortDistanceEnteredUnit   string  `json:"effortDistanceEnteredUnit,omitempty"`
	Subnational1Code            string  `json:"subnational1Code,omitempty"`
	SubmissionMethodCode        string  `json:"submissionMethodCode,omitempty"`
	SubmissionMethodVersion     string  `json:"submissionMethodVersion,omitempty"`
	UserDisplayName             string  `json:"userDisplayName,omitempty"`
	NumSpecies                  int32   `json:"numSpecies,omitempty"`
	SubmissionMethodVersionDisp string  `json:"submissionMethodVersionDisp,omitempty"`
	SubAux                      []SubAux
	SubAuxAi                    []string `json:"subAuxAi,omitempty"`
	Obs                         []Obs
}

Source Files

View all Source files

Directories

Path Synopsis
examples
geo
hotspot
obs
product
region
taxonomy

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.