Digital Delta Eco Extensions - Measurements API documentation version 0.9.5
https://ddecotest.aquadesk.nl
About
The Digital Delta Eco API is a specialization of the original Digital Delta API. The Eco API is focused on measurements in the Ecology realm (taxa, chemicals, physical objects), where measurements are mostly observation-based, instead of being measured by automated systems.
Due to this, the measurements are not on a fixed time schedule. Therefore, the time series are less usable for the Eco API.
Another reason for a specialization is that the data is less uniform: one sample can contain multiple organisms or chemicals. Furthermore, additional meta-data might be specified with measurements.
A list of implementations of the API is available here.
The current specification version is 0.9 with status 'Proposal'.
Ecological Measurements
Ecological measurements are divers, and mostly not a goal, but a means. A means to produce a spreadsheet, display a map, analyse what happens to a species in time, analyse the quality of a body of water, required reporting to the government, etc.
To be able to provide relevant information, the following is stored with a measurement:
Topic | Description |
---|---|
Who | What organisation requested the measurement and/or performed the sampling/analysis. |
When | When the sample was taken, the analysis performed. Ecological measurements are mostly non-automated and non-continuous. |
Where | Where the measurement was taken. This includes a position, but also what compartment such as open water, shore, vegetation. Some measurements are taken on a boat, so the position of the measurement may not be fixed and can differ from the location where the measurement object. |
What | This can range from a single chemical, to multiple kinds of species per measurement. Next to the parameter (mostly applies to species), more specifications might be requested, such as life stage, gender, behaviour. |
Why | The reason why the measurement took place. Was it, for instance, for a regular monitoring, was it for a specific project, was it for assessments, etc. |
How | The how described how a sample was taken, for instance: what fish net was used, what size the holes in the net were, what handbook was used to sample, or to analyse, etc. |
To allow those questions to be answered, the information required to answer those questions, need to be stored. That makes ecological measurements more complex, since that meta-information varies.
Furthermore, many ecological measurements require manual labour (getting the sample, preparing the sample, observing the sample) and are not measured in a fixed interval. Time series are therefore a less useful format for this type of measurements.
Measurement level
The Measurement level API is required and is filterable and pageable. An optional geojson specifier is recommended. The expandable specifier is optional. The RAML definition is here.
Implementation topics
Filter Syntax
Filtering can be performed by constructing a search filter using the following syntax:
<parametername>:<comparer>:<comparevalue>[;<parametername>:<comparer>:<comparevalue>]
Comparer | Description | Data types |
---|---|---|
eq | equal | string, date, number |
ne | unequal | string, date, number |
lt | less than | date, number |
le | less than or equal to | date, number |
ge | greater than or equal to | date, number |
gt | greater than | date, number |
in | item is one of the values in the list | string, number |
not | item is NOT one of the values in the list | string, number |
like | String contains the value. | string |
startswith | String starts with the value. | string |
endswith | String ends with the value. | string |
inbbox | Item is within the bounding box, defined by 4 numbers | bbox |
inpolygon | Item is within the polygon, defined by list of numbers, where each x and y are a numbers in the array | bbox |
notinbbox | Item is NOT within the bounding box, defined by 4 numbers | polygon |
notinpolygon | Item is NOT within the polygon, defined by list of numbers, where each x and y are a numbers in the array | polygon |
wkt | Item is within the Well-known-text definition | Wkt |
all | all items in the list must be present in the queried item | string, number |
Formatting |
---|
String compares are NOT case sensitive and must be surrounded by quotes. |
Arrays are expressed in JSON format. This means that they are surrounded by square brackets ([ and ]) and the array values are separated by comma's. |
Parameter names are NOT case sensitive. |
Number formats are in US notation. This means fractional separators are periods. Comma's (thousands-separators) are ignored. |
Date field notation is yyyy-MM-dd and must be surrounded by quotes. |
Bbox type requires an array of 4 numeric values. The uneven-numbers represent an X-ordinate, the even-numbers represent an Y-ordinates. The uneven and the following even number represent a coordinate in WGS84. |
Polygon type requires an array of numeric values. The number of items in the array need to be even. The uneven-numbers represent an X-ordinate, the even-numbers represent an Y-ordinates. The uneven and the following even number represent a coordinate in WGS84. |
Examples |
---|
location:eq:"NLKAD";parameter:eq:"Eukariota";organisation:eq:"RWS",measuredvalue:gt:1000;measuredunitSymbol:eq:"n" |
location:in:["NKLAD","NKLBVA","NLKBRA"];parameter:eq:"Eukariota";organisation:eq:"RWS";measuredvalue:gt:1000,measuredunitSymbol:eq:"n" |
location:in:["NKLAD","NKLBVA","NLKBRA"];parameter:in:["Eukariota [1]","Plantae"];measuredvalue:gt:1000;measuredunitSymbol:eq:"n" |
locationArea:inpolygon:[1,2,3,4];parameterCode:in:["Eukariota [1]","Plantae"];measuredvalue:gt:1000; |
Example of a filter in a URL: /organisations/?filter=organisation:eq:"RWS"
Sorting is the responsibility of the caller. It is the responsibility of the provider to always return results in the same order.
General URL syntax: available parameters on the root level:
Field | Meaning |
---|---|
filter | See 'FilterSyntax'. |
page | Returns the specified page of records. See 'Paging logic'. |
pagesize | The maximum number of records returned for the page. See 'Paging logic'. |
Error Handling
When errors are encountered, error information is provided as follows: The HTTP status code is set to be a value between 400 and 499. The response body has the structure of the Problem type (see 'Minimal'):
{
"type": "Filter query syntax",
"title": "Query syntax",
"typeinfo": null,
"status": 400,
"detail": "See 'errors' attribute.",
"ìnstance": null,
"errors": [
{
"errortype": "InvalidValue",
"context": "symbol:eq:"
}
]
}
The value of field 'type' contains an error message. The value of field 'typeinfo' is optional and can contain a link to a page explaining the message. The value of field 'title' contains the title of the message. The value of field 'status' has contains the HTTP status code. The value of field 'detail' can provide extra information, such as given in the example. The value of field 'instance' is optional and can contain information that identifies the error and request at the provider. The field 'errors' is optional and can contain further information concerning the error. In the example, it explains what is wrong with the query syntax.
Paging logic
Initialisation
The minimum page> is 1. The provider specifies minimum, maximum and default pagesize>. If pagesize> is not specified, pagesize> is the provider-specified default page size. If page> is not specified, page> is assumed to be 1.
Paging process
- If <filter> is set, <filter> is applied to the data set.
- ((<page> - 1) * <pagesize>) records are skipped.
- A maximum of <pagesize> records are returned from the resulting data set.
To find out what filters are recognised by the service, the /filters segment can be used on the endpoints. The filters segment does not recognise any additional parameters.
Also see 'Error handling' and 'Filter Syntax'.
Contents of the Repository
The structure of this repository is as follows:
Directory | Purpose |
---|---|
<root> | Contains the base RAML definitions, the readme file and the change history. |
.NET Filter Syntax Parser | Contains a sample implementation of a .NET project that parses the Filter Syntax including NUnit tests. |
AquaDesk Examples | JSON responses from AquaDesk for demonstration purposes. |
Html | Contains generated HTML documentation in two themes: the slate theme includes types. |
Libraries | RAML libraries in use. |
PostMan Scripts | Contains sample PostMan scripts in PostMan Collection 2.1 format. |
Security | Contains Security-related RAML definitions. |
Change History
In Version | Change Date | Who | Description |
---|---|---|---|
0.9 | 20180621 | Geri Wolters (EcoSys) | Initial release. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Provider block defined. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Provider block added to list responses. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Provider block added to problem responses. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Moved page-related response properties to the links block. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Added self-property to links block. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Corrected service names. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Added purpose end-points. |
0.9.1 | 20180710 | Geri Wolters (EcoSys) | Examples updated. |
0.9.2 | 20180716 | Geri Wolters (EcoSys) | Added end-point literature. |
0.9.2 | 20180716 | Geri Wolters (EcoSys) | Added geometry to measurement objects. |
0.9.2 | 20180717 | Geri Wolters (EcoSys) | Added taxonrank to biotaxon parameters. |
0.9.2 | 20180717 | Geri Wolters (EcoSys) | Moved totalObjectCount to the Links resource object in accordance with DD-API 2.0. |
0.9.2 | 20180717 | Geri Wolters (EcoSys) | Links block renamed to Paging in accordance with DD-API 2.0. |
/eco
Retrieves a list of measurements.
Defines query parameters for pageable requests.
Checks if the specified ids are present in the service. Returns only the list of ids from the list that are still present.
Retrieves a list of measurements as a GeoJSON FeatureCollection.
Defines query parameters for pageable requests.