Interprétation taxonomique

Support de plusieurs taxonomies

Afin de faciliter la recherche et la génération de mesures, tous les enregistrements d’occurrences sont mis en correspondance avec deux taxonomies :

Catalogue of Life eXtended Release (COL XR) - Il s’agit de la taxonomie principale utilisée par le GBIF. Catalogue of Life est un index mondial des espèces qui vise à fournier une liste complète et faisant autorité des espèces existant dans le monde. Il est compilé à partir de multiples ensembles de données taxonomiques et est régulièrement mis à jour. Le eXtended Release (COL XR) s’appuie sur le Base Release en intégrant de manière programmatique des sources de données supplémentaires. Il intègre des informations provenant de plus de 58 000 sources de données taxonomiques et nomenclaturales mondiales, régionales, nationales et de gestion (listes de contrôle) qui se recoupent, ainsi que des données issues de la littérature numérisée disponible dans l’infrastructure du Catalogue of Life ChecklistBank.
GBIF backbone - Il s’agit d’une taxonomie que, jusqu’à récemment, le GBIF construisait et intégrait périodiquement. Elle repose principalement sur une ancienne version du Catalogue of Life, à laquelle ont été ajoutés automatiquement des taxons provenant d’autres ensembles de données taxonomiques. Le processus de construction a désormais été interrompu au profit du eXtended release du Catalogue of Life. Le GBIF Backbone ne sera plus mis à jour, mais restera disponible à des fins de rétrocompatibilité. Tous les identifiants GBIF Backbone seront conservés et supportés dans l’API.

Assistance API

L’API GBIF permet de rechercher et de récupérer des enregistrements d’occurrences à l’aide de l’une ou l’autre taxonomie. Vous pouvez spécifier la taxonomie à l’aide du paramètre de requête facultatif checklistKey. Si ce paramètre n’est pas fourni, l’API utilise par défaut la taxonomie GBIF backbone.

Les valeurs valides pour ce paramètre sont les clés des ensembles de données taxonomiques enregistrées dans GBIF.

Les valeurs actuellement supportées sont les suivantes :

checklistKey=7ddf754f-d193-4cc9-b351-99906754a03b pour le Catalogue of Life eXtended Release
checklistKey=d7dddbf4-2cf0-4f39-9b2a-bb099caae36c pour le GBIF backbone.

Les sous-sections suivantes décrivent comment l’API soutien plusieurs taxonomies.

Correspondance taxonomique

Pour chaque enregistrement d’occurrence, GBIF tente de faire correspondre cet enregistrement à un taxon dans chaque taxonomie. Par conséquent, chaque occurrence se voit attribuer des taxonKeys qui renvoient au taxon correspondant à la fois dans le GBIF Backbone et dans le Catalogue of Life.

Ces clés sont récupérées en interrogeant notre API de correspondance des espèces, selon que les champs Darwin Core suivants ont été fournis par l’éditeur de données avec l’enregistrement d’occurrence :

Vous trouverez plus de détails sur les paramètres et les formats de réponse dans la documentation API.

Si le scientificName n’est pas présent dans l’enregistrement d’occurrence publié, il sera assemblé à partir des différentes parties du nom, si elles sont présentes : genus, specificEpithet, genericName et infraspecificEpithet. Le fait d’avoir une classification supérieure qualifiant le scientificName améliore la précision de la correspondance taxonomique de deux manières, même s’il s’agit simplement de la famille ou même du règne.

Dans le cas d’homonymes ou de noms orthographiés de manières similaire, le service n’a aucun moyen de vérifier les correspondances potentielles, de sorte que ces noms obtiennent souvent des correspondances taxonomiques plus élevées.
Si un nom scientifique donné ne fait pas (encore) partie de la taxonomie, le GBIF peut au moins associer l’enregistrement à un taxon supérieur dans cette taxonomie, tel que le genre.

Fuzzy name matching, matching to a higher taxon or matching to no taxon are issue flags we assign to records.

Correspondance basée sur l’identifiant

