Documentation
¶
Overview ¶
Package bhlnames is an HTTP client for the BHLnames service (bhlnames.globalnames.org/api/v1). It looks up Biodiversity Heritage Library references for a scientific name + authorship and projects each match into a coldp.Reference preview plus surface metadata (quality, score, page URL) that a UI can use to sort or annotate.
LIFT-TO-SFLIB CANDIDATE. Every SFBorg tool that touches nomenclatural events benefits from this. Written self-contained (no reach into hive-internal state, no singleton) so migration to sflib is a clean copy.
The main endpoint is POST /name_refs which takes a name (+ optional authorship / year / reference context) and returns a scored list of BHL references that likely contain or are the original description. Full schema at bhlnames.globalnames.org/apidoc/index.html.
Index ¶
Constants ¶
const DefaultBaseURL = "https://bhlnames.globalnames.org/api/v1"
DefaultBaseURL is the production endpoint. Tests can pass an httptest URL to New instead.
Variables ¶
var ErrNoMatch = errors.New("bhlnames: no matching references")
ErrNoMatch is a sentinel for callers that want to treat an empty match list as an error; the client itself returns (nil, nil) for empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the HTTP client for BHLnames. Concurrent-safe.
func New ¶
New constructs a client against baseURL. Pass DefaultBaseURL for production; pass an httptest server URL for offline tests. BHLnames has no polite-pool concept — no email header needed.
func (*Client) LookupName ¶
func (c *Client) LookupName( ctx context.Context, canonical, authors string, year int, opts LookupOpts, ) ([]Hit, error)
LookupName runs the POST /name_refs query for a scientific name. canonical is the name without authorship ("Panthera leo"); authors is the authorship string ("Linnaeus"); year is the publication year or 0 for unknown. All three are optional per the BHLnames docs but scores improve dramatically when authorship + year are provided.
Returns an empty slice (no error) when BHLnames finds no matches.
type Hit ¶
type Hit struct {
Reference coldp.Reference
Quality int
Score int
PageURL string
PageID int
MatchedName string
}
Hit is one match from BHLnames, projected into a hive-friendly shape. Reference is a preview coldp.Reference ready to hand to CreateReference; Quality (1-5) and Score are surface metadata a UI can use to sort, filter, or annotate.
Quality thresholds (from the BHLnames API doc):
1 — nothing found (usually filtered out by BHLnames itself) 2 — 15% (Odds > 0.01) 3 — 50% (Odds > 0.1) 4 — 80% (Odds > 1) ← reasonable "auto-suggest" threshold 5 — 98% (Odds > 10) ← very confident
type LookupOpts ¶
type LookupOpts struct {
// RefsLimit — how many matches to return. Default 5 (client-side
// cap when zero). BHLnames itself supports up to a few hundred.
RefsLimit int
// NomenEvent asks BHLnames to focus on identifying the original
// nomenclatural act (protologue). Slower + more targeted. Useful
// when the caller specifically wants "where was this name
// established," less useful for "any BHL page containing this
// name."
NomenEvent bool
}
LookupOpts controls what BHLnames returns. Zero-value means "sensible defaults" — pull up to 5 matches, don't try to identify the nomenclatural event separately. NomenEvent=true makes BHLnames try to isolate the original description specifically.
Source Files