TOQE: the Thesaurus Query Expander

Home | Documentation | Demo | Repository (subversion) |



Client API

Methods

Concept

  • getConceptsByTerm()
    Returns concepts matching a given term. Each concept contains information about its reference.
    Arguments
    • term:String (required)
      string containing one or multiple terms (may contain wildcards).
    • thesaurus:String (required)
      string containing the thesaurus name to use

    Example
      Query:
    http://search.biocase.org/toqe/toqe.py?term=Calendula+arvensis&thesaurus=Standardliste&method=getConceptsByTerm
    
      Response
    <conceptSet searchTerm="calendula arvensis">
    	<concept dataSchemaConcept="DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/HigherTaxa/HigherTaxon/HigherTaxonName">
    		<name id="10794" relationtype="" id2="" name="">Calendula arvensis @authorL.</name>
    		<status>accepted</status>
    		<reference id="1">R. Wisskirchen ET H. Haeupler - Standardliste der Farn- und Blütenpflanzen Deutschlands 1998.</reference>
    	</concept>
    </conceptSet>
    


  • getNamesLike()
    Returns names matching a given term. Each names contains information about its reference.
    Arguments
    • term:String (required)
      string containing one term with wildcards.
    • thesaurus:String (required)
      string containing the thesaurus name to use

    Example
      Query:
    http://search.biocase.org/toqe/toqe.py?term=calendula+arv%25&method=getNamesLike&thesaurus=Euro%2BMed+Plantbase
    
      Response
    <conceptSet searchTerm="calendula arv%">
    	<concept dataSchemaConcept="noconcept">
    		<name id="" relationtype="" id2="" name="">Calendula arvensis</name>
    		<reference id="500000">Euro+Med preliminary checklist as merged from Flora Europaea..</reference>
    	</concept>
    	<concept dataSchemaConcept="noconcept">
    		<name id="" relationtype="" id2="" name="">Calendula arvensis</name>
    		<reference id="7000000">Greuter 2005-2009.</reference>
    	</concept>
    	<concept dataSchemaConcept="noconcept">
    		<name id="" relationtype="" id2="" name="">Calendula arvensis subsp. aegyptiaca</name>
    		<reference id="7000000">Greuter 2005-2009.</reference>
    	</concept>
    	<concept dataSchemaConcept="noconcept">
    		<name id="" relationtype="" id2="" name="">Calendula arvensis subsp. arvensis</name>
    		<reference id="500000">Euro+Med preliminary checklist as merged from Flora Europaea..</reference>
    	</concept>
    </conceptSet>
    


  • getRelatedConceptsByTerm()
    Returns concepts and semanticaly related concepts for a given term for the given relations.
    Arguments
    • term:String (required)
      string containing one or multiple terms (may contain wildcards).
    • relation:String [] (required)
      string containing the relation name.
    • thesaurus:String (required)
      string containing the thesaurus name to use

    Example
      Query:
    http://search.biocase.org/toqe/toqe.py?method=getRelatedConceptsByTerm&term=Abies&relation=Taxonomic hierarchy&thesaurus=Euro%2BMed+Plantbase&
    
      Response
    <response success="true">
      <conceptSet>
        <concept dataSchemaConcept="DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/HigherTaxa/HigherTaxon/HigherTaxonName">
          <name id="106385" relationtype="" id2="" name="">Abies@authorMill.</name>
          <status>accepted</status>
          <reference id="500000">
          Euro+Med preliminary checklist as merged from Flora Europaea, Med-Checklist and Flora of Macaronesia (for families not yet treated in Med-Checklist, the distributional record does not include N Africa and SW Asia)..
          </reference>
          <relationSet>
            <relation name="Taxonomic hierarchy">
              <concept dataSchemaConcept="DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString">
                <name id="106415" relationtype="is taxonomically included in" id2="106385" name="Abies">Abies alba@authorMill.</name>
                <status>accepted</status>
                <reference id="500000">
                Euro+Med preliminary checklist as merged from Flora Europaea, Med-Checklist and Flora of Macaronesia (for families not yet treated in Med-Checklist, the distributional record does not include N Africa and SW Asia)..
                </reference>
                <reference_2 id="500000">
                Euro+Med preliminary checklist as merged from Flora Europaea, Med-Checklist and Flora of Macaronesia (for families not yet treated in Med-Checklist, the distributional record does not include N Africa and SW Asia)..
                </reference_2>
              </concept>
            ...
    


  • getAllRelatedConcepts()

    Returns concepts and semanticaly related concepts for a given concept for the given relations
    Arguments
    • conceptKey:String (required)
      key containing the nameID and the reference ID
    • relation:String [] (required)
      string containing the relation name
    • recursive:Boolean (Optional)
      boolean specifying if the search is recursive or not: the number of recursion steps is specified by the respective thesaurus (example)
    • thesaurus:String (required)
      string containing the thesaurus name to use

    Example
      Query
    http://search.biocase.org/toqe/toqe.py?conceptKey=7000009toto7000000totoaccepted&method=getAllRelatedConcepts&thesaurus=Euro%2BMed+Plantbase&relation=AllTaxo
      Response
    <response success="true">
      <conceptSet>
        <concept dataSchemaConcept="DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/HigherTaxa/HigherTaxon/HigherTaxonName">
          <name id="7000009" relationtype="" id2="" name=""></name>
          <status>accepted</status>
          <reference id="7000000"></reference>
          <relationSet>
            <relation name="AllTaxo">
              <concept dataSchemaConcept="DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/HigherTaxa/HigherTaxon/HigherTaxonName">
                <name id="118963" relationtype="is taxonomically included in_inverse" id2="7000009" name="Calendula arvensis@authorL.">Calendula@authorL.</name>
                <status>accepted</status>
                <reference id="7000000">Greuter 2005-2007.</reference>
                <reference_2 id="7000000">Greuter 2005-2007.</reference_2>
              </concept>
              <concept dataSchemaConcept="DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString">
                <name id="7000010" relationtype="is homotypic synonym of" id2="7000009" name="Calendula arvensis@authorL.">Caltha arvensis@authorVaill.</name>
                <status>synonym</status>
                <reference id="7000000">Greuter 2005-2007.</reference>
                <reference_2 id="7000000">Greuter 2005-2007.</reference_2>
              </concept>
              ...
    

