跳至主要内容

go-ebird - eBird API 的 Go Library

· 閱讀時間約 3 分鐘

GoDoc License: MIT Go Report Card

go-ebird 是一個全面的 eBird API Go 客戶端函式庫。它為開發者提供了易於使用的介面，讓你可以輕鬆地將 eBird 的鳥類觀測資料整合到你的 Go 應用程式中。

主要功能​

  • 完整的資料存取：檢索各種類型的鳥類觀測資料，包括最近的觀測記錄、值得注意的觀測，以及觀測清單。
  • 靈活的篩選：基於地點、日期、物種等條件進行資料篩選。
  • 健全的錯誤處理：清晰的錯誤訊息和適當的 API 速率限制處理。
  • 可自訂的客戶端：設定超時、基礎 URL 及其他 HTTP 客戶端選項。
  • 完整的 API 涵蓋：支援所有主要的 eBird API 端點。

安裝​

使用 go get 安裝 go-ebird：

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

快速開始​

以下是一個簡單的範例：

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    client, err := ebird.NewClient("YOUR_EBIRD_API_KEY")
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    observations, err := client.RecentObservationsInRegion(context.Background(), "US-NY", ebird.MaxResults(5))
    if err != nil {
        log.Fatalf("Failed to get observations: %v", err)
    }

    for _, obs := range observations {
        fmt.Printf("%s spotted at %s\n", obs.ComName, obs.LocName)
    }
}

詳細使用​

  • 檢索值得注意的觀測記錄
  • 取得附近的熱門鳥點
  • 獲取最近的觀測清單
  • 存取分類資訊

API 端點​

go-ebird 支援所有主要的 eBird API 端點，包括：

  • Observations（觀測記錄）
  • Hotspots（熱門鳥點）
  • Taxonomy（分類）
  • Checklists（觀測清單）
  • Region information（區域資訊）

請參考 GoDoc 以查看完整的支援端點列表及其使用方式。

設定​

你可以使用各種選項來設定客戶端：

client, err := ebird.NewClient(
    "YOUR_EBIRD_API_KEY",
    ebird.WithBaseURL("https://api.ebird.org/v2/"),
    ebird.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
    ebird.WithAcceptLanguage("en"),
)

速率限制​

eBird API 有速率限制。此客戶端不會自動處理速率限制，因此請確保在你的應用程式中實作適當的退避和重試邏輯。

貢獻​

歡迎貢獻！以下是你可以貢獻的方式：

  1. Fork 這個儲存庫
  2. 建立你的功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交你的變更 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 開啟一個 Pull Request

請確保你的程式碼符合現有的風格並包含適當的測試。

測試​

使用以下命令執行測試：

go test -v ./...

支援​

如果你遇到任何問題或有疑問，請在 GitHub 上開啟一個 issue。