Lists taxon concepts
The following taxon concept fields are returned:
unique identifier of a taxon concept
scientific name [max 255 characters]
author and year (parentheses where applicable) [max 255 characters]
one of KINGDOM, PHYLUM, CLASS,
ORDER, FAMILY, SUBFAMILY,
GENUS, SPECIES, SUBSPECIES,
VARIETY [max 255 characters]
A for accepted names, S for synonyms (both types
of names are taxon concepts in Species+) [max 255 characters]
timestamp of last update to the taxon concept in Species+
if false, taxon concept has been deleted
list of synonyms (only for accepted names, i.e. name_status == A) [full_name, author_year and rank follow the same length constraints as respective properties of the main taxon concept]
object that gives scientific names of ancestors in the taxonomic tree (only for active accepted names) [higher taxa names follow the same length constraint as full_name of the main taxon concept]
list of common names (with language given by ISO 639-1 code; only for accepted names) [name, language max 255 characters]
value of current CITES listing (as per CITES Checklist). When taxon concept
is removed from appendices this becomes NC. When taxon is
split listed it becomes a concatenation of appendix symbols, e.g.
I/II/NC (only for accepted names) [max 255 characters]
list of current CITES listings with annotations (there will be more than one element in this list in case of split listings; only for accepted names) [appendix max 255 characters; annotation, hash_annotation unlimited length]
value of current EU listing. When taxon concept is removed from annexes
this becomes NC. When taxon is split listed it becomes a
concatenation of annex symbols, e.g. A/B/NC (only for accepted
names) [max 255 characters]
list of current EU listings with annotations (there will be more than one element in this list in case of split listings; only for accepted names) [appendix max 255 characters; annotation, hash_annotation unlimited length]
list of accepted names (only for synonyms, i.e. name_status == S) [full_name, author_year and rank follow the same length constraints as respective properties of the main taxon concept]
In the event of removal from CITES appendices, a taxon is not deleted from the Species+ DB. As a historically listed taxon it remains in the database, and in most cases the value of current CITES listing becomes 'NC'. In some cases the value is affected by listed subspecies, e.g. Pseudomys fieldi has been removed from Appendix I, but since there is a listed subspecies, the current listing is 'I/NC'.
Taxon concepts are deleted from the Species+ database only on rare occasions when they have been entered by mistake. API consumers can detect this event by checking the value of the 'active' flag, which is set to false in case of deleted taxa.
updated_since¶ ↑The updated_since parameter is intended to be used in order to
allow API clients to only fetch taxon concepts updated since the last run
of the synchronisation job. Those taxa will include:
Taxa that have been newly added. This can be verified by checking against the list of existing identifiers.
Taxa that have been deleted. This can be inferred by the value of the active flag.
Taxa that have been updated, and that includes changes to the taxon concept record as well as linked records (names, distribution, references, CITES or EU legislation). There is no way to infer which piece of information was changed and in such cases a full re-synchronisation of all infomation on that taxon concept is recommended.
Where more than 500 taxon concepts are returned, the request is paginated, showing 500 objects (or less by passing in an optional 'per_page' parameter) at a time. To fetch the remaining objects, you will need to make a new request and pass the optional ‘page’ parameter as below:
https://api.speciesplus.net/api/v1/taxon_concepts?page=2&per_page=25
Information about the remaining pages is provided in the Link header of the API response. For example, making the above request for page two, with a limit of 25 objects per page would return the following in the link header along with a total-count header:
Link: <https://api.speciesplus.net/api/v1/taxon_concepts?page=3&per_page=25>; rel="next", <https://api.speciesplus.net/api/v1/taxon_concepts?page=2570&per_page=25>; rel="last" Total-Count: 64230
If there are additional pages, the link header will contain the URL for the next page of results, followed by the URL for the last page of results. The Total-Count header shows the total number of objects returned for this call, regardless of pagination.
For convenience, a 'pagination' meta object is also included in the body of the response.
{
"pagination":{
"current_page":1,
"per_page":500,
"total_entries":1
},
"taxon_concepts":[
{
"id":4521,
"full_name":"Loxodonta africana",
"author_year":"(Blumenbach, 1797)",
"rank":"SPECIES",
"name_status":"A",
"updated_at":"2014-12-11T15:39:51.620Z",
"active":true,
"cites_listing":"I/II",
"higher_taxa":{
"kingdom":"Animalia",
"phylum":"Chordata",
"class":"Mammalia",
"order":"Proboscidea",
"family":"Elephantidae"
},
"synonyms":[
{
"id":37069,
"full_name":"Loxodonta cyclotis",
"author_year":"(Matschie, 1900)",
"rank":"SPECIES"
}
],
"common_names":[
{
"name":"African Elephant",
"language":"EN"
},
{
"name":"African Savannah Elephant",
"language":"EN"
},
{
"name":"Eléphant d'Afrique",
"language":"FR"
},
{
"name":"Eléphant africain",
"language":"FR"
}
],
"cites_listings":[
{
"appendix":"II",
"annotation":"The populations of Botswana, Namibia, South Africa and Zimbabwe are listed in Appendix II for the exclusive purpose of allowing: [...]",
"hash_annotation":null
},
{
"appendix":"I",
"annotation":"Included in Appendix I, except the populations of Botswana, Namibia, South Africa and Zimbabwe, which are included in Appendix II.",
"hash_annotation":null
}
],
"eu_listings":[
{
"id":"32796"
"annex":"A"
"annotation":"Except for the populations of Botswana, Namibia, South Africa and Zimbabwe, which are included in Annex B."
"hash_annotation":nil
"effective_at":"2022-01-19"
"party":nil
},
{
"id":"34129"
"annex":"B"
"annotation":"Only the populations of Botswana, Namibia, South Africa and Zimbabwe; all other populations are included in Annex A. [...]"
"hash_annotation":nil
"effective_at":"2022-01-19"
"party":nil
}
]
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<pagination>
<current-page type="integer">1</current-page>
<per-page type="integer">500</per-page>
<total-entries type="integer">1</total-entries>
</pagination>
<taxon-concepts type="array">
<taxon-concept>
<id type="integer">4521</id>
<full-name>Loxodonta africana</full-name>
<author-year>(Blumenbach, 1797)</author-year>
<rank>SPECIES</rank>
<name-status>A</name-status>
<updated-at type="dateTime">2014-12-11T15:39:51Z</updated-at>
<active type="boolean">true</active>
<cites-listing>I/II</cites-listing>
<higher-taxa>
<kingdom>Animalia</kingdom>
<phylum>Chordata</phylum>
<class>Mammalia</class>
<order>Proboscidea</order>
<family>Elephantidae</family>
</higher-taxa>
<synonyms type="array">
<synonym>
<id type="integer">37069</id>
<full-name>Loxodonta cyclotis</full-name>
<author-year>(Matschie, 1900)</author-year>
<rank>SPECIES</rank>
</synonym>
</synonyms>
<common-names type="array">
<common-name>
<name>African Elephant</name>
<language>EN</language>
</common-name>s
<common-name>
<name>African Savannah Elephant</name>
<language>EN</language>
</common-name>
<common-name>
<name>Eléphant d'Afrique</name>
<language>FR</language>
</common-name>
<common-name>
<name>Eléphant africain</name>
<language>FR</language>
</common-name>
</common-names>
<cites-listings type="array">
<cites-listing>
<appendix>II</appendix>
<annotation>The populations of Botswana, Namibia, South Africa and Zimbabwe are listed in Appendix II for the exclusive purpose of allowing: [...]</annotation>
<hash-annotation nil="true"/>
</cites-listing>
<cites-listing>
<appendix>I</appendix>
<annotation>Included in Appendix I, except the populations of Botswana, Namibia, South Africa and Zimbabwe, which are included in Appendix II.</annotation>
<hash-annotation nil="true"/>
</cites-listing>
</cites-listings>
<eu-listings>
<eu-listing>
<id type="integer">32796</id>
<annex>A</annex>
<annotation>Except for the populations of Botswana, Namibia, South Africa and Zimbabwe, which are [...]</annotation>
<hash-annotation inl="true"/>
<effective-at>2022-01-19</effective-at>
<party nil="true"/>
</eu-listing>
<eu-listing>
<id type="integer">34129</id>
<annex>B</annex>
<annotation>Only the populations of Botswana, Namibia, South Africa and Zimbabwe; all other populations are [...]</annotation>
<hash-annotation inl="true"/>
<effective-at>2022-01-19</effective-at>
<party nil="true"/>
</eu-listing>
</eu-listings>
</taxon-concept>
</taxon-concepts>
</hash>
| Param name | Description |
|---|---|
|
page optional |
Page number for paginated responses Value: Must be String |
|
per_page optional |
Limit for how many objects returned per page for paginated responses. If not specificed it will default to the maximum value of 500 Value: Must be String |
|
updated_since optional |
Pull only objects updated after (and including) the specified timestamp in ISO8601 format (UTC time). Value: Must be String |
|
name optional |
Filter taxon concepts by name Value: Must be String |
|
with_descendants optional |
Broadens the above search by name to include higher taxa. Value must be true or false Value: Must be String |
|
taxonomy optional |
Filter taxon concepts by taxonomy, accepts either CITES or CMS as its value. Defaults to CITES if no value is specified Value: Must be String |
|
language optional |
Filter languages returned for common names. Value should be a single country code or a comma separated string of country codes (e.g. language=EN,PL,IT). Defaults to showing all available languages if no language parameter is specified Value: Must be String |
|
with_eu_listings optional |
Include EU listing data. Value must be true or false, defaults to false Value: Must be String |