Service

  • getMethods()

    Return a list of methods TOQE is capable of.
    Arguments
    • None.

    Example Response
    <methodSet>
        <method name="myFirstMethod" />
        <method name="mySecondMethod" />
        <method name="myThirdMethod" />
    </methodSet>
    


  • getMethodInfo()

    Returns information for a given TOQE API method.
    Arguments
    • methodName:String (required)
      The name of the method to fetch information for.

  • Example Response
    <method name="getConceptByTerm">
    	<description>
    		Returns concepts matching a given term. Each concept contains information 
    		about its reference. If there is no reference data available, this option
    		will be ignored.
    	</description>
    	<example_response>None</example_response>
    	<arguments>None</arguments>
    	<errors>None</errors>
    </method>
    

Errors


  • Unknown method name:
    Example:
    Query:
    http://search.biocase.org/toqe/toqe.py?term=Calendula+arvensis&thesaurus=Standardliste&method=fooMethod
    Response:
    <response success="false">
    <error code="93" message="Method not found" detail="The requested method was not found."/>
    </response>
    

  • No concept found
    Example:
    Query:
    http://search.biocase.org/toqe/toqe.py?term=Calendula+arv&thesaurus=Standardliste&method=getConceptByTerm
    <response success="false">
    <error code="1" message="No related concept" detail="There is no conceptually related concept with the desired relation."/>
    </response>

  • Invalid parameters or missing parameters
    Examples:
    Query (relation parameter is missing):
    http://search.biocase.org/toqe/toqe.py?term=Calendula+arvensis&thesaurus=Standardliste&method=getRelatedConceptsByTerm
    Response:
    <response success="false">
    <error code="92" message="Invalid signature" detail="The passed signature was invalid."/>
    </response>
    Query (method parameter is missing):
    http://search.biocase.org/toqe/toqe.py?term=Calendula+arvensis&thesaurus=Standardliste
    Response:
    <response success="false">
    <error code="100" message="Request not well formed" detail="Request was not formed well."/>
    </response>

Formats

Request Format

For now, there is only a REST-like Endpoint available. Method-call example:

http://path.to/endpoint?method=test&name=value

Response Format

Method response is expressed in a well-defined XML Format. See Schema

A method call returns this:

<?xml version="1.0" encoding="utf-8" ?>
<response success="true">
	[xml-payload-here]
</response>

If an error occurs, the following is returned:

<?xml version="1.0" encoding="utf-8" ?>
<response success="false">
	<error code="[error-code]" message="[error-message]" 
               detail="[error-detail]" />
</response>

Explanation of standard error codes: if a method call fails, the service will answer with one or more errors in the format:
<error code="[error-code]" message="[error-message]" />
Error-codes < 100 are reserved for method specific errors. All other are standard errors.

Data Schema Concept

Concepts returned by a method call might contain information about a Data Schema Concept they support. Following are examples of possible schemas.

  • ABCD

DB API: to be done