- HELP CONTENTS 1. SUMMARY 2. GET INDIVIDUAL RECORDS - get 3. SEARCH FOR RECORDS - list 4. COUNT RECORDS - count 5. GET HELP - help 6. RESPONSE STRUCTURE - schema 7. BROWSER FORMATTING - stylesheet 1. SUMMARY The taxon web service provides access to records of taxon concepts from data resources in the GBIF network. This service can be used to find the species and higher taxa for which GBIF has data. The records returned represent the use of a scientific name in the context of one of the data resources included in the network, or the position assigned to the scientific name within a synthetic taxonomic hierarchy maintained by the GBIF data portal. This taxonomic hierarchy is built from the taxonomic information provided by the individual resources and includes every a concept record for every name known to the portal. The placement of any concept within the hierarchy depends on an automated process and may not represent the best current taxonomic opinion. Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/<action>?<parameter_list> where: action is one of: get - get a single taxon concept record list - search for taxon concept records matching a range of filters count - count taxon concept records matching a range of filters help - displays this help text schema - returns the response schema document stylesheet - returns a stylesheet for rendering response documents as HTML parameter_list is a set of key-value pair options controlling or modifying how the service handles the action request. See subsections below for information on the parameters supported in parameter list for each action. 2. GET INDIVIDUAL RECORDS - get Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/get/<key>?<parameter_list> or: http://crbio.cr/portalCRBio/ws/rest/taxon/get?<parameter_list> where: key is a numeric key uniquely identifying the taxon concept record within the GBIF data portal. parameter_list is a set of URL-encoded key-value pairs including any of the following keys: key - numeric key uniquely identifying the taxon concept record within the GBIF data portal (same as key above). Note that key strings of the form "c-1234" are generated by the portal to allow vernacular name records to be related to taxon concepts. These vernacular name keys can also be resolved by this service. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The get action is intended as a quick way to retrieve an taxon record for which the key is already known (e.g. from an earlier use of the list action). The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below) using the TaxonConcept element from the Taxon Concept Schema. The response may contain multiple TaxonConcept elements. One of these will be marked with the primary="true" attribute and represents the taxon identified by the request. The others will be marked with the primary="false" attribute and are included in the response as further information about the requested taxon. The primary TaxonConcept includes a set of RelationshipAssertion elements which identify the relationship between the primary taxon and these secondary taxa. These relationships should be interpreted as follows: 1. Secondary taxa from the same data resource as the primary taxon - these relationships are provided by the data resource serving the information on the primary taxon. (If the data resource is the synthetic "PORTAL" taxonomy, i.e. data resource 1, this simply means that these relationships have been included in the classification generated dynamically to manage data within the portal.) The significance of the relationship is further defined by the value of the type attribute: - "IsParentTaxonOf" indicates that the primary taxon includes the secondary taxon as a taxon of immediately subordinate rank - "IsChildTaxonOf" indicates that the primary taxon is included by the secondary taxon as a taxon of immediately subordinate rank - "HasSynonym" indicates that the primary taxon is accepted as valid and the secondary taxon names are considered to be synonyms for the primary taxon name (including partial synonyms and misapplied names) - "IsIncludedIn" indicates that the primary taxon is not accepted as valid and the secondary taxon should be used instead - "HasVernacular" indicates that the secondary taxon is a vernacular name for the primary taxon - "IsVernacularFor" indicates that the primary taxon is a vernacular name for the secondary taxon 2. Primary taxon from synthetic "PORTAL" taxonomy (i.e. data resource 1) and secondary taxon from a different resource - these relationships are managed by the portal to indicate how the synthetic classification used by the portal maps to the different taxon names used by each resource. The type attribute in these cases is always "Includes". 3. Secondary taxon from synthetic "PORTAL" taxonomy (i.e. data resource 1) and primary taxon from a different resource - these relationships are managed by the portal to indicate how taxon names used in each resource are handled by the portal. The type attribute in these cases is always "IsIncludedIn". Secondary taxa may also include TaxonRelationship elements of the type "IsChildTaxonOf" to indicate the full higher taxonomy for the primary taxon. Examples: http://crbio.cr/portalCRBio/ws/rest/taxon/get/100 - returns the taxon concept record with key 100 http://crbio.cr/portalCRBio/ws/rest/taxon/get?key=100&stylesheet= - returns the taxon concept record with key 100 with HTML formatting disabled. Likely future enhancements: 1. Support a format parameter to switch to alternate formats. 2. Include a URL to retrieve the original record from the provider. 3. SEARCH FOR RECORDS - list Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/list?<parameter_list> where: parameter_list is a set of URL-encoded key-value pairs including any of the following keys: scientificname - return only records where the scientific name matches that supplied. Including an asterisk '*' in the search string causes the service to return records for any name starting with the string preceding the asterisk. There must be at least three characters preceding the asterisk. rank - return only records where the rank matches that specified. The value should be one of the following: kingdom, phylum, class, order, family, genus, species, infraspecific. dataproviderkey - return only records which have been made available by the provider identified by the supplied numeric key. (Each provider may serve one or more resources, so this can be used to query the full set of resources from a single provider.) Values for dataproviderkey can be found through the provider web service (see http://crbio.cr/portalCRBio/ws/rest/provider) or from previous invocations of the list and get actions of this service. dataresourcekey - return only records which have been made available by the resource identified by the supplied numeric key. (Each provider may serve one or more resources.) Values for dataresourcekey can be found through the resource web service (see http://crbio.cr/portalCRBio/ws/rest/resource) or from previous invocations of the list and get actions of this service. The special value "PORTAL" can be used to retrieve just taxon concept records from the generated synthetic taxonomy maintained by the portal. resourcenetworkkey - return only records which have been made available by resources identified as belonging to the network identified by the supplied numeric key. (Each network may include several resources.) Values for resourcenetworkkey can be found through the network web service (see http://crbio.cr/portalCRBio/ws/rest/network). hostisocountrycode - return only records served by providers from the country identified by the supplied 2-letter ISO code. modifiedsince - return only records which have been indexed or modified in the GBIF data portal index on or after the supplied date (format YYYY-MM-DD, e.g. 2006-11-28). Note that these dates are based on the time at the GBIF Secretariat in Copenhagen. startindex - return the subset of the matching records that starts at the supplied (zero-based index). If this is not supplied, the response includes records starting with the first matching record (equivalent to startindex=0). This can be used in conjunction with information in the /gbifResponse/header/summary element in the response document to manage paging through large sets of records. maxresults - return at most the specified number of records. The default (and maximum supported) is 1000 records. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The list action should be used to find taxon concept records of interest from within the GBIF data portal. The response data are only sorted within an individual response. If the search matches more records than can be returned in a single response, subsequent responses may include additional blocks of data for providers and resources included in the earlier response. The data from the union of all responses may need to be sorted before use if such repetition is problematic. Note that this action does not count all records in the portal matching the supplied filters. The totalMatched attribute in the response should only be used to indicate whether further records exist. To get an accurate total count, us the count action (see "4. COUNT RECORDS - count" below). The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below). The taxon concept records are found in the response document at the path /gbifResponse/dataProviders/dataProvider/dataResources/dataResource/taxonConcepts/taxonConcept The /gbifResponse/header/summary element may contain up to four attributes: start - the index of the first matching record returned. totalMatched - the minimum number of matching records contained in the portal. This should only be used to indicate that there are more records still unreturned. Use the count action for an accurate count. This value is only reliable if the startindex on the request was lower than the number of records actually matching. totalReturned - the number of records actually returned in this response. next - the index of the next matching record (if totalMatched is greater than totalReturned). This can be used as the value for startindex on the next list request to retrieve another page of matching records. When there are more matching records to retrieve (i.e. the next attribute is set), the document includes a URL which can be used to retrieve the next page. This is returned in the /gbifResponse/header/nextRequestUrl element. Examples: http://crbio.cr/portalCRBio/ws/rest/taxon/list?scientificname=Puma+concolor - returns all TaxonConcept records for Puma concolor (i.e. one for every data resource including Puma concolor) http://crbio.cr/portalCRBio/ws/rest/taxon/list?scientificname=Puma*&dataresourcekey=12 - returns TaxonConcept records for names starting "Puma" and included in the data resource with the key value 12 in the GBIF portal Likely future enhancements: 1. Support search by thematic network (e.g. MaNIS, OBIS, WFCC). 2. Support multiple values for a single parameter (to be OR'ed together). 3. Include URLs to perform the equivalent searches against each matching provider. 4. Support searches spanning 180 degrees east/west. 4. COUNT RECORDS - count Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/count?<parameter_list> where: parameter_list is a set of URL-encoded key-value pairs including any of the following keys: scientificname - count only records where the scientific name matches that supplied. Including an asterisk '*' in the search string causes the service to count records for any name starting with the string preceding the asterisk. There must be at least three characters preceding the asterisk. rank - count only records where the rank matches that specified. The value should be one of the following: kingdom, phylum, class, order, family, genus, species, infraspecific. dataproviderkey - count only records which have been made available by the provider identified by the supplied numeric key. (Each provider may serve one or more resources, so this can be used to query the full set of resources from a single provider.) Values for dataproviderkey can be found through the provider web service (see http://crbio.cr/portalCRBio/ws/rest/provider) or from previous invocations of the list and get actions of this service. dataresourcekey - count only records which have been made available by the resource identified by the supplied numeric key. (Each provider may serve one or more resources.) Values for dataresourcekey can be found through the resource web service (see http://crbio.cr/portalCRBio/ws/rest/resource) or from previous invocations of the list and get actions of this service. The special value "PORTAL" can be used to retrieve just taxon concept records from the generated synthetic taxonomy maintained by the portal. resourcenetworkkey - count only records which have been made available by resources identified as belonging to the network identified by the supplied numeric key. (Each network may include several resources.) Values for resourcenetworkkey can be found through the network web service (see http://crbio.cr/portalCRBio/ws/rest/network). hostisocountrycode - count only records served by providers from the country identified by the supplied 2-letter ISO code. modifiedsince - count only records which have been indexed or modified in the GBIF data portal index on or after the supplied date (format YYYY-MM-DD, e.g. 2006-11-28). Note that these dates are based on the time at the GBIF Secretariat in Copenhagen. stylesheet - sets the URL of the stylesheet to be associated with the response document. This overrides the default provided by the data portal. Supplying an empty string as the value for this parameter disables the setting of a stylesheet by the data portal. The value of this parameter is used in an xml-stylesheet processing instruction at the start of the response document. See "7. BROWSER FORMATTING - stylesheet" below. The count action can be used to get an accurate count of taxon concept records of interest from within the GBIF data portal prior to retrieving these records using the list action. This may assist with deciding whether to refine the search more closely before retrieving records. The response is formatted according to the XML schema returned by the schema action (see "6. RESPONSE STRUCTURE - schema" below). The count is returned in the totalMatched attribute of the /gbifResponse/header/summary element in the response document. Examples: http://crbio.cr/portalCRBio/ws/rest/taxon/count?scientificname=Puma+concolor - counts taxon concept records for the name Puma concolor http://crbio.cr/portalCRBio/ws/rest/taxon/count?rank=family&dataresourcekey=12 - counts family-level taxa in resource 12 Likely future enhancements: 1. Support multiple values for a single parameter (to be OR'ed together). 5. GET HELP - help Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/help or: http://crbio.cr/portalCRBio/ws/rest/taxon The help action returns this help documentation. 6. RESPONSE STRUCTURE - schema Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/schema The schema action returns the XML schema document used for the responses to the get, list, count and help actions. The response document includes a header which includes intellectual property statements, information on the request issued and a summary of the response contents. The body of the document for the response to a list or get action request is a dataProviders element, containing one or more dataProvider elements, each with metadata on a particular provider and a dataResources element, containing one or more dataResource elements, each with metadata on a particular resource and an taxonRecords element containing a set of taxonRecord elements. The response data are only sorted within an individual response. If the search matches more records than can be returned in a single response, subsequent responses may include additional blocks of data for providers and resources included in the earlier response. The data from the union of all responses may need to be sorted before use if such repetition is problematic. 7. BROWSER FORMATTING - stylesheet Syntax: http://crbio.cr/portalCRBio/ws/rest/taxon/stylesheet The stylesheet action returns a simple XSLT document which can be used to display the responses to the get, list, count and help actions in a readable form in a web browser. An xml-stylesheet processing instruction referenceing this stylesheet is included by default in the responses to these actions. - help - This document contains data shared through the GBIF Network - see http://data.gbif.org/ for more information. All usage of these data must be in accordance with the GBIF Data Use Agreement - see http://www.gbif.org/DataProviders/Agreements/DUA - http://www.crbio.cr/portalCRBio/ws/rest/taxon/stylesheet