Integrated Taxonomic Information System - Solr Web Services

spacing image

ITIS Solr Web Services

The base URL for the ITIS Solr index based web service is: https://services.itis.gov/?q=*:* where the initial query term and value would be a field in Solr and a value for it separated by a colon, such as: https://services.itis.gov/?q=tsn:182662

ITIS is currently using Apache Solr Vers. 5.4. Output from ITIS Solr is available in XML (default), CSV, JSON, JSONP and Serialized PHP. For example, add "&wt=json" to the end of the query string to get JSON output returned like this https://services.itis.gov/?q=tsn:182662&wt=json. The Apache Solr Reference Guide can be quite helpful in generating queries and using their output. The ITIS Data Model will also be helpful in elucidating the finer points of field definitions and validation rules.

We've included some ITIS Solr Web Service examples here.

Tips for Using the ITIS Solr Index

Regular Expressions. ITIS Solr supports regular expressions. For example:

Facets and Pivot Facets. ITIS Solr supports simple and complex facets. For example, to get a list of the numbers of taxa at the rank of species by kingdom use: https://services.itis.gov/?q=rank:Species&rows=0&facet=true&facet.field=kingdom If you do not set rows to 0, Solr will return a sample of full records along with the facet. You can also do complex facets called pivot facets. For example, to get a full list of all valid species of birds with their common names use: https://services.itis.gov/?q=hierarchySoFar:*$Aves$* AND rank:Species AND usage:valid&facet=true&facet.pivot=nameWInd,vernacular&facet.limit=-1&facet.mincount=1&rows=0. NOTE: Pivot facets are very computationally intensive, and therefore very slow, so please be considerate and conservative in their use.

Using JSONP. ITIS Solr supports JSONP. In addition to supporting JSON output using "wt=json" alone, ITIS Solr will return padded/wrapped JSON inside of any variable name that you choose (up to 30 characters) using "wt=json&json.wrf=whateverNameYouWant". This means that you can call data from ITIS and display it directly in your web page in javascript without having to manipulate it on the server, and without violating the cross-origin policy for javascript. Please see our examples page for examples.

Fuzzy Matching. ITIS Solr supports customizable fuzzy matching. Use a tilde along with a value between 0 and 1 after the string to be matched to indicate the level of fuzziness. For example: https://services.itis.gov/?q=nameWOInd:Liquidamber\%20styraciflua~0.4 will match Liquidambar styraciflua.

Escaping spaces and percent encoding in query strings. Because you cannot always be sure how a browser will interpret strings with spaces, it is good practice to both escape and percent encode spaces in queries for strings that have spaces. For example: https://services.itis.gov/?q=nameWOInd:Poa\%20annua.

Field Descriptions

Fields are listed in the order in which they appear in a Solr response. All are Solr strings.