The version 2 of the species matching API supports searching with the identifier fields taxonID, scientificNameID or taxonConceptID as query parameters. If both an identifier field and a scientificName are provided, the identifier field will be used first for matching. A match will also be made using the scientificName and a comparison will be made between the two matches. If they do not agree, a flag will be issued in the response to indicate the inconsistency.

Correspondance par rapport aux différentes taxonomies

Le paramètre facultatif checklistKey spécifie la taxonomie à laquelle il faut faire correspondre.

Exemple de demande de correspondance avec le COL XR

curl -s "http://api.gbif.org/v2/species/match?scientificName=Acacia+acuminata&checklistKey=7ddf754f-d193-4cc9-b351-99906754a03b"

Le format de réponse version 2 qui comprend des informations supplémentaires telles que la catégorie de la catégorie de l’IUCN RedList pour le taxon, si disponible.

Exemple de réponse pour une correspondance avec le COL XR :

{
  "usage": {
    "key": "5WZLF",
    "name": "Carcharodon carcharias (Linnaeus, 1758)",
    "canonicalName": "Carcharodon carcharias",
    "authorship": "(Linnaeus, 1758)",
    "rank": "SPECIES",
    "code": "ZOOLOGICAL",
    "status": "ACCEPTED",
    "genericName": "Carcharodon",
    "specificEpithet": "carcharias",
    "type": "SCIENTIFIC",
    "formattedName": "<i>Carcharodon</i> <i>carcharias</i> (Linnaeus, 1758)"
  },
  "classification": [
    {
      "key": "CS5HF",
      "name": "Eukaryota",
      "rank": "DOMAIN"
    },
    {
      "key": "N",
      "name": "Animalia",
      "rank": "KINGDOM"
    },
    {
      "key": "CH2",
      "name": "Chordata",
      "rank": "PHYLUM"
    },
    {
      "key": "8V4V3",
      "name": "Vertebrata",
      "rank": "SUBPHYLUM"
    },
    {
      "key": "8V4V5",
      "name": "Gnathostomata",
      "rank": "INFRAPHYLUM"
    },
    {
      "key": "8X6G5",
      "name": "Chondrichthyes",
      "rank": "PARVPHYLUM"
    },
    {
      "key": "LB",
      "name": "Elasmobranchii",
      "rank": "CLASS"
    },
    {
      "key": "3F5",
      "name": "Lamniformes",
      "rank": "ORDER"
    },
    {
      "key": "CB2M7",
      "name": "Lamnidae",
      "rank": "FAMILY"
    },
    {
      "key": "C973Q",
      "name": "Carcharodon",
      "rank": "GENUS"
    },
    {
      "key": "5WZLF",
      "name": "Carcharodon carcharias",
      "rank": "SPECIES"
    }
  ],
  "diagnostics": {
    "matchType": "EXACT",
    "confidence": 99,
    "timeTaken": 22,
    "timings": {
      "nameNRank": 0,
      "sciNameMatch": 22,
      "nameParse": 1,
      "luceneMatch": 21
    }
  },
  "additionalStatus": [
    {
      "clbDatasetKey": "53131",
      "datasetAlias": "IUCN",
      "datasetKey": "19491596-35ae-4a91-9a98-85cf505f1bd3",
      "status": "VULNERABLE",
      "statusCode": "VU",
      "sourceId": "3855"
    }
  ],
  "synonym": false,
  "left": 1049700,
  "right": 1049701
}

API de recherche d’occurrences

L' API de recherche d’occurrences support les requêtes avec l’une ou l’autre taxonomie en incluant le paramètre facultatif checklistKey dans la requête.

Exemple : bash curl -s "http://api.gbif.org/v1/occurrence/search?scientificName=Acacia+acuminata&checklistKey=7ddf754f-d193-4cc9-b351-99906754a03b"

Format de réponse

La réponse de l' API d’occurrence a été étendue afin d’inclure les informations taxonomiques provenant de plusieurs taxonomies. Le tableau classifications contient les informations taxonomiques provenant de toutes les taxonomies qui ont été associées à l’enregistrement d’occurrence. Remarque : la réponse de l’exemple a été raccourcie par souci de concision.

