rcol wraps the ChecklistBank API to give R
users idiomatic access to the Catalogue of Life (COL) and
every other public dataset in ChecklistBank.
Two function families
Most functions come in two forms:
-
clb_*()take adataset =argument and work against any dataset. -
col_*()drop that argument and always target the latest extended COL release. The"3LXR"alias is resolved once to its integer dataset key and cached for the session viacol_key(), so long-running work is not disrupted by a new release being published midway. Usecol_refresh()to deliberately re-pin to the newest release.
col_key() # the pinned integer dataset key of the latest extended release
col_refresh() # re-resolve to the newest releaseChoosing a dataset
Almost every function takes a dataset = argument
identifying which checklist to work against. You can pass:
- a numeric dataset key, e.g.
3(the COL project), - a dataset alias such as
"COL25"(the 2025 annual release), or - one of the magic COL release aliases that always resolve to the most recent release.
The COL is published in two cadences (monthly and annual) and two
flavours: a base release and an
extended release (XR) that merges in
additional data. clb_col_release() returns the right
identifier:
clb_col_release("monthly") # "3LR" latest monthly base release
clb_col_release("monthly", extended = TRUE) # "3LXR" latest monthly extended release
clb_col_release("annual") # e.g. "COL25"
# Every release, e.g. to find historical annual editions
clb_col_releases()The package default is "3LXR", the latest monthly
extended release.
Matching names
col_match() returns the single best match against the
latest COL release — the COL analogue of GBIF’s name backbone matching.
The match is done by the ChecklistBank API and returns a tidy one-row
tibble with the matched usage, the match type and the taxonomic
classification:
Use col_match_verbose() to see all candidate usages, and
col_match_checklist() to match a whole vector or data frame
in parallel (input columns are echoed back with a verbatim_
prefix):
col_match_verbose("Oenanthe")
col_match_checklist(c("Panthera leo", "Bufo bufo", "Abies alba"))To match against a particular dataset rather than the latest COL
release, use clb_match() with a dataset = key
or alias:
Linking a checklist to COL
Usages of any other ChecklistBank dataset, such as a GRIIS country
checklist, carry that dataset’s own ids. They are not linked to COL
taxon ids. To get the COL id of each name, match the checklist’s names
against COL. The usage columns scientific_name,
authorship and rank feed straight into
col_match_checklist(), and usage_id of the
result is the COL taxon id:
src <- clb_usage_search(dataset = 22856, max = Inf)$data
m <- col_match_checklist(src, name = "scientific_name")
m[c("verbatim_id", "verbatim_scientific_name", "match_type", "usage_id")]scientific_name is the name without its authorship,
which is in authorship. label combines the two
as shown on ChecklistBank. The authorship and
rank columns are picked up by their default names.
Parsing
The ChecklistBank parsers are exposed too — the scientific name parser and all the controlled-value parsers:
clb_parse_name("Abies alba Mill.")
clb_parsers()
clb_parse("rank", c("spec", "fam.", "ssp"))Datasets
clb_dataset_search("mammal")
clb_dataset("3LXR")
clb_dataset_metrics("COL25")Taxa and the tree
Using the col_*() shortcuts against the latest COL
release:
# Look up a usage and its context
col_usage("4CGXP")
col_classification("4CGXP")
col_synonyms("6DBT")
col_vernacular(id = "4CGXP")
# Navigate the tree
roots <- col_tree()
col_children(roots$id[1])
# Full-text search and metrics
col_usage_search("Felidae")
col_suggest("Panth")
col_usage_metrics("4CGXP")The dataset-scoped equivalents take a dataset =
argument, e.g. clb_usage("4CGXP", dataset = "COL25") or
clb_tree(dataset = "COL25").
Pointing at another server
Set CLB_BASE_URL to target a different ChecklistBank
deployment, such as the development API:
Sys.setenv(CLB_BASE_URL = "https://api.dev.checklistbank.org")