MOL Taxonomy API Specification

Description

Searches for taxon concepts with names matching one or more search strings. Searches can include wildcard characters. Returns lists of taxon concepts that match the search strings.

Parameters

• string searchstrs: [required] A comma-separated list of name strings to search for.
• boolean wildcard: [optional, default False] Whether to enable wildcard matching.
• boolean validonly: [optional, default False] If True, only valid names are searched (e.g., junior synonyms, homonyms, etc. are excluded from the search).
• string rank: [optional] If specified, limits the search to taxon concepts of a specified taxonomic rank.
• integer taxonomyid: [optional] If specified, limits the search to taxon concepts within a particular taxonomy.
• boolean vernacular: [optional, default False] If True, returns the vernacular name in the language specified in lang.
• string lang: [optional, default 'en'] If specified, the language for the vernacular name.

Return value

An associative array of results lists, where the array keys are the user-specified search strings, and each key maps to a list of results. Each list of results provides the taxon concepts that matched a particular search term, and each element of the list is an object with the following members:

• string tcid: The taxon concept ID.
• string taxonomyid: The ID of the source taxonomy.
• string rank: The taxonomic rank of the taxon concept.
• string name: The name string for the taxon concept.
• boolean isvalidname: Whether the name is valid.
• if isvalidname is False, string synonym_of: The valid name in this taxonomy.
• string vernacular_name: The vernacular name of the species.
• string lang: The language of the vernacular name.

Examples

• Branta canadensis: http://api.mol.org/0.x/tcsearch?searchstrs=Branta%20canadensis

Description

Searches for taxon concepts with names that are similar to one or more search strings. Searches are based on approximate (“fuzzy”) string matching to account for simple misspellings or typos. Returns lists of taxon concepts that match the search criteria.

Parameters

• string searchstrs: [required] A list of name strings to search for.
• string method: [optional, default “hybrid”] Specifies the approximate string matching algorithm to use. Supported value are “qgram”, “DL” (Damerau-Levenshtein), or “hybrid” (hybrid algorithm based on qgram and D-L matching).
• boolean validonly: [optional, default False] If True, only valid names are searched (e.g., junior synonyms, homonyms, etc. are excluded from the search).
• string rank: [optional] If specified, limits the search to taxon concepts of a specified taxonomic rank.
• integer taxonomyid: [optional] If specified, limits the search to taxon concepts within a particular taxonomy.

Return value

An associative array of results lists, where the array keys are the user-specified search strings, and each key maps to a list of results. Each list of results provides the taxon concepts that approximately matched a particular search term. Each element of a results list is an object with the following members:

• string tcid: The taxon concept ID.
• string taxonomyid: The ID of the source taxonomy.
• string rank: The taxonomic rank of the taxon concept.
• string name: The name string for the taxon concept.
• boolean validname: Whether the name is valid.
• boolean ismaster: Whether the taxonomy from which the name is returned is master.

Description

Retrieves detailed information about one or more taxon concepts.

Parameters

• string tcids: [required] A comma-separated list of taxon concept IDs.
• boolean gethighertaxa: [optional, default False] If True, returns the higher taxa (that is, all ancestors) for the taxon concept.
• boolean getchildren: [optional, default False] If True, all child taxa for this taxon concept are returned.
• boolean getsynonyms: [optional, default False] If True, all known name synonyms for this taxon concept are returned.

Return value

Returns an associative array of results. The keys of the array are the user-provided taxon concept IDs, and each ID maps to an object with the following members:

• string taxonomyid: The ID of the source taxonomy.
• string name: The valid name string for the taxon concept.
• string authorstring: The citation string for the taxon concept's name. The empty string (“”) is returned if no citation information is available.
• string citationid: The ID of the reference for the taxon concept's name. The empty string (“”) is returned if no citation information is available.
• string rank: The taxonomic rank of the taxon concept.
• string parenttcid: The taxon concept ID of the taxon concept’s immediate parent.
• list highertaxa: An ordered list of all ancestors of the concept concept, with the deepest ancestor listed first and the closest listed last. Each element of the list is an object with the members tcid, taxonomyid, rank, and name. This member is only present if the parameter gethighertaxa == True.
• list children: A list of all child taxa of this taxon concept. Each element of the list is an object with the members tcid, taxonomyid, rank, and name. This member is only present if the parameter getchildren == True.
• list synonyms: A list of all known name synonyms for this taxon concept. Each element of the list is an object with the members name, citationid, and authorstring. This member is only present if the parameter getsynonyms == True.

Examples

• Branta canadensis: http://api.mol.org/0.x/tcinfo?tcids=8f402889-9c1b-410a-9483-81a226f3ba9d&gethighertaxa=true

Description

Retrieves detailed information about a taxonomy.

Parameters

• string taxonomyid: [required] The ID of the taxonomy.

Return value

An object with the following members:

• string name: The name/description of the taxonomy.
• string citationid: The ID of the full citation record for the taxonomy.
• string authorstring: A short reference for the authors of the taxonomy.
• boolean ismaster: Whether the taxonomy is a “master” taxonomy for Map of Life.
• string roottcid: The ID of the root taxon concept for the taxonomy.

Description

Retrieves detailed information about one or more citation records.

Parameters

• string citationids: [required] A comma-separated list of citations IDs.

Return value

An associative array of search results. The array keys are the user-provided citations IDs, and each ID maps to an object with the following elements:

• string fullcite: The full citation string.
• string url: The URL for the reference.
• string doi: The DOI for the reference.

Description

Retrieves a listing of the taxonomies in the database.

Parameters

none

Return value

An associative array of taxonomies:

• string name: The name of the taxonomy.
• string authorstring: A short reference for the authors of the taxonomy.
• boolean ismaster: Whether the taxonomy is a “master” taxonomy for Map of Life.
• string roottcid: The ID of the root taxon concept for the taxonomy.
• string citationstr: The full citation for the taxonomy.
• int taxonomy_id: The ID of the taxonomy.

Examples

• http://api.mol.org/0.x/taxonomies

[
            {
            ismaster: true,
            name: "MOL backbone",
            roottcid: "a025e068-12e3-11e5-94b1-37903a5f6c8a",
            authorstring: "Jetz et al. 2012",
            citationstr: "Jetz, W., J.M. McPherson, R.P. Guralnick. 2012. Integrating biodiversity distribution knowledge:
            toward a global map of life. Trends in Ecology and Evolution 27: 151-159.",
            taxonomy_id: 1
            },
            {
            ismaster: true,
            name: "Jetz birds",
            roottcid: "bdac5ba6-6efd-4549-ad01-474c154434c2",
            authorstring: "Jetz et al. 2012",
            citationstr: "Jetz, W., Thomas G.H., Joy J.B., Hartmann K., and Mooers A.O. (2012) The global diversity of birds in
            space and time. Nature 491: 444-448",
            taxonomy_id: 2
            },
            {
            ismaster: true,
            name: "Mammal Species of the World v3",
            roottcid: "93c1ee00-bb6d-4c8c-81ce-b5ea2ec290e1",
            authorstring: "Wilson and Reeder 2005",
            citationstr: "Wilson, DE & Reeder, DM (2005) Mammal Species of the World. A Taxonomic and Geographic Reference
            (3rd ed), Johns Hopkins University Press, 2,142 pp. (Available from Johns Hopkins University Press.",
            taxonomy_id: 7
            },
            ...
            ]