gbif

Documentation

Overview

Package gbif exposes GBIF biodiversity data as a kit Domain. A multi-domain host (ant) enables this driver with a single blank import:

import _ "github.com/tamnd/gbif-cli/gbif"

The same Domain also builds the standalone gbif binary.

Package gbif is the library behind the gbif command line: the HTTP client, request shaping, wire decoding, and typed data models for the GBIF (Global Biodiversity Information Facility) REST API.

The API at https://api.gbif.org/v1 is entirely public and requires no authentication key. The Client paces requests, sets a real User-Agent, and retries transient failures (429 and 5xx).

Index

• Constants
• type Client
  • func NewClient(cfg Config) *Client
  • func (c *Client) GetOccurrence(ctx context.Context, key int) (Occurrence, error)
  • func (c *Client) GetTaxon(ctx context.Context, key int) (Taxon, error)
  • func (c *Client) ListDatasets(ctx context.Context, datasetType string, limit int) ([]Dataset, error)
  • func (c *Client) SearchOccurrences(ctx context.Context, p OccurrenceParams) ([]Occurrence, error)
  • func (c *Client) SearchSpecies(ctx context.Context, query string, limit int) ([]Taxon, error)
• type Config
  • func DefaultConfig() Config
• type Dataset
• type Domain
  • func (Domain) Classify(input string) (string, string, error)
  • func (Domain) Info() kit.DomainInfo
  • func (Domain) Locate(t, id string) (string, error)
  • func (Domain) Register(app *kit.App)
• type Occurrence
• type OccurrenceParams
• type Taxon

Constants

const BaseURL = "https://" + Host + "/v1"

BaseURL is the root every API request is built from.

const DefaultUserAgent = "gbif-cli/0.1.0 (github.com/tamnd/gbif-cli)"

DefaultUserAgent identifies the client to the GBIF API.

const Host = "api.gbif.org"

Host is the GBIF API hostname.

Types

type Client

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

Client talks to the GBIF REST API.

func NewClient

func NewClient(cfg Config) *Client

NewClient returns a Client built from cfg.

func (*Client) GetOccurrence

func (c *Client) GetOccurrence(ctx context.Context, key int) (Occurrence, error)

GetOccurrence fetches a single occurrence record by its numeric key.

func (*Client) GetTaxon

func (c *Client) GetTaxon(ctx context.Context, key int) (Taxon, error)

GetTaxon fetches a single taxon by its numeric GBIF key.

func (*Client) ListDatasets

func (c *Client) ListDatasets(ctx context.Context, datasetType string, limit int) ([]Dataset, error)

ListDatasets lists GBIF datasets, optionally filtered by type.

func (*Client) SearchOccurrences

func (c *Client) SearchOccurrences(ctx context.Context, p OccurrenceParams) ([]Occurrence, error)

SearchOccurrences searches occurrence records with optional filters.

func (*Client) SearchSpecies

func (c *Client) SearchSpecies(ctx context.Context, query string, limit int) ([]Taxon, error)

SearchSpecies searches the /species/search endpoint by name.

type Config

type Config struct {
	BaseURL   string
	UserAgent string
	Rate      time.Duration
	Timeout   time.Duration
	Retries   int
}

Config holds all tunable parameters for the Client.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults.

type Dataset

type Dataset struct {
	Key   string `json:"key"`
	Title string `json:"title"`
	Type  string `json:"type"`
	URL   string `json:"url"`
}

Dataset is a contributing dataset in the GBIF network.

type Domain

type Domain struct{}

Domain is the GBIF driver. It carries no state; the per-run client is built by the factory Register hands kit.

func (Domain) Classify

func (Domain) Classify(input string) (string, string, error)

Classify turns a taxon key or GBIF URL into (type, id).

func (Domain) Info

func (Domain) Info() kit.DomainInfo

Info describes the scheme, hostnames, and binary identity.

func (Domain) Locate

func (Domain) Locate(t, id string) (string, error)

Locate returns the live https URL for a (type, id).

func (Domain) Register

func (Domain) Register(app *kit.App)

Register installs the client factory and every operation onto app.

type Occurrence

type Occurrence struct {
	Key            int     `json:"key"`
	ScientificName string  `json:"scientific_name"`
	Country        string  `json:"country"`
	StateProvince  string  `json:"state_province"`
	Locality       string  `json:"locality"`
	Year           int     `json:"year"`
	Month          int     `json:"month"`
	Lat            float64 `json:"lat"`
	Lon            float64 `json:"lon"`
	BasisOfRecord  string  `json:"basis_of_record"`
	URL            string  `json:"url"`
}

Occurrence is a single observation record from the GBIF occurrence index.

type OccurrenceParams

type OccurrenceParams struct {
	ScientificName string
	TaxonKey       int
	Country        string
	Year           int
	Limit          int
}

OccurrenceParams holds optional filters for occurrence searches.

type Taxon

type Taxon struct {
	Key           int    `json:"key"`
	CanonicalName string `json:"canonical_name"`
	Rank          string `json:"rank"`
	Kingdom       string `json:"kingdom"`
	Phylum        string `json:"phylum"`
	Class         string `json:"class"`
	Order         string `json:"order"`
	Family        string `json:"family"`
	Genus         string `json:"genus"`
	Status        string `json:"status"`
	URL           string `json:"url"`
}

Taxon represents a species or higher taxonomic unit from the GBIF backbone.