What is {int} in the species API? is it: taxonID or taxonKey (and are they the same thing?)

[therobyouknow]

On page developer/species url on gbif dot org,

{int} is referred to in several API endpoint calls, e.g. /species/{int}

I believe {int} is taxonID, would I be correct?

Also, another question, is taxonID the same thing as taxonKey ? (are the synonyms?)

I believe {int} is the taxonID because I downloaded hosted-backbone-current.zip from datasets dot gbif dot org slash datasets slash backbone slash hosted-backbone-current.zip and in the enclosed file, Taxon.csv, if I look at the taxonID and then use that in the above call to the GBIF API species/5509692 I get a result back that contains field data that looks the same as in the row for 5509692 in the Taxon.csv file.

Thank you.

[ahahn]

That {int} would be the taxonKey (or other relevant key, see the other post you linked), according to the GBIF species API (see the small print under “working with name usages”). There is also a blog post about the API.

Be aware that this relates to name usages, that is: the application of a taxon name in the context of a given checklist, including the GBIF taxonomic backbone as one of those checklists. Any one name can occur in multiple checklists, possibly with different information about higher taxonomy, synonymy, etc. Even though they may look identical, they will have different taxonKeys. The GBIF backbone taxonomy is the large, aggregate checklist dataset that is used to organize species occurrence records, but in technical terms, it is just one of a number of checklists, with its particular name usages.

The various ~Key values cross-reference entries within the GBIF backbone and other indexed checklist datasets, as explained in the other post that you referenced this one from. They will always be {int} values.

A taxonID, on the other hand, is a term defined in the Darwin Core data standard as:

Label: Taxon ID
Definition: An identifier for the set of taxon information (data associated with the Taxon class). May be a global unique identifier or an identifier specific to the data set.
Examples: 8fa58e08-08de-4ac1-b69c-1235340b7001 , 32567 , https://www.gbif.org/species/212

As such, a TaxonID is a value that is part of the originating source dataset, intended to uniquely identify the taxon within a given context, and may come in various formats, not necessarily integer. A name source dataset (checklist dataset in the GBIF context) does have to provide unique taxonIDs for taxon records within the dataset itself in order to be indexed by GBIF. These TaxonIDs are maintained in the indexed version. Weaving these resources together into the GBIF taxonomic backbone taxonomy and index, the records get issued GBIF key values on top of that, which are used to specify the relationships between records all across.

I hope this explains it a bit, but let us know if you have more questions about this.

[therobyouknow]

Thank you very much @ahahn I will absorb this information into my thoughts.

I had observed that:
GBIF API / v1/species/1341976
and
gbif org species/1341976

return the same species as per following screenshot.

Indeed, https://github.com/gbif/portal-feedback/issues/1820#issuecomment-470023851 states it as being a key, though I do note that the Taxon.tsv from https://hosted-datasets.gbif.org/datasets/backbone/backbone-current.zip has a column taxonID which is an integer, which can be used in the above 2 URL calls I mention, which call it the taxonKey.

But taking on your definitive advice and the above, my conclusion so far, is that taxonID and taxonID can be the same thing, and that it depends. Depends on where that data comes from.

I’d always agree with your definitive advice and I think my finding above would agree with that and I will understood why when I’ve thought more about your advice. Most appreciated! Thank you.