[Back]

Calling the WoRMS webservice from TCL


Step 1: Install the Tcl Web Services package (tclws)

Go to http://core.tcl.tk/tclws/home and install the package. You need to use at least version 2.1.2.
The package relies on Tcl 8.5 and also needs the packages tdom 0.8.1 and tls, plus the tcllib packages log, uri, and struct::set.

Step 2: Tcl code to use the WoRMS service
The following code provides some wrapper procedures, that can be used to call the WoRMS webservice.
 proc AphiaInit {} {
	 #
	 # init Aphia service and
	 # provide the handle "aphia" to access the service
	 #
	 set rc [WS::Client::GetAndParseWsdl https://www.marinespecies.org/aphia.php?p=soap&wsdl=1 {} aphia]
	 # we do not want to return the parsed service definition:
	 return
 }


 proc AphiaID {name} {
	 #
	 # return the AphiaID of a given scientific name
	 #
	 set rc [::WS::Client::DoCall aphia getAphiaID [list scientificname $name marine_only false]]
	 return [dict get $rc return]
 }


 proc AphiaData {id} {
	 #
	 # return taxonomical data for a given AphiaID:
	 #      name author rank status validAphia validName validAuthority
	 # (the last three items may be empty strings ...)
	 #
	 set rc [WS::Client::DoCall aphia getAphiaRecordByID [list AphiaID $id]]
	 # make sure, the variable exists, since it may be missing in result:
	 array set data {scientificname {} authority {} rank {} status {} valid_AphiaID {} \
	  valid_name {} valid_authority {}}
	 array set data [dict get $rc return]
	 return [list $data(scientificname) $data(authority) $data(rank) $data(status) \
	  $data(valid_AphiaID) $data(valid_name) $data(valid_authority)]
 }


 proc AphiaClassification {id} {
	 #
	 # return the classification of a taxon as a list
	 # each element is a list itself with {AphiaID name rank}
	 # the taxon itself is the first element of the list
	 #
	 set result [WS::Client::DoCall aphia getAphiaClassificationByID [list AphiaID $id]]
	 array set myArray [dict get $result return]
	 while 1 {
		 lappend rc [list $myArray(AphiaID) $myArray(scientificname) $myArray(rank)]
		 if {$myArray(child) eq ""} {break}
		 array set myArray $myArray(child)
	 }
	 set i [llength $rc]
	 for {incr i -1} {$i >= 0} {incr i -1} {
		 lappend rc2 [lindex $rc $i]
	 }
	 return $rc2
 }


 proc AphiaVernaculars {id} {
	 #
	 # return a list of vernacular names of a taxon.
	 # The list is returned as 
	 #
	 set rc [WS::Client::DoCall aphia getAphiaVernacularsByID [list AphiaID $id]]
	 set result [list]
	 set items [lindex [dict get $rc return] 1]
	 foreach item $items {
		 array set myArray {language_code {} vernacular {}}
		 array set myArray $item
		 #puts "$myArray(language_code) - $myArray(language): $myArray(vernacular)"
		 if {$myArray(language_code) ne ""} {
			 lappend result $myArray(language_code) $myArray(vernacular)
		 }
	 }
	 return $result
 }

Step 3: Actually call the service

These are some examples on how to use the above code (interactively entered at the Tcl prompt):
 % package require WS::Client
 2.1.2
 % # here, source the code from Step 2 above before you can issue the following commands ...
 % AphiaInit
 % AphiaID "Mytilus edulis"
 140480
 %
 % AphiaData 140480
 {Mytilus edulis} {Linnaeus, 1758} Species accepted 140480 {Mytilus edulis} {Linnaeus, 1758}
 %
 % AphiaClassification 140480
 {140480 {Mytilus edulis} Species} {138228 Mytilus Genus} {211 Mytilidae Family} {491766 Mytiloidea Superfamily}
 {210 Mytiloida Order} {206 Pteriomorphia Subclass} {105 Bivalvia Class} {51 Mollusca Phylum}
 {2 Animalia Kingdom} {1 Biota Superdomain}
 %
 % AphiaVernaculars 140480
 da blåmusling sv blåmussla nn blåskjel nb blåskjell nl {blauwe mossel} en {blue mussel}
 en {common mussel} en {edible blue mussel} nl {eetbare mossel} de {essbare Miesmuschel}
 es mejillon pt mexilhao ru midiya de Miesmuschel nl mossel fr {moule comestible}
 fr {moule commun}
Credits for this tutorial go to Torsten Berg (Marilim, Germany)