ITIS - Solr Web Services (original) (raw)

spacing image

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 thishttps://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 Required Definition 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
nameWInd Yes 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
unit2 No Second atomized unit of the taxonomic name string. string false americana
unit3 No Third atomized unit of the taxonomic name string. string false americana
unit4 No Fourth atomized unit of the taxonomic name string. string false expansa
ind1 No Rank Indicator in front of unit1 of the taxonomic name string. It is often used to indicate hybrid genera. string false X Amelasorbus jackii
ind2 No Indicator between unit1 and unit2 of the taxonomic name string. string false Lycopodium X habereri
ind3 No Indicator between unit2 and unit3 of the taxonomic name string. string false Agave americana ssp. americana
ind4 No Indicator between unit3 and unit4 of the taxonomic name string. string false Agave americana ssp. americana var. expansa
usage Yes 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
credibilityRating Yes 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
currencyRating Yes 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
taxonAuthor No 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
hierarchySoFar Yes 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 EmbryophytaEmbryophytaEmbryophytaTracheophyta$Spermatophytina MagnoliopsidaMagnoliopsidaMagnoliopsidaLilianae$Poales PoaceaePoaceaePoaceaePoa$Poa annua$
hierarchyTSN Yes 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 202422202422202422954898$846494$954900$846496$846504 180631806318063846542$846620$40351$41074$41107$
publication No 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 PUBPUBPUB6355$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 664846648466484WoRMS - 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$
expert No 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 EXPEXPEXP203$Mark Mort AssociateProfessor,DepartmentofEcologyandEvolutionaryBiology,TheUniversityofKansas,1200SunnysideAvenue,Lawrence,Kansas,USA66045Associate Professor, Department of Ecology and Evolutionary Biology, The University of Kansas, 1200 Sunnyside Avenue, Lawrence, Kansas, USA 66045 AssociateProfessor,DepartmentofEcologyandEvolutionaryBiology,TheUniversityofKansas,1200SunnysideAvenue,Lawrence,Kansas,USA660452012-05-31 00:00:00$
otherSource No 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 SRCSRCSRC1119$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$
vernacular No 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 goldmossstonecropgoldmoss stonecropgoldmossstonecropEnglish$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$
rankID Yes 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
parentTSN Yes for usage = valid or accepted Taxonomic Serial Number of the accepted or valid direct parent taxon string false 23453
hierarchySoFarWRanks Yes 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:StreptophytaInfrakingdom:StreptophytaInfrakingdom:StreptophytaSuperdivision:Embryophyta Division:TracheophytaDivision:TracheophytaDivision:TracheophytaSubdivision:Spermatophytina Class:MagnoliopsidaClass:MagnoliopsidaClass:MagnoliopsidaSuperorder:Lilianae Order:PoalesOrder:PoalesOrder:PoalesFamily:Poaceae$Genus:Poa Species:PoaannuaSpecies:Poa annuaSpecies:Poaannua
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 791574791574791574793946$793954$802116 802117802117802117802119$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
geographicDivision No 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 NorthAmericaNorth AmericaNorthAmerica1996-11-05 00:00:00$
jurisdiction No 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 ContinentalUSContinental USContinentalUSIntroduced$2000-03-15 00:00:00$
hierarchicalSort Yes 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