<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><meta http-equiv=Content-Type content="text/html; charset=utf-8"><meta name=Generator content="Microsoft Word 15 (filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
span.EmailStyle20
{mso-style-type:personal-compose;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--></head><body lang=EN-GB link=blue vlink=purple style='word-wrap:break-word'><div class=WordSection1><p class=MsoNormal><span style='mso-fareast-language:EN-US'>Dear Markus,<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'>Thanks for this information, it is very welcome.<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'>One quick question: I develop an application that depends on the old-style taxon identifiers (e.g., c526234e655cec65618f58161d24932a), as it uses its own dataset that cross-references these. It currently uses the 2019 annual checklist webservice:<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><a href="https://www.catalogueoflife.org/annual-checklist/2019/webservice?name=Picea%20abies%20abies&format=json">https://www.catalogueoflife.org/annual-checklist/2019/webservice?name=Picea%20abies%20abies&format=json</a><o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'>I would be happy to migrate to the new webservice API, but that would only possible if I can still query taxonomic classifications by old-style taxon id, as well as search for old-style taxon ids by taxon name. Is that possible? I do not immediately see an attribute with the old identifier in the sample queries you provided.<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'>And should migration to the new API not be possible for me: could you give an indication how long the 2019 annual checklist webservice is expected to remain available?<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'>Best,<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'>Jorn<o:p></o:p></span></p><p class=MsoNormal><span style='mso-fareast-language:EN-US'><o:p> </o:p></span></p><div><div style='border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0cm 0cm 0cm'><p class=MsoNormal><b><span lang=EN-US>From:</span></b><span lang=EN-US> COL-Users <col-users-bounces@lists.gbif.org> <b>On Behalf Of </b>Markus Döring<br><b>Sent:</b> 17 March 2021 12:31<br><b>To:</b> col-users@lists.gbif.org<br><b>Subject:</b> [COL-Users] API Introduction<o:p></o:p></span></p></div></div><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>Dear all, <o:p></o:p></p><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>as you all know at the end of last year the Catalogue of Life has moved to a whole new infrastructure and now offers a new and richer API.<o:p></o:p></p></div><div><p class=MsoNormal>As I had a few similar requests vie email lately I thought it would be good to give you a quick introduction to get started, while we are still working on better documentation.<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>The basic concept has changed in the sense that the API does not only expose the Catalogue of Life (COL), but all of ChecklistBank (CLB) which hosts a large number of taxonomic or nomenclatural datasets including the sources that we use to assemble the COL. You can read here more about it: <a href="https://www.catalogueoflife.org/about/colpipeline">https://www.catalogueoflife.org/about/colpipeline</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>The base URL of the API uses Swagger to exposes a rudimentary documentation of all the available REST resources and allows you to test it with real data: <a href="https://api.catalogueoflife.org">https://api.catalogueoflife.org</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>In order to access the latest version of COL you need to use the datasetKey=3LR (note that the swagger generated API docs do not allow strings, please use the currents release key 2242 for testing or curl). Pretty much all calls of interest to you should be scoped under <a href="http://api.catalogueoflife.org/dataset/3LR">http://api.catalogueoflife.org/dataset/3LR</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>In order to search for a name you could be doing this:<o:p></o:p></p></div><div><p class=MsoNormal><a href="http://api.catalogueoflife.org/dataset/3LR/nameusage/search?q=Abies&rank=SPECIES&status=ACCEPTED">http://api.catalogueoflife.org/dataset/3LR/nameusage/search?q=Abies&rank=SPECIES&status=ACCEPTED</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>To get taxon details for a given taxonID this does most of it:<o:p></o:p></p></div><div><p class=MsoNormal>Basics: <a href="http://api.catalogueoflife.org/dataset/2242/taxon/5QQJ9">http://api.catalogueoflife.org/dataset/2242/taxon/5QQJ9</a><o:p></o:p></p></div><div><p class=MsoNormal>Full Infos: <a href="http://api.catalogueoflife.org/dataset/2242/taxon/5QQJ9/info">http://api.catalogueoflife.org/dataset/2242/taxon/5QQJ9/info</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>To browse the tree you can use the Tree API which in its basic form works like this:<o:p></o:p></p></div><div><p class=MsoNormal>Root taxa: <a href="http://api.catalogueoflife.org/dataset/3LR/tree">http://api.catalogueoflife.org/dataset/3LR/tree</a><o:p></o:p></p></div><div><p class=MsoNormal>Plant Children: <a href="http://api.catalogueoflife.org/dataset/3LR/tree/P">http://api.catalogueoflife.org/dataset/3LR/tree/P/children</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>We now also offer reusable React UI components that you can embed in your own site or application to browse the tree, search and present species pages: <a href="https://github.com/CatalogueOfLife/portal-components">https://github.com/CatalogueOfLife/portal-components</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><div><p class=MsoNormal>We have also migrated the previous "legacy" API which you can access with the latest data from <a href="https://api.catalogueoflife.org/col/webservice?name=Abies%20alba&format=json&response=full">https://api.catalogueoflife.org/col/webservice</a> like this:<o:p></o:p></p></div><div><p class=MsoNormal><a href="https://api.catalogueoflife.org/col/webservice?name=Abies%20alba&format=json&response=full">https://api.catalogueoflife.org/col/webservice?name=Abies%20alba&format=json&response=full</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>There are a few small differences how we treat references compared to the previous version, otherwise it should work just as before.<o:p></o:p></p></div><div><p class=MsoNormal>We do consider this a legacy API and would like to encourage everyone using it still to migrate to our new API above.<o:p></o:p></p></div></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>Please don't hesitate to ask any questions on this list if you want to know more on how to use our API.<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>With best wishes,<o:p></o:p></p></div><div><p class=MsoNormal>Markus<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><p class=MsoNormal>+++ COL RESOURCES +++<br><br>COL Website:<br><a href="http://www.catalogueoflife.org/">http://www.catalogueoflife.org/</a> <o:p></o:p></p><div><p class=MsoNormal><br>COL ChecklistBank:<br><a href="http://data.catalogueoflife.org/">http://data.catalogueoflife.org/</a> <o:p></o:p></p><div><p class=MsoNormal><br>COL ChecklistBank API:<br><a href="http://api.catalogueoflife.org/">http://api.catalogueoflife.org/</a> <o:p></o:p></p><div><p class=MsoNormal><br>COL latest release in API:<o:p></o:p></p><div><p class=MsoNormal><a href="http://api.catalogueoflife.org/dataset/3LR">http://api.catalogueoflife.org/dataset/3LR</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p><div><div><div><div><div><div><p class=MsoNormal>--<br>Markus Döring<o:p></o:p></p></div><div><p class=MsoNormal>Lead Developer Catalogue of Life<br>Global Biodiversity Information Facility (GBIF)<o:p></o:p></p><div><p class=MsoNormal><a href="mailto:mdoering@gbif.org">mdoering@gbif.org</a><o:p></o:p></p></div><div><p class=MsoNormal><a href="http://www.gbif.org/">http://www.gbif.org</a><o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div></div></div></div></div></div></div></div></div></div></div></div></body></html>