Skip to contents

Migration Guide - COL XR as Default

John Waller

2026-07-02

Source: vignettes/col_migration_guide.Rmd
col_migration_guide.Rmd

What Changed in rgbif 3.9.0

Starting in rgbif 3.9.0, the default taxonomy has changed from the GBIF Backbone Taxonomy to the COL (Catalogue of Life) Extended Release.

This is a breaking change that affects how taxonomic keys are returned and how you should structure your queries.

Key Differences

The GBIF Backbone Taxonomy (the old default) uses numeric taxon keys such as 5231190 or 2977832. This taxonomy is now out-of-date compared to COL XR. To use the GBIF Backbone, explicitly set checklistKey = "d7dddbf4-2cf0-4f39-9b2a-bb099caae36c".

The COL XR (the new default) uses alpha-numeric taxon keys such as "Q2M4" or "9WLSS". This is the default behavior with checklistKey = "7ddf754f-d193-4cc9-b351-99906754a03b".

Backward Compatibility

Your existing code using numeric keys will continue to work! Functions like occ_search() and occ_download() automatically detect numeric taxonomic keys and switch to the GBIF Backbone taxonomy with a warning message. This gives you time to migrate to COL XR at your own pace while ensuring your scripts don’t break.

However, we strongly recommend updating your code to use COL XR keys for the most up-to-date taxonomy. Use gbif_to_col() to convert your existing GBIF Backbone numeric keys to COL XR alpha-numeric keys.

Affected Functions

The following functions now use the COL XR by default:

Name Matching

Before (rgbif 3.8.5 and earlier):

library(rgbif)

# Returned GBIF Backbone numeric key
result <- name_backbone(name = "Calopteryx splendens")
result$usageKey
# [1] 5231190  # numeric key

After (rgbif 3.9.0):

library(rgbif)

# Now returns COL XR alpha-numeric key
result <- name_backbone(name = "Calopteryx splendens")
result$usageKey
# [1] "Q2M4"  # alpha-numeric key

Converting GBIF Backbone Keys to COL XR

If you have existing GBIF Backbone numeric taxon keys and want to convert them to COL XR alpha-numeric keys, use the gbif_to_col() convenience function:

# Convert a single GBIF Backbone key
result <- gbif_to_col(5231190)
result$usage$key  # "Q2M4"

# Convert multiple keys at once
results <- gbif_to_col(c(5231190, 2435099, 2877951))
sapply(results, function(x) x$usage$key)
# [1] "Q2M4"  "9WLSS" "Q2N2"

This function uses the GBIF species matching API to resolve GBIF Backbone keys to their COL XR equivalents. The result includes the original GBIF key, the new COL XR key (in $usage$key), full taxonomic classification, and match quality information to help you assess the conversion.

Before (rgbif 3.8.5 and earlier):

# Using numeric GBIF Backbone key
occ_search(taxonKey = 5231190, limit = 10)

After (rgbif 3.9.0):

# Use alpha-numeric key
occ_search(taxonKey = "Q2M4", limit = 10)

If you provide a numeric taxonomic key (e.g., taxonKey = 5231190), rgbif will automatically switch to the GBIF Backbone taxonomy and issue a warning:

occ_search(taxonKey = 5231190, limit = 10)
# Warning: Numeric taxonomic keys detected (taxonKey).
# These are legacy GBIF Backbone identifiers.
# Switching to Backbone checklistKey: d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
# Consider migrating to COL XR identifiers using gbif_to_col().

Occurrence Downloads

Before (rgbif 3.8.5 and earlier):

# Using numeric keys with pred()
occ_download(
  pred("taxonKey", 5231190),
  pred("hasCoordinate", TRUE)
)
# With warning about numeric keys

After (rgbif 3.9.0):

# Using alpha-numeric COL XR keys
occ_download(
  pred("taxonKey", "Q2M4"),
  pred("hasCoordinate", TRUE)
)

# Or get the key dynamically
key <- name_backbone(name = "Calopteryx splendens")$usageKey
occ_download(
  pred("taxonKey", key),
  pred("hasCoordinate", TRUE)
)

If you provide numeric taxonomic keys in your download predicates, rgbif will automatically inject the GBIF Backbone checklistKey into each predicate containing numeric keys and issue a warning:

occ_download(
  pred("taxonKey", 5231190),
  pred("hasCoordinate", TRUE)
)
# Warning: Numeric taxonomic keys detected in predicates.
# These are legacy GBIF Backbone identifiers.
# Switching to Backbone checklistKey: d7dddbf4-2cf0-4f39-9b2a-bb099caae36c
# at the predicate level.
# Consider migrating to COL XR identifiers using gbif_to_col().

This works with nested predicates too (e.g., pred_and(), pred_or()), ensuring existing code continues to work while encouraging migration to COL XR.

Batch Name Matching

Before (rgbif 3.8.5 and earlier):

species_list <- c("Calopteryx splendens", "Puma concolor", "Quercus robur")

# Returned numeric keys
results <- name_backbone_checklist(species_list)
results$usageKey
# [1] 5231190 2435099 2877951  # numeric keys

After (rgbif 3.9.0):

species_list <- c("Calopteryx splendens", "Puma concolor", "Quercus robur")

# Returns alpha-numeric COL XR keys
results <- name_backbone_checklist(species_list)
results$usageKey
# [1] "Q2M4" "9WLSS" "Q2N2"  # alpha-numeric keys

Maps

Before (rgbif 3.8.5 and earlier):

# Using numeric GBIF Backbone key for penguins
map_fetch(srs='EPSG:3031', taxonKey=2481660, style='glacier.point')

After (rgbif 3.9.0):

# Get COL XR key first
key <- name_backbone(name = "Spheniscidae")$usageKey
# key is "623RM"

# Use alpha-numeric key
map_fetch(srs='EPSG:3031', taxonKey="623RM", style='glacier.point')

Deprecated Functions

Three functions only work by default with the GBIF Backbone Taxonomy and will show deprecation warnings when a datasetKey is not provided.

Keep in mind that something like the following will not work even if you set the datasetKey to COL XR:

# will return error
name_usage(key="Q2M4",datasetKey="7ddf754f-d193-4cc9-b351-99906754a03b")

# use instead 
rcol::col_usage("Q2M4")