How to use the DWB REST Webservice for Taxon Lists

From Diversitymobile Wiki
Jump to: navigation, search

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 retreive 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.

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.