Field Name RequiredDefinition and Notes Type Multi Valued Example Value
tsn Yes ITIS Taxonomic Serial Number or TSN. It is a globally unique and persistent identifier assigned to every scientific name at every rank in ITIS. It is unique for every record. It is never null. It is always a positive integer with no leading zeros. For more information about TSNs as non-intelligent unique identifiers see What is an ITIS TSN. string false 182662
multiplyLinkedSynonyms No Set to true when an invalid or not accepted name is linked to more than one valid or accepted name. Otherwise this field is absent. boolean false true
nameWIndYes Taxonomic name string with rank indicators string false Agave americana ssp. americana var. expansa
nameWOInd Yes Taxonomic name string without rank indicators. It may hold the same value as nameWInd if the name lacks rank indicators. string false Agave americana americana expansa
nameWtaxonAuthor Yes Taxonomic name string with rank indicators and taxon author. string false Agave americana ssp. americana var. expansa (Jacobi) Gentry
unit1 Yes First atomized unit of the taxonomic name string. string false Agave
unit2No Second atomized unit of the taxonomic name string. string false americana
unit3No Third atomized unit of the taxonomic name string. string false americana
unit4No Fourth atomized unit of the taxonomic name string. string false expansa
ind1No Rank Indicator in front of unit1 of the taxonomic name string. It is often used to indicate hybrid genera. string false X Amelasorbus jackii
ind2No Indicator between unit1 and unit2 of the taxonomic name string. string false Lycopodium X habereri
ind3No Indicator between unit2 and unit3 of the taxonomic name string. string false Agave americana ssp. americana
ind4No Indicator between unit3 and unit4 of the taxonomic name string. string false Agave americana ssp. americana var. expansa
usageYes Status of the taxonomic name. Acceptable values for this field in the kingdoms Plantae, Fungi and Chromista are "accepted" or "not accepted". In Archaea, Bacteria, Animalia and Protozoa acceptable field values are "valid" or "invalid" string false accepted
unacceptReason Yes if usage = 'no accepted' or 'invalid' Unacceptability reason for an invalid or not accepted name. For more information about unacceptability reasons see ITIS Data Submittal Guidelines. string false junior synonym
credibilityRatingYes Level of quality review of the taxonomic name. For more information about ITIS data quality indicators see ITIS Data Submittal Guidelines. string false TWG standards met
completenessRating Yes if rankID <= 180 Indication of the completeness of taxonomic coverage. Acceptable values are: "unknown","partial", and "complete". For more information about ITIS data quality indicators see ITIS Data Submittal Guidelines. string false complete
currencyRatingYes if rankID <= 180 A 4-digit year reflecting the currency of the treatment in ITIS, or a value of “unknown” when currency hasn’t been specified. For more information about ITIS data quality indicators see ITIS Data Submittal Guidelines. string false 2016
taxonAuthorNo Authorship string for the taxon represented in the record in the customary format for the taxonomic group string false Lam.
kingdom Yes Highest level of the taxonomic hierarchy (Animalia, Archaea, Bacteria, Chromista, Fungi, Plantae or Protozoa) string false Archaea
rank Yes Taxonomic rank of the name in this usage. For more information about ITIS ranks see ITIS Data Submittal Guidelines. string false species
hierarchySoFarYes The hierarchical name path of the scientific name represented by a TSN with a usage of valid/accepted, or the hierarchical name path or paths of the valid/accepted scientific name linked in synonymy to a TSN with a usage of invalid/not accepted TSN. Begins with valid/accepted TSN, then a colon, then a dollar character delimited name hierarchy from kingdom down to the rank including that name. string true 41107:$Plantae$Viridiplantae$Streptophyta $Embryophyta$Tracheophyta$Spermatophytina $Magnoliopsida$Lilianae$Poales $Poaceae$Poa$Poa annua$
hierarchyTSNYes The hierarchical TSN path of the scientific name represented by a TSN with a usage of valid/accepted, or the hierarchical TSN path or paths of the valid/accepted scientific name linked in synonymy to a TSN with a usage of invalid/not accepted TSN. It consists of a dollar character delimited TSN hierarchy from kingdom down to the rank including the TSN with a usage of valid/accepted. string true $202422$954898$846494$954900$846496$846504 $18063$846542$846620$40351$41074$41107$
publicationNo Publication reference linked to the scientific name, or scientific and vernacular names. It consists of a dollar character delimited string with the ITIS reference type, publication ID, title, author(s), and other fields describing the publication and ending in the create and update date. string true $PUB$6355$American Ornithologists' Union$Thirty-third Supplement to the American Ornithologists' Union Check-list of North American Birds$The Auk, vol. 93, no. 4$1976-10-01 00:00:00$1976-10-29 00:00:00$$$$$875-879$$2015-10-28 00:00:00$
comment No Comment about the scientific name. It consists of a dollar character delimited string with the ITIS comment ID, commentator, comment text, create date, and update date string true $66484$WoRMS - World List of Holothuroidea$LSID urn:lsid:marinespecies.org:taxname:529884 associated with the scientific name Actinocucumis longipedes Clark, 1938 acquired on 15 October, 2015$2018-07-27 13:00:26$2018-07-27 00:00:00$
expertNo Expert reference linked to the scientific name, or scientific and vernacular names. It consists of a dollar character delimited string with the ITIS reference type, expert ID, expert name, expert comment, create date, and update date. string true $EXP$203$Mark Mort $Associate Professor, Department of Ecology and Evolutionary Biology, The University of Kansas, 1200 Sunnyside Avenue, Lawrence, Kansas, USA 66045 $2012-05-31 00:00:00$
otherSourceNo Other reference linked to the scientific name, or scientific or vernacular names. It consists of a dollar character delimited string with the ITIS reference type, source ID, source type, source name, version, acquisition date, source comment, create date, and update date. string true $SRC$1119$website$Zoonomen - Zoological Nomenclature Resource, 2015.02.01$01-Feb-15$2015-01-02 00:00:00$'Zoonomen Nomenclatural data' maintained by Alan P. Peterson at http://www.zoonomen.net$2015-10-28 00:00:00$
vernacularNo Common name associated with the scientific name. It consists of a dollar character delimited string of the vernacular name, language, approved indicator, vernacular ID, and update date. string true $goldmoss stonecrop$English$N$146430$2012-05-31 00:00:00$
acceptedTSN Yes for usage = invalid or not accepted Taxonomic Serial Number of the accepted or valid name or names for a TSN with a usage of invalid or not accepted. string true 41107
synonyms Yes for usage = invalid or not accepted The valid or accepted name or names linked to the invalid or not accepted name. It consists of the Taxonomic Serial Number for the accepted or valid name, then a colon, then a dollar character delimited list of all synonyms linked to the valid or accepted name. string true 41107:$Poa annua aquatica$Poa annua reptans$Aira pumila$Catabrosa pumila$Ochlopoa annua$Poa aestivalis$Poa algida$Poa annua annua$Poa annua eriolepis$Poa annua rigidiuscula$Poa annua reptans$
rankIDYes Series number indicating relative physical placement of the taxonomic rank in a table. For example, both Phylum and Division have a rankID of 30 integer false 220
parentTSNYes for usage = valid or accepted Taxonomic Serial Number of the accepted or valid direct parent taxon string false 23453
hierarchySoFarWRanksYes The hierarchical name path of the scientific name represented by a TSN with a usage of valid/accepted, or the hierarchical name path or paths of the valid/accepted scientific name linked in synonymy to a TSN with a usage of invalid/not accepted TSN. Begins with valid/accepted TSN, then a colon, then a dollar character delimited 'rank:name' hierarchy from kingdom down to the rank including that name string true 41107:$Kingdom:Plantae$Subkingdom:Viridiplantae $Infrakingdom:Streptophyta$Superdivision:Embryophyta $Division:Tracheophyta$Subdivision:Spermatophytina $Class:Magnoliopsida$Superorder:Lilianae $Order:Poales$Family:Poaceae$Genus:Poa $Species:Poa annua$
synonymTSNs Yes for usage = invalid or not accepted The valid or accepted name or names linked to the invalid or not accepted name. It consists of the TSN for the accepted or valid name, then a colon, then a dollar character delimited list of all synonym TSNs linked to the valid or accepted name. string true 41107:$538978$538979$785854$787993 $791574$793946$793954$802116 $802117$802119$803667$
createDate Yes The date and time upon which the TSN record was created. string false 1996-06-13 14:51:08
updateDate Yes The date and time upon which the TSN record was last updated. string false 2016-02-15 00:00:00
geographicDivisionNo Geographic value or values associated with the scientific name, and the geographic update date. For more information about ITIS geographic divisions see ITIS Data Submittal Guidelines. string true $North America$1996-11-05 00:00:00$
jurisdictionNo Geographical jurisdiction value or values associated with the scientific name, and the jurisdiction update date. For more information about ITIS jurisdiction values see ITIS Data Submittal Guidelines. string true $Continental US$Introduced$2000-03-15 00:00:00$
hierarchicalSortYes for usage = valid or accepted A hyphen-delimited name hierarchy from kingdom down to the target valid or accepted name, with names in the hierarchy prefixed by a 4 digit high-to-low rank identifier computed as 10,000 - rank_id string false 9990Bacteria-9980Negibacteria-9970Proteobacteria-9940Gammaproteobacteria-9900Pseudomonadales
spacing image
spacing image spacing image spacing image spacing image