Table of Contents - 30th October 2017 Web Service v1.9 rev 2126ab0

 

1. URL

          1.1 Parameters

          1.2 Example URLs

2. XML format

          2.1 Basic format

                   2.1.1 Terse format

                   2.1.2 Full format

          2.2 Accepted species and infraspecific names

                   2.2.1 Terse format

                   2.2.2 Full format

          2.3 Species or infraspecific synonyms

                   2.3.1 Terse format

                   2.3.2 Full format

          2.4 Common names for species or infraspecific taxa

                   2.4.1 Terse format

                   2.4.2 Full format

          2.5 Higher taxa

                   2.5.1 Terse format

                   2.5.2 Full format

 

 

URL

 

The Web service (version 1.9 rev 2126ab0) is currently available at:

/col/webservice

 

Parameters

 

There is one required parameter, which is either name or id. Give eithera name or an ID. If an ID is given, the name parameter may not be used, and vice versa.

 

The parameters format, response and start are all optional.

 

name            The string to search for. Only exact matches found the name given will be returned, unless a wildcard (*) is appended. Wildcards are allowed only at the end of the string. This offers the option to e.g. search for genus* to retrieve the genus plus all its (infra)species. The name must be at least 3 characters long, not counting the wildcard character.

id                  The record ID of the specific record to return (only for scientific names of species or infraspecific taxa)

format           format of the results returned. Valid values are format=xml, format=json and format=php; if the format parameter is omitted, the results are returned in the default XML format. If format=json is appended, the results are returned in JSON (JavaScript Object Notation) format. For format=php results are as a serialized PHP array, which can be converted back to an array in PHP using the unserialize function.

response       Type of response returned. Valid values are response=terse and response=full. if the response parameter is omitted, the results are returned in the default terse format. If format=terse then a minimum set of results are returned (this is faster and smaller, enough for name lookup), if format=full then all available information is returned.

start               The first record to return. If omitted, the results are returned from the first record (start=0). This is useful if the total number of results is larger than the maximum number of results returned by a single Web service query (currently the maximum number of results returned by a single query is 500 for terse queries and 50 for full queries).

 

Example URLs

 

/col/webservice?name=Tara+spinosa

/col/webservice?name=Apus

/col/webservice?id=4fdb38d6220462049eab9e3f285144e0

/col/webservice?name=Platalea+leucorodia

/col/webservice?id=4fdb38d6220462049eab9e3f285144e0&format=json&response=full

 

 

XML format

 

Basic format

 

The search parameters and error message returned by the Web service are included as parameters of the <results> tag.

 

<results id="" name="" total_number_of_results="" number_of_results="" start="" error_message="" version="1.9 rev 2126ab0">

     <result></result>     <!-- one <result /> for each record returned -->

</results>

 

Each result can be an accepted (infra)species name, an (infra)species synonym, a common name for an (infra)species, or a higher taxon.

 

 

Accepted (infra)species name

 

Terse response

<id></id>

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<url></url>

<is_extinct></is_extinct>     <!-- true/false -->

<online_resource></online_resource>

<source_database></source_database>

<source_database_url></source_database_url>

 

Full response

<id></id>

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<genus></genus>

<species></species>

<infraspecies_marker></infraspecies_marker>    

<infraspecies></infraspecies>

<author></author>

<additional_comments></additional_comments>

<distribution></distribution>

<url></url>

<is_extinct></is_extinct>     <!-- true/false -->

<source_database></source_database>

<source_database_url></source_database_url>

<record_scrutiny_date></record_scrutiny_date>

<online_resource></online_resource>

<references>

     <reference>     <!-- one <reference /> for each reference -->

         <author></author>

         <year></year>

         <title></title>

         <source></source>

     </reference>

</references>

<classification>

     <taxon>     <!-- one <taxon /> for each higher taxon -->

         <name></name>

         <rank></rank>

         <name_html></name_html>

         <url></url>

     </taxon>

</classification>

<child_taxa>     <!-- only for species -->

     <taxon>     <!-- one <taxon /> for each child taxon -->

         <id></id>

         <name></name>

         <name_html></name_html>

         <genus></genus>

         <species></species>

         <infraspecies_marker></infraspecies_marker>

         <infraspecies></infraspecies>

         <author></author>

         <url></url>

        <is_extinct></is_extinct>     <!-- true/false -->

     </taxon>

</child_taxa>

