Difference between revisions of "How to use the DWB REST Webservice for Taxon Lists"
| Line 3: | Line 3: | ||
| − | == Usage Examples == | + | ==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 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]. | 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 14: | 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 22: | 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 30: | 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 38: | 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 104: | 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 151: | 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: | ||
Revision as of 15:57, 4 September 2019
The DTN Rest Webservice is set up for machine2machine communication to provide open and free access to taxon list information organised in a TNT installation 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!