{
      "key": 5104646682,
      "datasetKey": "50c9509d-22c7-4a22-a47d-8c48425ef4a7",
      "basisOfRecord": "HUMAN_OBSERVATION",
      "occurrenceStatus": "PRESENT",
      "classifications": {
        "7ddf754f-d193-4cc9-b351-99906754a03b": {
          "usage": {
            "key": "BSJCX",
            "name": "Acacia acuminata Benth.",
            "rank": "SPECIES",
            "code": "BOTANICAL",
            "authorship": "Benth.",
            "genericName": "Acacia",
            "specificEpithet": "acuminata",
            "formattedName": "<i>Acacia</i> <i>acuminata</i> Benth."
          },
          "acceptedUsage": {
            "key": "BSJCX",
            "name": "Acacia acuminata Benth.",
            "rank": "SPECIES",
            "code": "BOTANICAL",
            "authorship": "Benth.",
            "genericName": "Acacia",
            "specificEpithet": "acuminata",
            "formattedName": "<i>Acacia</i> <i>acuminata</i> Benth."
          },
          "taxonomicStatus": "ACCEPTED",
          "classification": [
            {
              "key": "CS5HF",
              "name": "Eukaryota",
              "rank": "DOMAIN"
            },
            {
              "key": "P",
              "name": "Plantae",
              "rank": "KINGDOM"
            },
            {
              "key": "CMQ8S",
              "name": "Pteridobiotina",
              "rank": "SUBKINGDOM"
            },
            {
              "key": "TP",
              "name": "Tracheophyta",
              "rank": "PHYLUM"
            },
            {
              "key": "MG",
              "name": "Magnoliopsida",
              "rank": "CLASS"
            },
            {
              "key": "383",
              "name": "Fabales",
              "rank": "ORDER"
            },
            {
              "key": "623QT",
              "name": "Fabaceae",
              "rank": "FAMILY"
            },
            {
              "key": "C8VYK",
              "name": "Acacia",
              "rank": "GENUS"
            },
            {
              "key": "BYZSL",
              "name": "Juliflorae",
              "rank": "SECTION_BOTANY"
            },
            {
              "key": "BSJCX",
              "name": "Acacia acuminata",
              "rank": "SPECIES"
            }
          ],
          "iucnRedListCategoryCode": "LC",
          "issues": [
            "TAXON_ID_NOT_FOUND"
          ]
        },
        "d7dddbf4-2cf0-4f39-9b2a-bb099caae36c": {
          "usage": {
            "key": "2979180",
            "name": "Acacia acuminata Benth.",
            "rank": "SPECIES",
            "authorship": "Benth.",
            "genericName": "Acacia",
            "specificEpithet": "acuminata",
            "formattedName": "<i>Acacia</i> <i>acuminata</i> Benth."
          },
          "acceptedUsage": {
            "key": "2979180",
            "name": "Acacia acuminata Benth.",
            "rank": "SPECIES",
            "authorship": "Benth.",
            "genericName": "Acacia",
            "specificEpithet": "acuminata",
            "formattedName": "<i>Acacia</i> <i>acuminata</i> Benth."
          },
          "taxonomicStatus": "ACCEPTED",
          "classification": [
            {
              "key": "6",
              "name": "Plantae",
              "rank": "KINGDOM"
            },
            {
              "key": "7707728",
              "name": "Tracheophyta",
              "rank": "PHYLUM"
            },
            {
              "key": "220",
              "name": "Magnoliopsida",
              "rank": "CLASS"
            },
            {
              "key": "1370",
              "name": "Fabales",
              "rank": "ORDER"
            },
            {
              "key": "5386",
              "name": "Fabaceae",
              "rank": "FAMILY"
            },
            {
              "key": "2978223",
              "name": "Acacia",
              "rank": "GENUS"
            },
            {
              "key": "2979180",
              "name": "Acacia acuminata",
              "rank": "SPECIES"
            }
          ],
          "iucnRedListCategoryCode": "LC",
          "issues": [
            "TAXON_ID_NOT_FOUND"
          ]
        }
      }
    }

