migrate to using the COL XR as the default taxonomy

[jhnwllr]

BREAKING CHANGES

Test dev version here:

# Using remotes
remotes::install_github("ropensci/rgbif", ref = "v3.9.0")
# Or using devtools
devtools::install_github("ropensci/rgbif", ref = "v3.9.0")

Default taxonomy changed from GBIF Backbone to COL (Catalogue of Life) Extended Release (#895)

Migration Guide

The following functions now use COL Extended Release (checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b") as the default taxonomy:

• name_backbone() - Returns COL XR alpha-numeric taxon keys (e.g., "Q2M4") instead of numeric GBIF Backbone keys
• name_backbone_checklist() - Matches names against COL XR by default
• occ_search() - Searches using COL XR taxonomy
• occ_download() - Creates downloads with COL XR taxonomy
• occ_download_prep() - Prepares downloads with COL XR taxonomy
• map_fetch() - Fetches maps using COL XR taxonomy
• mvt_fetch() - Fetches map vector tiles using COL XR taxonomy

DEPRECATED

The following functions are deprecated because they use the GBIF Backbone taxonomy, and will not work with COL XR keys.

• name_lookup() - use rcol::col_search() instead
• name_suggest() - use rcol::col_suggest() instead
• name_usage() - use rcol::col_usage() instead
• name_issues() - use rcol::col_usage() to parse and examine name issues

NEW FEATURE

gbif_to_col() - Convert GBIF Backbone numeric taxon keys to COL Extended Release alpha-numeric keys. Returns the full API response including usage details, classification hierarchy, and match diagnostics.

MINOR IMPROVEMENTS

• occ_search() now returns classifications as a named list of tibbles, with one tibble per checklistKey (taxonomy source). Each tibble contains one row per occurrence with taxonomic ranks pivoted into camelCase columns (checklistKey, kingdomName, kingdomKey, phylumName, phylumKey, className, classKey, etc.). This structure makes it easy to work with occurrences from different taxonomies separately while keeping the checklistKey information with the data. Known checklists (COL, backbone) are shown with friendly names, while unknown checklists use their UUID.
• occ_search() now detects numeric taxonomic keys (taxonKey, speciesKey, kingdomKey, etc.) and automatically switches to the GBIF Backbone taxonomy checklistKey with a warning message. These numeric keys are legacy identifiers from the GBIF Backbone taxonomy. Users are advised to migrate to COL XR identifiers using gbif_to_col().
• occ_download() and occ_download_prep() now detect numeric taxonomic keys in predicates and automatically inject the GBIF Backbone checklistKey at the predicate level with a warning message. This ensures existing code using numeric keys continues to work correctly.
• name_usage() now warns when datasetKey parameter is ignored. When a key is provided, the GBIF API ignores the datasetKey parameter and returns data based solely on the key. A warning is now issued to alert users of this behavior (datasetKey ignored in name_usage() without issuing warning #899).

[PietrH]

Are there any tasks that others could pick up John?

[LienReyserhove]

Dear John,

I was wondering if you could update me about when this specific issue will be implemented. For one of our projects, we heavily rely on rgbif to construct a European checklist of Introduced and Invasive Species.

Context:

To compile this European list, we combine several national species checklist from GBIF, using a reproducible workflow in R. One of the main tasks in this process is the harmonization of taxonomy. For this we use the GBIF taxonomic backbone accessed through rGBIF. We replace synonyms by accepted names, remove taxa that have no match with the backbone, etc. This process is automated by using the R package elodea, developed by my colleague @sannegovaert.

A first draft of this European checklist is now available and ready for review by the partners. They will review whether the removed taxa should be retained in the checklist, whether merging synonyms with the accepted name is correct, etc. However, since the GBIF backbone now uses the COL backbone as a default, we expect several changes to the content of this European list and the process of assemling it. As rgbif hasn't been updated yet, it keeps us from initiating the expert review as many of the work will be redundant.

This delay is a concern, as we are on a tight timeline to deliver our final output, i.e the European checklist.

Best wishes,
Lien

[sannegovaert]

How does this relate to https://github.com/CatalogueOfLife/rcol ?

[ManonGros]

Hello people in the thread! I believe that you can already use the CoLXR with rgbif: https://docs.ropensci.org/rgbif/articles/getting_occurrence_data.html#downloading-using-an-alternative-taxonomy
This issue is about making the CoLXR the default taxonomy (the one used when no checklist key is specified). I think you can already use rgbif for your work.

[sannegovaert]

Hello people in the thread! I believe that you can already use the CoLXR with rgbif: https://docs.ropensci.org/rgbif/articles/getting_occurrence_data.html#downloading-using-an-alternative-taxonomy This issue is about making the CoLXR the default taxonomy (the one used when no checklist key is specified). I think you can already use rgbif for your work.

Thank you Manon.
We use checklist data, not occurence data. Is there any way to use rgibf::name_usage() with the CoL backbone? Or should we switch to https://github.com/CatalogueOfLife/rcol ?

[ManonGros]

Hi @sannegovaert using name_backbone()$usageKey with checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b" would give you the keys from the ColXR. Alternatively, you should also be able to use name_usage() with the datasetKey = "7ddf754f-d193-4cc9-b351-99906754a03b"

[sannegovaert]

Is this how it should be used?

library(rgbif)
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

# CoL backbone
rgbif::name_usage(
  key = 4528099, datasetKey = "7ddf754f-d193-4cc9-b351-99906754a03b")$data |>
  dplyr::select(dplyr::any_of(c(
    "key", "scientificName", "taxonomicStatus", "acceptedKey", "accepted",
    "rank", "kingdom"
  )))
#> # A tibble: 1 × 7
#>       key scientificName      taxonomicStatus acceptedKey accepted rank  kingdom
#>     <int> <chr>               <chr>                 <int> <chr>    <chr> <chr>  
#> 1 4528099 Tuta absoluta (Mey… SYNONYM             4528100 Phthori… SPEC… Animal…

# GBIF backbone
rgbif::name_usage(key = 4528099)$data |>
  dplyr::select(dplyr::any_of(c(
    "key", "scientificName", "taxonomicStatus", "acceptedKey", "accepted",
    "rank", "kingdom"
  )))
#> # A tibble: 1 × 7
#>       key scientificName      taxonomicStatus acceptedKey accepted rank  kingdom
#>     <int> <chr>               <chr>                 <int> <chr>    <chr> <chr>  
#> 1 4528099 Tuta absoluta (Mey… SYNONYM             4528100 Phthori… SPEC… Animal…

^{Created on 2026-07-15 with reprex v2.1.1}

This gives the same result, while this taxon, Tuta absoluta (Meyrick, 1917), with nubkey 4528099 is the accepted name following CoL and not a synonym.

We are standardising published GBIF checklists on alien species to create a unified European checklist on alien species. For this we need to align the taxonomy and take the accepted name of each taxon. We want to follow the CoL because that is now what GBIF uses.

[ManonGros]

Hi @sannegovaert my apologies, I mistakenly thought that name_usage() was using the v2 of the species search API. It isn't the case.

I am not sure what the plans are for usage_name() in rgbif but in the meantime, you can try: https://www.catalogueoflife.org/2026/06/20/rcol-r-package

[damianooldoni]

Something important maybe for @sannegovaert as well.
If you have a list of GBIF Backbone keys and you need to get the "new" CoL IDs, you can do it via name_backbone_checklist() which supports API v2. You need to use the checklistKey and scientificNameID arguments. I found the solution based on the blogpost How to migrate from the legacy GBIF Backbone Taxonomy to Catalogue of Life Extended Release of @jhnwllr:

If you have an old GBIF backbone integer taxonKey and want to resolve it to the new COL XR identifier, you can use the scientificNameID parameter with the matching service: https://api.gbif.org/v2/species/match?checklistKey=7ddf754f-d193-4cc9-b351-99906754a03b&scientificNameID=gbif:1427067

So, we just need to add the prefix gbif: to the GBIF Backbone keys. Here below an example:

library(rgbif)
library(dplyr)

# Example of how to get COL IDs for a list of GBIF keys

backbone_keys <- c(2978552, 3189866, 2489010, 2489005, 3190653)
# Add prefix "gbif:" to the backbone keys
backbone_keys <- paste0("gbif:", backbone_keys)

# Use name_backbone_checklist to get COL IDs for the GBIF keys
col_keys <- rgbif::name_backbone_checklist(
  name_data = backbone_keys,
  scientificNameID = backbone_keys,
  checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b") %>%
  dplyr::distinct(usageKey) %>%
  dplyr::pull()

# Create a lookup table
dplyr::tibble(
  gbif_taxon_key = backbone_keys,
  col_taxon_key = col_keys
)
#> # A tibble: 5 × 2
#>   gbif_taxon_key col_taxon_key
#>   <chr>          <chr>        
#> 1 gbif:2978552   64BRL        
#> 2 gbif:3189866   94F5         
#> 3 gbif:2489010   9KHM         
#> 4 gbif:2489005   9KHT         
#> 5 gbif:3190653   BCBF

^{Created on 2026-07-16 with reprex v2.1.1}

[damianooldoni]

@sannegovaert, your example above in #895 (comment) is indeed important.
The point there is that you are providing a key from the GBIF Backbone while datasetKey points to CoL, so the datasetKey value is probably ignored. I created a new issue for it (#899) as I think it is important to allow the user to understand that the retrieved information is still from the Backbone, not from CoL.

I can confirm that name_usage() doesn't accept CoL keys:

library(rgbif)
name_usage(key = "B6LVP")
#> Error:
#> ! For input string: "B6LVP"

^{Created on 2026-07-16 with reprex v2.1.1}

@sannegovaert: to get taxonomic status assigned by CoL you must use name_backbone() or the multi-taxa equivalent name_backbone_checklist(), the only two taxonomy related functions supporting API v2. Here below the code based on your example for Tuta absoluta (Meyrick, 1917):

library(rgbif)
library(dplyr)

rgbif::name_backbone(
  usageKey = "B6LVP",
  checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b"
) |>
  dplyr::pull(status)
#> [1] "ACCEPTED"

^{Created on 2026-07-16 with reprex v2.1.1}

Still, the example provided by @sannegovaert about taxonomicStatus is just an example: we need a way to get many other fields as we were used to do with GBIF Backbone, only possible via name_usage(), I think. Thanks in advance 🙏

[jhnwllr]

@LienReyserhove
There is no release date for this change, but it will be rolled out carefully as it is a breaking change.

Please see this article. Near the bottom it gives examples of how to already prepare for the change.
https://data-blog.gbif.org/post/catalogue-of-life-taxonomic-backbone/

Currently the plan is to deprecate (meaning they will still work with the old GBIF backbone, but not support the COL XR)
name_lookup(), name_suggest(), and name_usage()
They will return some warning message guiding users to switch to using rcol.
https://www.catalogueoflife.org/2026/06/20/rcol-r-package

As mentioned by @ManonGros name_backbone() and name_backbone_checklist() currently already support matching against the COLXR, as long as one supplies checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b".

name_backbone(
  name = "Calopteryx splendens",
  checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b"
)
# Q2M4

Since the GBIF backbone will no longer be updated, this change is necessary for rgbif.