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