<synonyms>

     <synonym>     <!-- one <synonym /> for each taxon -->

         <id></id>

         <name></name>

         <rank></rank>

         <name_html></name_html>

         <name_status></name_status>

         <genus></genus>

         <species></species>

         <infraspecies_marker></infraspecies_marker>

         <infraspecies></infraspecies>

         <additional_data></additional_data>

         <url></url>

         <online_resource></online_resource>

         <source_database></source_database>

         <source_database_url></source_database_url>

         <record_scrutiny_date></record_scrutiny_date>

         <references>

             <reference>     <!-- one <reference /> for each reference -->

                 <author></author>

                 <year></year>

                 <title></title>

                 <source></source>

             </reference>

         </references>

     </synonym>

</synonyms>

<common_names>

     <common_name>     <!-- one <common_name /> for each name -->

         <name></name>

         <country></country>

         <language></language>

         <references>

             <reference>     <!-- one <reference /> for each reference -->

                 <author></author>

                 <year></year>

                 <title></title>

                 <source></source>

             </reference>

         </references>

     </common_name>

</common_names>

 

(Infra)species synonym

 

Terse response

<id></id>

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<url></url>

<online_resource></online_resource>

<source_database></source_database>

<source_database_url></source_database_url>

<accepted name>     <!-- duplicates the terse response for an accepted name -->

     <id></id>

     <name></name>

     <rank></rank>

     <name_status></name_status>

     <name_html></name_html>

     <url></url>

     <is_extinct></is_extinct>     <!-- true/false -->

     <online_resource></online_resource>

     <source_database></source_database>

     <source_database_url></source_database_url>

</accepted name>

 

Full response

<id></id>

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<genus></genus>

<species></species>

<infraspecies_marker></infraspecies_marker>

<infraspecies></infraspecies>

<author></author>

<additional_comments></additional_comments>

<distribution></distribution>

<url></url>

<source_database></source_database>

<source_database_url></source_database_url>

<record_scrutiny_date></record_scrutiny_date>

<online_resource></online_resource>

<references>

     <reference>     <!-- one <reference /> for each reference -->

         <author></author>

         <year></year>

         <title></title>

         <source></source>

     </reference>

</references>

<accepted_name>     <!-- duplicates the full response for an accepted name -->

     <id></id>

     <name></name>

     <rank></rank>

     <name_status></name_status>

     <name_html></name_html>

     <genus></genus>

     <species></species>

     <infraspecies_marker></infraspecies_marker>

     <infraspecies></infraspecies>

     <author></author>

     <additional_comments></additional_comments>

     <distribution></distribution>

     <url></url>

     <is_extinct></is_extinct>     <!-- true/false -->

     <online_resource></online_resource>

     <source_database></source_database>

     <source_database_url></source_database_url>

     <references>

         <reference>     <!-- one <reference /> for each reference -->

             <author></author>

             <year></year>

             <title></title>

             <source></source>

         </reference>

     </references>

     <classification>

         <taxon>     <!-- one <taxon /> for each higher taxon -->

             <name></name>

             <rank></rank>

             <name_html></name_html>

             <url></url>

             </taxon>

     </classification>

     <child_taxa>

         <taxon>     <!-- one <taxon /> for each child taxon -->

             <id></id>

             <name></name>

             <name_html></name_html>

             <genus></genus>

             <species></species>

             <infraspecies_marker></infraspecies_marker>

             <infraspecies></infraspecies>

             <author></author>

             <url></url>

             <is_extinct></is_extinct>     <!-- true/false -->

         </taxon>

     </child_taxa>

     <synonyms>

         <synonym>     <!-- one <synonym /> for each taxon -->

             <id></id>

             <name></name>

             <rank></rank>

             <name_html></name_html>

             <name_status></name_status>

             <genus></genus>

             <species></species>

             <infraspecies_marker></infraspecies_marker>

             <infraspecies></infraspecies>

             <additional_data></additional_data>

             <url></url>

             <online_resource></online_resource>

             <source_database></source_database>

             <source_database_url></source_database_url>

             <record_scrutiny_date></record_scrutiny_date>

             <references>

                 <reference>     <!-- one <reference /> for each reference -->

                     <author></author>

                     <year></year>

                     <title></title>

                     <source></source>

                 </reference>

             </references>

         </synonym>

     </synonyms>

     <common_names>

         <common_name>     <!-- one <common_name /> for each name -->

            <name></name>

            <country></country>

            <language></language>

            <references>

                <reference>     <!-- one <reference /> for each reference -->

                    <author></author>

                    <year></year>

                    <title></title>

                    <source></source>

                </reference>

            </references>

         </common_name>

     </common_names>

