spacing image spacing image spacing image spacing image
The ITIS Logo The banner for the ITIS Web Service page spacing image
spacing image

ITIS Solr Web Services

The base URL for the ITIS Solr index based web service is: http://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: http://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 http://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: http://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: http://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: http://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: http://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 NotesExample Value
tsn Yes ITIS Taxonomic Serial Number or TSN. It is the 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. This field is never an array (i.e. every record only ever has one TSN). A TSN once assigned, will always exist in the database. Due to historical reasons early in the development of the data, TSNs are not guaranteed sequential though. There is no other information contained in the TSN and order of assignment, date, and taxonomic group cannot be reliably determined from it.182662
nameWIndYes Taxonomic name string with rank indicatorsAgave americana ssp. americana var. expansa
nameWOInd YesTaxonomic name string without rank indicators. It may hold the same value as nameWInd if the name has no indicators.Agave americana americana expansa
unit1 Yes First atomized unit of the taxonomic name stringAgave
unit2No Second atomized unit of the taxonomic name stringamericana
unit3No Third atomized unit of the taxonomic name stringamericana
unit4No Fourth atomized unit of the taxonomic name stringexpansa
ind1No Indicator in front of unit1 of the taxonomic name string. It is often used to indicate hybrid genera as in "X Amelasorbus"X
ind2No Indicator between unit1 and unit2 of the taxonomic name string. As in "Lycopodium X habereri"X
ind3No Indicator between unit2 and unit3 of the taxonomic name string. As in "Agave americana ssp. americana"ssp.
ind4No Indicator between unit3 and unit4 of the taxonomic name string. As in "Agave americana ssp. americana var. expansa"var.
usageYes Status of the taxonomic name. Acceptable values in the kingdoms Plantae, Fungi & Chromista are "accepted" or "not accepted". In Archaea, Bacteria, Animalia and Protozoa they are "valid" or "invalid".accepted
unacceptReasonYes Unacceptability reason for an invalid or not accepted name. There is a controlled vocabulary that differs by kingdom.junior synonym
taxonAuthorNo Authorship string for the taxon represented in the record in the customary format for the taxonomic groupLam.
credibilityRatingYes Designated level of review of the taxonomic nameTWG standards met
completenessRating Yes if rankID <= 180 Indication of completeness. Acceptable values are: "unknown", "partial", and "complete"complete
currencyRatingYes if rankID <= 180A 4 digit year reflecting the currency of the treatment in ITIS2016
kingdom Yes Highest level of the taxonomic hierarchy (Animalia, Archaea, Bacteria, Chromista, Fungi Plantae or Protozoa)Archaea
parentTSNNo Taxonomic Serial Number of the accepted or valid direct parent taxon23453
rankIDYes Series number indicating relative physical placement of the rank in a table. For example, both Phylum and Division have a rankID of 30220
rank Yes Taxonomic rank of the name in this usagespecies
hierarchySoFarYesA computed field available only from the Solr web service. It consists of the TSN for the accepted or valid name for the taxon, then a colon, then a dollar sign delimited verbatim hierarchy for that valid or accepted name from kingdom down to the rank including that name. This field will be an array of two or more strings in the case of synonyms (such as pro parte synonyms) that link to more than one accepted or valid name.41107:$Plantae$Viridiplantae$Streptophyta $Embryophyta$Tracheophyta$Spermatophytina $Magnoliopsida$Lilianae$Poales $Poaceae$Poa$Poa annua$
hierarchySoFarWRanksYesA computed field available only from the Solr web service. It consists of the TSN for the accepted or valid name for the taxon, then a colon, then a dollar sign delimited verbatim hierarchy with ranks for that valid or accepted name from kingdom down to the rank including that name. This field will be an array of two or more strings in the case of synonyms (such as pro parte synonyms) that link to more than one accepted or valid name.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$
hierarchyTSNYesA computed field available only from the Solr web service. It is a dollar sign delimited hierarchy of TSNs for the valid or accepted name of the taxon from kingdom down to that name. This field will be an array of two or more strings in the case of synonyms (such as pro parte synonyms) that link to more than one accepted or valid name.$202422$954898$846494$954900$846496$846504 $18063$846542$846620$40351$41074$41107$
synonyms NoA computed field available only from the Solr web service. It consists of the TSN for the accepted or valid name for the taxon, then a colon, then a dollar sign delimited list of all synonyms linked to the valid or accepted name of the taxon. The synonymTNSs field will have the TSNs for same taxa in the same order. This field will be an array of two or more strings in the case of synonyms (such as pro parte synonyms) that link to more than one accepted or valid name. 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$
synonymTSNs No A computed field available only from the Solr web service. It consists of the TSN for the accepted or valid name for the taxon, then a colon, then a dollar sign delimited list of all synonym TSNs linked to the valid or accepted name of the taxon. The synonyms field will have the verbatim names for same taxa in the same order. This field will be an array of two or more strings in the case of synonyms (such as pro parte synonyms) that link to more than one accepted or valid name. 41107:$538978$538979$785854$787993 $791574$793946$793954$802116 $802117$802119$803667$
expertNo Expert or data steward for this record. It consists of a dollar sign delimited string with the ITIS expert type, number and name as well as other fields describing the expert. If there is more than one expert associated with the record then the field will contain an array of these strings. $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$
publicationNo Citation of a publication relating to the record. It consists of a dollar sign delimited string with the ITIS publication type, number and title as well as other fields describing the citation. If there is more than one publication associated with the record then the field will contain an array of these strings. $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$
otherSourceNoCitation of a source other than a publication relating to the record. It consists of a dollar sign delimited string with the ITIS source type, number and other fields describing the citation. If there is more than one citation associated with the record then the field will contain an array of these strings. $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$
acceptedTSN Yes for usage = invalid or not accepted TSN of the accepted or valid name for the taxon if the taxon usage is valid or not accepted. See the description for tsn above. This field will be an array of two or more strings in the rare case of synonyms (such as pro parte synonyms) that link to more than one accepted or valid name. 41107
vernacularNo Dollar sign delimited string of the vernacular name often along with the language and other information. If there is more than one vernacular name, it will be an array for these strings.$goldmoss stonecrop$English$N$146430$2012-05-31 00:00:00$
jurisdictionNo Dollar sign delimited string of an association between one of several jurisdictions in the US, Canada and Mexico and an assertion of status. If there is more than one jurisdictional assertion, it will be an array for these strings.$Continental US$Introduced$2000-03-15 00:00:00$
geographicDivisionNo ITIS specific global geographic division. These designations are not exhaustive or complete. Lack of an assertion that the taxon is in a division does not equal an assertion that it is not there. Acceptable values are: North America, Middle America, Caribbean, South America, Europe and Northern Asia (excluding China), Africa, Southern Asia, Australia, Oceania, Antarctica/Southern Ocean, Eastern Atlantic Ocean, Indo-West Pacific and East Pacific. If there is more than one geographic division assertion, it will be an array for these strings.$North America$1996-11-05 00:00:00$
createDate The record creation date1996-06-13 14:51:08
updateDate The last record update date2016-02-15 00:00:00
hierarchicalSortyes, for valid or accepted names only A computed field available only from the Solr web service. It consists of a hyphen delimited verbatim 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. This field is always a single string, and never an array.9990Bacteria-9980Negibacteria-9970Proteobacteria-9940Gammaproteobacteria-9900Pseudomonadales
spacing image
spacing image spacing image spacing image spacing image