Table of Contents - 2010 Annual Checklist Web Service v1.2

 

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.2) is currently available at:

http://www.catalogueoflife.org/annual-checklist/2010/webservice

 

Parameters

 

There is one required parameter, which is either name or id. Give either a 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 one or wildcards are included in the search string. An * (asterisk) character denotes a wildcard; a % (percentage) character may also be used. The name must be at least 3 characters long, not counting wildcard characters.

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 and format=php; if the format parameter is omitted, the results are returned in the default XML format. If format=php then results are returned as a PHP array in serialized string format, which can be converted back to an array in PHP using the unserialize command

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

 

http://www.catalogueoflife.org/annual-checklist/2010/webservice?name=Tara+spinosa

http://www.catalogueoflife.org/annual-checklist/2010/webservice?name=Apus

http://www.catalogueoflife.org/annual-checklist/2010/webservice?id=7264597

http://www.catalogueoflife.org/annual-checklist/2010/webservice?name=Platalea+leucorodia

http://www.catalogueoflife.org/annual-checklist/2010/webservice?id=7264597&format=php&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.2">

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

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

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

     </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>

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

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

         </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>

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

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

 

Full response

<name></name>

<rank></rank>

<name_status></name_status>

<name_html></name_html>

<url></url>

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

     </taxon>

</child_taxa>