-
Notifications
You must be signed in to change notification settings - Fork 7
TNRS API v3
Methods for resolving taxonomic names to Open Tree of Life Taxonomy identifiers (ott ids), including finding synonyms / honomyms and performing fuzzy string matching (for matching misspelled names). These methods can use information about taxonomic context to limit search scope and thereby improve performance (e.g. 'search only plants').
The base URL for all services:
https://api.opentreeoflife.org/v3/
This page is part of the Open Tree of Life Web APIs.
| URL | Verb | Summary |
|---|---|---|
/tnrs/match_names |
POST | Returns a list of potential matches to known taxonomic names. |
/tnrs/autocomplete_name |
POST | Given a partial (from the beginning) to complete taxonomic name, return a list of potential matches. |
/tnrs/contexts |
POST | Return a list of pre-defined taxonomic contexts (i.e. clades), which can be used to limit the scope of tnrs queries. |
/tnrs/infer_context |
POST | Return a taxonomic context given a list of taxonomic names. |
Returns a list of potential matches to known taxonomic names.
POST /tnrs/match_names
Accepts one or more taxonomic names and returns information about potential matches for these names to known taxa in OTT. Currently limited to 10,000 names for non-fuzzy matching and 250 names for fuzzy matching. This service uses taxonomic contexts to disambiguate homonyms and misspelled names; a context may be specified using the context_name parameter. If no context is specified, then the context will be inferred: the shallowest taxonomic context that contains all unambiguous names in the input. A name is considered unambiguous if it is not a synonym and has only one exact match to any taxon name in the entire taxonomy.
Taxonomic contexts are uncontested higher taxa that have been selected to allow limits to be applied to the scope of TNRS searches (e.g. 'match names only within flowering plants'). Once a context has been identified (either user-specified or inferred), all taxon name matches will performed only against taxa within that context. Using contexts increases both speed and accuracy of the service, so we highly recommending setting a context. For a list of available taxonomic contexts, see the contexts service.
Input parameters
Parameters with bold type definitions are required.
-
names: (list of string) An array of taxon names to be queried. Currently limited to 1000 names. -
context_name: (string) The name of the taxonomic context to be searched -
do_approximate_matching: (boolean) Whether or not to perform approximate string (a.k.a. "fuzzy") matching. Will greatly improve speed if false. Default = false. -
include_suppressed: (boolean) When false, we suppress taxa with certain flags from the TNRS service. The taxonomy documentation contains a list of the these flags.
Output parameters
-
governing_code: (string) e.g. "ICN" -
unambiguous_names: (list of string) A list of the input names that are not synonyms and have only one exact match to any taxon name in the entire taxonomy. -
unmatched_names: (list of string) A list of the input names that could not be matched. -
matched_names: (list of string) A list of the input names that were matched. -
context: (string) The context used for the search -
includes_approximate_matches: (boolean) -
includes_deprecated_taxa: (boolean) Whether or not the search included deprecated taxa. -
includes_suppressed_names: (boolean) Whether or not the search included suppressed taxa. -
taxonomy: (dict) Information about the taxonomy (same fields as taxonomy/about). -
results: (list of dict) A list of the results for each input name. Each element in the list is a dictionary with following fields:-
name: (string) The input name string being matched-
matches: (list of dict) A list of the matches for this name. Each match is a dictionary of fields that describe both the matched taxon and the match itself. -
matched_name: (string) The name matched to the input.-
search_string: (string) The input name.
-
-
score: (float) A score that represents the closeness of the match (perfect matches have score = 1.0).-
is_approximate_match: (boolean) Whether this is an approximate match -
is_synonym: (boolean) Whether match was via a synonym -
nomenclature_code: (string) The code used for this match. -
taxon: (dict) an extended-taxon-descriptor with fieldsott_id,name,rank,unique_name,tax_sourcesandis_suppressed.
-
-
-
Example command:
$ curl -X POST https://api.opentreeoflife.org/v3/tnrs/match_names \
-H "content-type:application/json" -d \
'{"names":["Aster","Symphyotrichum","Barnadesia"]}'Example result:
{
"governing_code" : "ICN",
"unambiguous_names" : [ "Barnadesia", "Aster", "Symphyotrichum" ],
"unmatched_names" : [ ],
"matched_names" : [ "Barnadesia", "Aster", "Symphyotrichum" ],
"context" : "Asteraceae",
"includes_deprecated_taxa" : false,
"includes_suppressed_names" : false,
"includes_approximate_matches" : false,
"taxonomy" : {
"weburl" : "https://tree.opentreeoflife.org/about/taxonomy-version/ott2.9",
"author" : "open tree of life project",
"name" : "ott",
"source" : "ott2.9draft12",
"version" : "2.9"
},
"results" : [ {
"name" : "Symphyotrichum",
"matches" : [ {
"is_synonym" : false,
"score" : 1.0,
"nomenclature_code" : "ICN",
"is_approximate_match" : false,
"taxon" : {
"is_suppressed" : false,
"tax_sources" : [ "ncbi:72977", "worms:416035", "gbif:3151391", "irmng:1029676" ],
"unique_name" : "Symphyotrichum",
"synonyms" : [ "Symphyotrichum" ],
"name" : "Symphyotrichum",
"flags" : [ ],
"ott_id" : 1058735,
"rank" : "genus"
},
"search_string" : "symphyotrichum",
"matched_name" : "Symphyotrichum"
} ]
}, {
"name" : "Barnadesia",
"matches" : [ {
"is_synonym" : false,
"score" : 1.0,
"nomenclature_code" : "ICN",
"is_approximate_match" : false,
"taxon" : {
"is_suppressed" : false,
"tax_sources" : [ "ncbi:4237", "gbif:3105285", "irmng:1046392" ],
"unique_name" : "Barnadesia",
"synonyms" : [ "Barnadesia", "Barnadesia Mutis" ],
"name" : "Barnadesia",
"flags" : [ ],
"ott_id" : 515698,
"rank" : "genus"
},
"search_string" : "barnadesia",
"matched_name" : "Barnadesia"
} ]
}, {
"name" : "Aster",
"matches" : [ {
"is_synonym" : false,
"score" : 1.0,
"nomenclature_code" : "ICN",
"is_approximate_match" : false,
"taxon" : {
"is_suppressed" : false,
"tax_sources" : [ "ncbi:41479", "worms:403904", "gbif:3093921", "irmng:1355106" ],
"unique_name" : "Aster",
"synonyms" : [ "Borkonstia", "Virgulaster", "Conyzanthus", "Aster", "Chlamydites", "Weberaster" ],
"name" : "Aster",
"flags" : [ ],
"ott_id" : 5507594,
"rank" : "genus"
},
"search_string" : "aster",
"matched_name" : "Aster"
} ]
} ]
}Given an input string, return a list of potential matches based on taxonomic names that begin with that string.
POST /tnrs/autocomplete_name
Important This service is optimized for autocompleting name fields on a form. If you are trying to resolve a list of taxonomic names, you should use the match_names method, which takes into account synonyms, taxonomic contexts, and string matching throughout the input string.
The autocomplete_name method assumes the input is a taxon name that may be incomplete (i.e. the beginning of a taxon name such as 'Ast', which would match 'Astelia', 'Astilbe', 'Aster', 'Asteroidea', 'Asteraceae', 'Astrantia', etc.). If the input string is an exact string match to an existing taxon name, then only the exact match will be returned, (i.e. the input 'Aster' will produce a single result 'Aster').
If name expansion identifies a valid genus name, the results will not include species names from within that genus, but if a trailing space exists in the input following a valid genus name, then species names will be returned. For example, both 'Garcin' and 'Garcinia' will match the genus name 'Garcinia' itself but will not match any species names within the genus, but 'Garcinia ' (note the trailing space) will match all the species in the genus, and 'Garcinia m' with match all species names in Garcinia with a specific epithet that starts with 'm'.
Input parameters
Parameters with bold type definitions are required.
-
name: (string) A string containing a single name (or partial name prefix) to be queried. -
context_name: (string) The name of the taxonomic context to be searched -
include_suppressed: (boolean) Whether or not suppressed taxa should be included in the results. Defaults to false (suppressed taxa not included).
Output parameters The method returns a list of matches. Each match is a dict containing the following parameters:
-
ott_id: (integer) The OTT identifier for the taxon -
unique_name: (string) The unique name of the taxon -
is_suppressed: (boolean) Whether the taxon is suppressed -
is_higher: (boolean) Whether the taxon is a higher taxon (vs a terminal)
Example command:
$ curl -X POST https://api.opentreeoflife.org/v3/tnrs/autocomplete_name \
-H "content-type:application/json" -d \
'{"name":"Endoxyla","context_name":"All life"}'Example result:
[ {
"is_suppressed" : false,
"unique_name" : "Endoxyla (genus in Holozoa)",
"ott_id" : 1098009,
"is_higher" : true
}, {
"is_suppressed" : false,
"unique_name" : "Endoxyla (genus in Nucletmycea)",
"ott_id" : 307183,
"is_higher" : true
} ]Return a list of pre-defined taxonomic contexts (i.e. clades), which can be used to limit the scope of tnrs queries.
POST /tnrs/contexts
Taxonomic contexts are available to limit the scope of TNRS searches. These contexts correspond to uncontested higher taxa such as 'Animals' or 'Land plants'. This service returns a dictionary containing all available taxonomic context names, which may be used as input (via the context_name parameter) to limit the search scope of other services including match_names and autocomplete_name.
Input parameters
None
Output parameters Returns a dictionary of concepts keyed by a few higher-level categories. Each value in the dictionary is a list of valid taxonomic contexts.
Example command:
$ curl -X POST https://api.opentreeoflife.org/v3/tnrs/contextsExample result:
{
"ANIMALS" : [ "Animals", "Birds", "Tetrapods", "Mammals", "Amphibians", "Vertebrates", "Arthropods", "Molluscs", "Nematodes", "Platyhelminthes", "Annelids", "Cnidarians", "Arachnides", "Insects" ],
"MICROBES" : [ "Bacteria", "SAR group", "Archaea", "Excavata", "Amoebae", "Centrohelida", "Haptophyta", "Apusozoa", "Diatoms", "Ciliates", "Forams" ],
"FUNGI" : [ "Fungi", "Basidiomycetes", "Ascomycetes" ],
"PLANTS" : [ "Land plants", "Hornworts", "Mosses", "Liverworts", "Vascular plants", "Club mosses", "Ferns", "Seed plants", "Flowering plants", "Monocots", "Eudicots", "Rosids", "Asterids", "Asterales", "Asteraceae", "Aster", "Symphyotrichum", "Campanulaceae", "Lobelia" ],
"LIFE" : [ "All life" ]
}Return a taxonomic context given a list of taxonomic names.
POST /tnrs/infer_context
Find the least inclusive taxonomic context that includes all the unambiguous names in the input set. Unambiguous names are names with exact matches to non-homonym taxa. Ambiguous names (those without exact matches to non-homonym taxa) are indicated in results.
Input parameters
Parameters with bold type definitions are required.
-
names: (list of string) An array of taxon names to be queried.
Output parameters
-
context_name: (string) The name of the context -
context_ott_id: (integer) The OTT id of the context -
ambiguous_names: (list of string) A list of names without exact matches that were not used in inferring the context. You can use the match_name method to disambiguate names.
Example command:
$ curl -X POST https://api.opentreeoflife.org/v3/tnrs/infer_context \
-H "content-type:application/json" -d \
'{"names":["Pan","Homo","Mus","Bufo","Drosophila"]}'Example result:
{
"context_name" : "Animals",
"context_ott_id" : 691846,
"ambiguous_names" : [ "bufo", "mus" ]
}