The power of sharing species data – an overview of the Species+ API
Species+, developed by UNEP-WCMC and the CITES Secretariat, is a website designed to assist Parties with implementing CITES, CMS and other multilateral environmental agreements (MEAs). Species+ provides a centralised portal for accessing key information on species of global concern.
In particular, Species+ contains information on all species that are listed in the Appendices of CITES and CMS, as well as other CMS Family listings and species included in the Annexes to the EU Wildlife Trade Regulations.
Since the launch of the CITES Checklist and Species+, the Secretariat has worked with UNEP-WCMC, Belgium, France and Switzerland on the development of web services to allow Parties to extract, inter alia, species’ scientific and common names and the relevant Appendix number directly into national CITES checklists or CITES electronic permits and certificates.
Canada geese / Paul Sullivan / CC BY-ND 2.0
Species+/CITES Checklist API
The Species+/CITES Checklist API enables a user to request data from Species+ and CITES Checklist to be used in websites and databases regardless of the technology used. How an API works is very simple and a basic diagram is given below:
As described by the diagram, the entire process can be splitted into 4 steps:
This step is required to prevent unauthorized access to the protected resources. The user needs to sign up and to have a token generated for them. At this point the user can then send authorized requests to the Species+ server using that valid token.
The client submits a request using its token to one of the following available endpoints:
Each endpoint provides a different set of data, with the possibility to be filtered using optional parameters. Taking for example the Taxon Concepts endpoint, the user can use the following URL to get several information regarding all the species in the Species+ database:
api.speciesplus.net/api/v1/taxon_concepts
As you may have noticed, no optional parameters have been used and no response format has been specified. In this case, the request is paginated since more than 500 species are returned and the output of the response is delivered in JSON format by default.
The following is an example with optional parameters where we want to fetch 100 species per page and also select the second page:
api.speciesplus.net/api/v1/taxon_concepts?page=2&per_page=100
The main goal of the Taxon Concepts endpoint is to keep the list of all taxa up-to-date using it regularly as to find out about any possible changes, including deletion, that have occurred since the last synchronization. Note that in case of removal from CITES appendices, a taxon is not deleted from the Species+ database but it will be just marked as such. A taxon concept is deleted from the database only if it has been entered by mistake.
A full explanation of all endpoints is provided in the documentation page.
3. Request processing - Data retrieval
Once the request is taken successfully and verified, the requested data is retrieved from the Species+ Database.
The API sends the data to the client who made the request using the previously specified format (JSON or XML).
These are the essential steps for building a pipeline capable of automatically updating the client system with fetched data. If, for example, the user of the API is maintaining a species database by his/her own, he or she can automatically synchronize that database with the Species+ one. Another use case could be simply fetching the data using the API and processing the response to be used on another website.
An Application Programming Interface is a powerful instrument for sharing centralized content between applications and communities in an automatic and dynamic way. It’s a lot different than just having a website where you manually search for information.
With the Species+/CITES Checklist API we are allowing parties building pipelines to automatically update their own databases, helping them with their analysis procedures and with the achievement of several goals.
The possibilities are endless; everyone can use the API, everyone can fetch the data, everyone can benefit from the power of sharing information.
“In the long history of humankind (and animal kind too), those who learned to collaborate and improvise most effectively have prevailed” - Charles Darwin