Difference between revisions of "How to use the DWB REST Webservice for Taxon Lists"

From Diversitymobile Wiki
Jump to navigation Jump to search
(Analysis queries examples)
 
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  
−
== Usage Exapmles ==
+
The '''[http://services.snsb.info/DTNtaxonlists/rest/v0.1/static/api-doc.html DTN Rest Webservice]''' is set up for machine2machine communication to provide open and free access to taxon list information organised in a DWB cloud installation (TNT) of [https://diversityworkbench.net/Portal/DiversityTaxonNames DiversityTaxonNames (DTN)], see overview on [[DTN_Taxon_Lists_Services|content]]. It is normally used by machines via client programs but from time to time it can also be useful to create requests manually.
  
−
The DTN Rest Webservice is meant to be used by Programms but from time to time it can also be useful to create requests manually.
 
−
The main starting point for the service is the list as all taxon names belonging to a list.
 
  
 +
==Usage Examples==
  
−
= Query all available lists =
+
The main starting point for the service is the taxonomic list as all taxon names belonging to a list. A list is also known as a project.
 +
The REST service delivers mainly cached results to improve the respond times with a cache duration up to two weeks. If one needs more recent results please ask the [http://www.snsb.info/People.html administrators].
 +
 
 +
== Query all available lists ==
  
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists
Line 12: Line 14:
 
The result is a list with all available lists. For each item a link to the elements is given. If you follow this link all taxon name IDs are presented.
 
The result is a list with all available lists. For each item a link to the elements is given. If you follow this link all taxon name IDs are presented.
  
−
= Query all taxon name IDs of a list =
+
== Query all taxon name IDs of a list ==
  
 
A list is defined by the database name (e.g "DiversityTaxonNames_Animalia") and the project number (aka list number):
 
A list is defined by the database name (e.g "DiversityTaxonNames_Animalia") and the project number (aka list number):
Line 20: Line 22:
 
This URL is a concatenation of the former URL with the database name and the project name. The result is an array of taxon name ids, gain with links to details for the taxon name.
 
This URL is a concatenation of the former URL with the database name and the project name. The result is an array of taxon name ids, gain with links to details for the taxon name.
  
−
= Which analysis are available for this list? =
+
== Which analysis are available for this list? ==
  
 
For each name in a database additional values are stored in different analysis categories. An analysis might contain numeric values like the leaf length in mm, or category like the status of the taxon in a specific region, or just an information text. This is like an attribute which is given to the taxonomic name.  Al analysis have IDs, in the example the analysis ID 2 is the status in Bavaria. As the analysis ID is only valid for a list in a specific database.
 
For each name in a database additional values are stored in different analysis categories. An analysis might contain numeric values like the leaf length in mm, or category like the status of the taxon in a specific region, or just an information text. This is like an attribute which is given to the taxonomic name.  Al analysis have IDs, in the example the analysis ID 2 is the status in Bavaria. As the analysis ID is only valid for a list in a specific database.
Line 28: Line 30:
 
This query lists all analysis IDs which are used in the given list.
 
This query lists all analysis IDs which are used in the given list.
  
−
= What is this analysis about? =
+
== What is this analysis about? ==
  
 
To query information about the analysis ID 9 from the above database the API entry is now the analysiscategories.
 
To query information about the analysis ID 9 from the above database the API entry is now the analysiscategories.
Line 36: Line 38:
 
Here one finds Information about the list and links to further details like the allowed analysis values.
 
Here one finds Information about the list and links to further details like the allowed analysis values.
  
−
= Query an analysis value for a taxon name ID =
+
== Query an analysis value for a taxon name ID ==
  
 
This is the normal way to query analysis values. For each taxon name ID separately.
 
This is the normal way to query analysis values. For each taxon name ID separately.
Line 42: Line 44:
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysis/DiversityTaxonNames_Animalia/701/4000202/6
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysis/DiversityTaxonNames_Animalia/701/4000202/6
  
 +
[
 +
  {
 +
    "AnalysisID": 6,
 +
    "AnalysisValue": "2",
 +
    "DatabaseName": "DiversityTaxonNames_Animalia",
 +
    "NameID": 4000202,
 +
    "Notes": null,
 +
    "ProjectID": 701,
 +
    "TaxonNameListRefID": -1,
 +
    "links": [
 +
      ...
 +
    ]
 +
  }
 +
]
 
This will return the analysis value from analysis 6 for the taxon name id 4000202 in list 701.
 
This will return the analysis value from analysis 6 for the taxon name id 4000202 in list 701.
  
−
Or to query the status in BAvaria for taxon name ID 200:
+
Or to query the status in Bavaria for taxon name ID 200:
  
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysis/DiversityTaxonNames_Plants/1129/200/2
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysis/DiversityTaxonNames_Plants/1129/200/2
Line 50: Line 66:
 
The result contains the analysis value "E" and links to the analysis and the analysis value definition.
 
The result contains the analysis value "E" and links to the analysis and the analysis value definition.
  
−
= What means the "E" in the above example? =
+
[
 +
  {
 +
    "AnalysisID": 2,
 +
    "AnalysisValue": "E",
 +
    "DatabaseName": "DiversityTaxonNames_Plants",
 +
    "NameID": 200,
 +
    "Notes": null,
 +
    "ProjectID": 1129,
 +
    "TaxonNameListRefID": -1,
 +
    "links": [
 +
      {
 +
        "name": "analysiscategory",
 +
        "rel": "category",
 +
        "type": "uri",
 +
        "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/"
 +
      },
 +
      {
 +
        "name": "analysiscategoryvalues",
 +
        "rel": "valueset",
 +
        "type": "uri",
 +
        "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/valuedefinitions/"
 +
      },
 +
      {
 +
        "name": "listproject",
 +
        "rel": "related",
 +
        "type": "uri",
 +
        "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/projects/1129/"
 +
      },
 +
      {
 +
        "name": "name",
 +
        "rel": "related",
 +
        "type": "uri",
 +
        "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/names/DiversityTaxonNames_Plants/200/"
 +
      }
 +
    ]
 +
  }
 +
]
 +
 
 +
== What means the "E" in the above example? ==
 
   
 
   
 
Following the link analysiscategoryvalues form the result above will present a list for all defined values from the analysis containing also a description for each category.
 
Following the link analysiscategoryvalues form the result above will present a list for all defined values from the analysis containing also a description for each category.
Line 57: Line 111:
  
 
The resulting json list has an entry for "E":
 
The resulting json list has an entry for "E":
−
{
+
 
−
  "AnalysisValue": "E",
+
{
−
  "Description": "eingebürgert"
+
  ...
−
}
+
  "AnalysisValue": "E",
 +
  "Description": "eingebürgert"
 +
  ...
 +
}
  
  
−
= Query a list to get all taxon name IDs from a list which have an entry for an analysis ID =
+
Or the direct link to the desciption for "E" of analysis ID 2:
 +
 
 +
http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategorievalues/DiversityTaxonNames_Plants/2/E/
 +
 
 +
 
 +
[
 +
  {
 +
    "AnalysisID": 2,
 +
    "AnalysisValue": "E",
 +
    "DatabaseName": "DiversityTaxonNames_Plants",
 +
    "Description": "eingeb\u00fcrgert",
 +
    "DisplayOrder": null,
 +
    "DisplayText": "E",
 +
    "Notes": null,
 +
    "links": [
 +
      {
 +
        "name": "analysiscategory",
 +
        "rel": "category",
 +
        "type": "uri",
 +
        "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/"
 +
      },
 +
      {
 +
        "name": "analysiscategoryvalues",
 +
        "rel": "valueset",
 +
        "type": "uri",
 +
        "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/valuedefinitions/"
 +
      }
 +
    ]
 +
  }
 +
]
 +
 
 +
== Query a list to get all taxon name IDs from a list which have an entry for an analysis ID ==
  
 
It is possible to query a list for a specific analysis. For example to get all taxon names for a size class less or equal 2:
 
It is possible to query a list for a specific analysis. For example to get all taxon names for a size class less or equal 2:
Line 73: Line 161:
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists/DiversityTaxonNames_Plants/1129/analysis/2?value=%25&op=like&refid=-1
 
http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists/DiversityTaxonNames_Plants/1129/analysis/2?value=%25&op=like&refid=-1
  
−
The result is an list with all taxon name IDs which have an assigned analysis value for analysis category 2 including the information which analysis value is assigned .
+
The result is an list with all taxon name IDs which have an assigned analysis value for analysis category 2 including the information which analysis value is assigned. Beware that this query gives a huge result which might slow down the browser!
 +
 
 +
== Get the accepted name for a given TaxonNameID ==
 +
 
 +
The taxon name id is a unique identifier of a the taxonname in a database. The accepted name is an option that a taxon name is the one which should be used. For convenience a search function is implemented to return the accepted name ID according to the default 'opinion' aka. the default project in the current database. The API call for NameID 1 in the database DiversityTaxonNames_Plants:
 +
 
 +
http://services.snsb.info/DTNtaxonlists/rest/v0.1/names/DiversityTaxonNames_Plants/1/acceptednameid
 +
 
 +
The result contains the AcceptedNameID if there is an accepted name which might be equal to the given NameID. It contains also a link to the description of the accepted taxon name.
 +
 
 +
To retrieve the NameID for a given TaxonName the name search can be used:
 +
 
 +
http://services.snsb.info/DTNtaxonlists/rest/v0.1/names?exactname=Abies%20alba%20Mill. '''(workable with final "."!)'''
 +
 
 +
The taxon name must be URL encoded. The result is a list of URLs to all matching names. In the name details the DatabaseName and NameID is always given.

Revision as of 14:17, 14 July 2020

The DTN Rest Webservice is set up for machine2machine communication to provide open and free access to taxon list information organised in a DWB cloud installation (TNT) of DiversityTaxonNames (DTN), see overview on content. It is normally used by machines via client programs but from time to time it can also be useful to create requests manually.


Usage Examples

The main starting point for the service is the taxonomic list as all taxon names belonging to a list. A list is also known as a project. The REST service delivers mainly cached results to improve the respond times with a cache duration up to two weeks. If one needs more recent results please ask the administrators.

Query all available lists

http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists

The result is a list with all available lists. For each item a link to the elements is given. If you follow this link all taxon name IDs are presented.

Query all taxon name IDs of a list

A list is defined by the database name (e.g "DiversityTaxonNames_Animalia") and the project number (aka list number):

http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists/DiversityTaxonNames_Animalia/701/

This URL is a concatenation of the former URL with the database name and the project name. The result is an array of taxon name ids, gain with links to details for the taxon name.

Which analysis are available for this list?

For each name in a database additional values are stored in different analysis categories. An analysis might contain numeric values like the leaf length in mm, or category like the status of the taxon in a specific region, or just an information text. This is like an attribute which is given to the taxonomic name. Al analysis have IDs, in the example the analysis ID 2 is the status in Bavaria. As the analysis ID is only valid for a list in a specific database.

http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists/DiversityTaxonNames_Animalia/701/analysis/

This query lists all analysis IDs which are used in the given list.

What is this analysis about?

To query information about the analysis ID 9 from the above database the API entry is now the analysiscategories.

http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Animalia/9/

Here one finds Information about the list and links to further details like the allowed analysis values.

Query an analysis value for a taxon name ID

This is the normal way to query analysis values. For each taxon name ID separately.

http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysis/DiversityTaxonNames_Animalia/701/4000202/6 

[
 {
   "AnalysisID": 6,
   "AnalysisValue": "2",
   "DatabaseName": "DiversityTaxonNames_Animalia",
   "NameID": 4000202,
   "Notes": null,
   "ProjectID": 701,
   "TaxonNameListRefID": -1,
   "links": [
     ...
    ]
  }
]

This will return the analysis value from analysis 6 for the taxon name id 4000202 in list 701.

Or to query the status in Bavaria for taxon name ID 200:

http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysis/DiversityTaxonNames_Plants/1129/200/2

The result contains the analysis value "E" and links to the analysis and the analysis value definition. 

[
 {
   "AnalysisID": 2,
   "AnalysisValue": "E",
   "DatabaseName": "DiversityTaxonNames_Plants",
   "NameID": 200,
   "Notes": null,
   "ProjectID": 1129,
   "TaxonNameListRefID": -1,
   "links": [
     {
       "name": "analysiscategory",
       "rel": "category",
       "type": "uri",
       "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/"
     },
     {
       "name": "analysiscategoryvalues",
       "rel": "valueset",
       "type": "uri",
       "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/valuedefinitions/"
     },
     {
       "name": "listproject",
       "rel": "related",
       "type": "uri",
       "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/projects/1129/"
     },
     {
       "name": "name",
       "rel": "related",
       "type": "uri",
       "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/names/DiversityTaxonNames_Plants/200/"
     }
   ]
 }
]

What means the "E" in the above example?

Following the link analysiscategoryvalues form the result above will present a list for all defined values from the analysis containing also a description for each category.

http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/valuedefinitions/

The resulting json list has an entry for "E": 

{
  ...
  "AnalysisValue":	"E",
  "Description":	"eingebürgert"
  ...
}


Or the direct link to the desciption for "E" of analysis ID 2:

http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategorievalues/DiversityTaxonNames_Plants/2/E/ 


[
 {
   "AnalysisID": 2,
   "AnalysisValue": "E",
   "DatabaseName": "DiversityTaxonNames_Plants",
   "Description": "eingeb\u00fcrgert",
   "DisplayOrder": null,
   "DisplayText": "E",
   "Notes": null,
   "links": [
     {
       "name": "analysiscategory",
       "rel": "category",
       "type": "uri",
       "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/"
     },
     {
       "name": "analysiscategoryvalues",
       "rel": "valueset",
       "type": "uri",
       "uri": "http://services.snsb.info/DTNtaxonlists/rest/v0.1/analysiscategories/DiversityTaxonNames_Plants/2/valuedefinitions/"
     }
   ]
 }
]

Query a list to get all taxon name IDs from a list which have an entry for an analysis ID

It is possible to query a list for a specific analysis. For example to get all taxon names for a size class less or equal 2:

http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists/DiversityTaxonNames_Animalia/701/analysis/6?value=2&op=le&refid=-1

As a short cut one can get all taxon name IDs for all taxon names which have an analysis ID. For example query all taxon name IDs which have an assigns analysis category of 2 (Status in Bavaria):

http://services.snsb.info/DTNtaxonlists/rest/v0.1/lists/DiversityTaxonNames_Plants/1129/analysis/2?value=%25&op=like&refid=-1

The result is an list with all taxon name IDs which have an assigned analysis value for analysis category 2 including the information which analysis value is assigned. Beware that this query gives a huge result which might slow down the browser!

Get the accepted name for a given TaxonNameID

The taxon name id is a unique identifier of a the taxonname in a database. The accepted name is an option that a taxon name is the one which should be used. For convenience a search function is implemented to return the accepted name ID according to the default 'opinion' aka. the default project in the current database. The API call for NameID 1 in the database DiversityTaxonNames_Plants:

http://services.snsb.info/DTNtaxonlists/rest/v0.1/names/DiversityTaxonNames_Plants/1/acceptednameid

The result contains the AcceptedNameID if there is an accepted name which might be equal to the given NameID. It contains also a link to the description of the accepted taxon name.

To retrieve the NameID for a given TaxonName the name search can be used:

http://services.snsb.info/DTNtaxonlists/rest/v0.1/names?exactname=Abies%20alba%20Mill. (workable with final "."!)

The taxon name must be URL encoded. The result is a list of URLs to all matching names. In the name details the DatabaseName and NameID is always given.

Retrieved from "https://www.diversitymobile.net/mediawiki/index.php?title=How_to_use_the_DWB_REST_Webservice_for_Taxon_Lists&oldid=13997"