</accepted name>

 

 

Common name for (infra)species

 

Terse response

<name></name>

<name_status></name_status>

<language></language>

<country></country>

<url></url>

<source_database></source_database>

<source_database_url></source_database_url>

<accepted name>     <!-- duplicates the terse response for an accepted name -->

     <id></id>

     <name></name>

     <rank></rank>

     <name_status></name_status>

     <name_html></name_html>

     <url></url>

     <is_extinct></is_extinct>     <!-- true/false -->

     <online_resource></online_resource>

     <source_database></source_database>

     <source_database_url></source_database_url>

</accepted name>

 

Full response

<name></name>

<name_status></name_status>

<language></language>

<country></country>

<url></url>

<source_database></source_database>

<source_database_url></source_database_url>

<references>

     <reference>     <!-- one <reference /> for each reference -->

         <author></author>

         <year></year>

         <title></title>

         <source></source>

     </reference>

</references>

<accepted_name>     <!-- duplicates the full response for an accepted name -->

     <id></id>

     <name></name>

     <rank></rank>

     <name_status></name_status>

     <name_html></name_html>

     <genus></genus>

     <species></species>

     <infraspecies_marker></infraspecies_marker>

     <infraspecies></infraspecies>

     <author></author>

     <additional_comments></additional_comments>

     <distribution></distribution>

     <url></url>

     <is_extinct></is_extinct>     <!-- true/false -->

     <online_resource></online_resource>

     <source_database></source_database>

     <source_database_url></source_database_url>

     <references>

         <reference>     <!-- one <reference /> for each reference -->

             <author></author>

             <year></year>

             <title></title>

             <source></source>

         </reference>

     </references>

     <classification>

         <taxon>     <!-- one <taxon /> for higher taxon -->

             <name></name>

             <rank></rank>

             <name_html></name_html>

             <url></url>

         </taxon>

     </classification>

     <child_taxa>

         <taxon>     <!-- one <taxon /> for each child taxon -->

             <id></id>

             <name></name>

             <name_html></name_html>

             <genus></genus>

             <species></species>

             <infraspecies_marker></infraspecies_marker>

             <infraspecies></infraspecies>

             <author></author>

             <url></url>

         </taxon>

     </child_taxa>

     <synonyms>

         <synonym>     <!-- one <synonym /> for each taxon -->

             <id></id>

             <name></name>

             <rank></rank>

             <name_html></name_html>

             <name_status></name_status>

             <genus></genus>

             <species></species>

             <infraspecies_marker></infraspecies_marker>

             <infraspecies></infraspecies>

             <additional_data></additional_data>

             <url></url>

             <online_resource></online_resource>

             <source_database></source_database>

             <source_database_url></source_database_url>

             <record_scrutiny_date></record_scrutiny_date>

             <references>

                 <reference>     <!-- one <reference /> for each reference -->

                     <author></author>

                     <year></year>

                     <title></title>

                     <source></source>

                 </reference>

             </references>

         </synonym>

     </synonyms>

     <common_names>

         <common_name>     <!-- one <common_name /> for each name -->

             <name></name>

             <country></country>

             <language></language>

             <references>

                 <reference>     <!-- one <reference /> for each reference -->

                     <author></author>

                     <year></year>

                     <title></title>

                     <source></source>

                 </reference>

             </references>

         </common_name>

     </common_names>

</accepted name>

 

 

Higher taxa

 

Terse response

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<url></url>

<is_extinct></is_extinct>     <!-- true/false -->

 

Full response

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<url></url>

<is_extinct></is_extinct>     <!-- true/false -->

<classification>

     <taxon>     <!-- one <taxon /> for each higher taxon -->

         <name></name>

         <rank></rank>

         <name_html></name_html>

         <url></url>

     </taxon>

</classification>

<child_taxa>

     <taxon>     <!-- one <taxon /> for each child taxon -->

         <id></id>

         <name></name>

         <name_html></name_html>

         <genus></genus>

         <species></species>

         <infraspecies_marker></infraspecies_marker>

         <infraspecies></infraspecies>

         <author></author>

         <url></url>

         <is_extinct></is_extinct>     <!-- true/false -->

     </taxon>

</child_taxa>