API de téléchargement d’occurrences

L’API de téléchargement des occurrences support le téléchargement des enregistrements d’occurrences à l’aide de l’une ou l’autre taxonomie.

Prédicats de téléchargement d’occurrence

L’API de recherche prédicative comprend le paramètre checklistKey qui permet de spécifier la taxonomie à utiliser pour filtrer les enregistrements d’occurrence.

Exemple :

{
  "creator": "userName",
  "sendNotification": false,
  "format": "SIMPLE_CSV",
  "predicate": {
      "type": "equals",
      "key": "TAXON_KEY",
      "value": "5WZLF",
      "checklistKey": "7ddf754f-d193-4cc9-b351-99906754a03b"
  }
}

Contenu du téléchargement d’occurrence

Les utilisateurs peuvent spécifier la taxonomie à inclure dans les téléchargements d’occurrences en ajoutant le paramètre checklistKey à la demande de téléchargement. Par défaut, le GBIF Backbone sera utilisé si aucun checklistKey n’est fourni.

{
  "creator": "userName",
  "notificationAddresses": [
    "userEmail@example.org"
  ],
  "sendNotification": true,
  "format": "SIMPLE_CSV",
  "predicate": {
    "type": "and",
    "predicates": [
      {
        "type": "equals",
        "key": "BASIS_OF_RECORD",
        "value": "PRESERVED_SPECIMEN"
      },
      {
        "type": "in",
        "key": "COUNTRY",
        "values": [ "VC", "GD" ]
      }
    ]
  },
  "checklistKey": "7ddf754f-d193-4cc9-b351-99906754a03b"
}

Pour plus d’informations sur l’API de téléchargement, consultez la documentation de l’API.

Index taxonomiques

À chaque mise à jour d’une taxonomie, des conteneurs docker versionnés sont créés pour supporter l’API d’appariement des espèces API. Ces conteneurs sont mis à disposition via le registre docker du GBIF et peuvent être utilisés localement sans dépendre des services en ligne.

Les index des conteneurs docker sont créés à partir de ChecklistBank, qui fournit les données taxonomiques organisées, les noms et la hiérarchie.

En outre, des identificateurs uniques stables pour les taxons provenant d’autres ensembles de données taxonomiques tels que Dyntaxa, IPNI, ITIS, UK Species Inventory et WoRMs sont extraits de ChecklistBank et liés aux taxons de la liste de contrôle (par exemple, COL XR ou GBIF Backbone).

Cela permet la mise en correspondance à l’aide des champs scientificNameID, taxonID ou taxonConceptID si ces identifiants sont utilisés par les éditeurs de données.

La catégorie de l’IUCN RedList est également liée aux taxons dans l’index. Les informations de l’IUCN RedList sont extraites de ChecklistBank lorsque les conteneurs docker sont créés et liés à la liste de contrôle (par exemple, COL XR ou GBIF Backbone).

Conteneurs docker

Tous les conteneurs correspondants disponibles dans le registre docker GBIF sont répertoriés ici

Les balises d’image sont composées de plusieurs éléments d’information :

{taxonomy}-{architecture}-{checklistbank-datasetKey}-{date}-{time}

Ainsi, l’image xcol-arm64-308651-20250516-145444 expose le COL eXtended Release avec datasetKey=308651 et a été créée le 16 mai 2025.

Vous pouvez également télécharger et exécuter la dernière version de COL XR comme suit :

# use arm64 image instead of amd64 on a mac with apple silicon docker run -d -p 8080:8080 --name colxr docker.gbif.org/matching-ws:xcol-arm64-latest ```


Une fois fonctionné, les métadonnées relatives aux données indexées peuvent être récupérées :

```bash curl -s "http://localhost:8080/v2/species/match/metadata" ```

Exemple d'URL de requête utilisant un conteneur docker local : ```bash curl -s "http://localhost:8080/v2/species/match?scientificName=Oenanthe&scientificNameAuthorship=L.&taxonRank=genus&kingdom=Plantae" ```