Difference between revisions of "How to use the DWB REST Webservice for Taxon Lists"
| (20 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == Usage Examples == | + | 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. |
| + | |||
| + | |||
| + | ==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 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 | + | 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 = | + | == 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 102: | Line 104: | ||
] | ] | ||
| − | = What means the "E" in the above example? = | + | == 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 149: | Line 151: | ||
] | ] | ||
| − | = Query a list to get all taxon name IDs from a list which have an entry for an analysis ID = | + | == 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 160: | Line 162: | ||
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! | 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.
[
{
"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.
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:
[
{
"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:
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):
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.