[GET] api/v1/taxon_concepts

Description

Lists taxon concepts

The following taxon concept fields are returned:

id: unique identifier of a taxon concept
full_name: scientific name [max 255 characters]
author_year: author and year (parentheses where applicable) [max 255 characters]
rank: one of KINGDOM, PHYLUM, CLASS, ORDER, FAMILY, SUBFAMILY, GENUS, SPECIES, SUBSPECIES, VARIETY [max 255 characters]
name_status: A for accepted names, S for synonyms (both types of names are taxon concepts in Species+) [max 255 characters]
updated_at: timestamp of last update to the taxon concept in Species+
active: if false, taxon concept has been deleted
synonyms: 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]
higher_taxa: 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]
common_names: list of common names (with language given by ISO 639-1 code; only for accepted names) [name, language max 255 characters]
cites_listing: 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]
cites_listings: 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]
eu_listing: 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]
eu_listings: 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]
accepted_names: 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]

Note on deleted taxon concepts¶ ↑

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.

Note on `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.

Note on pagination¶ ↑

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.

Supported Formats

JSON, XML

Errors

400 Bad Request
401 Unauthorized
404 Not Found
422 Unprocessable Entity
500 Internal Server Error

{
  "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>

Params

Param name	Description
page optional	Page number for paginated responses Value: Must be a 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 a String
updated_since optional	Pull only objects updated after (and including) the specified timestamp in ISO8601 format (UTC time). Value: Must be a String
name optional	Filter taxon concepts by name Value: Must be a String
with_descendants optional	Broadens the above search by name to include higher taxa. Value must be true or false Value: Must be a 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 a 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 a String
with_eu_listings optional	Include EU listing data. Value must be true or false, defaults to false Value: Must be a String

Feedback