Dataqueries are different to queries - they are specifically designed to retrieve data from EcoPlots filtering data based on specified species. The dataqueries endpoints are an integral part of EcoPlots API, and are intended to facilitate efficient querying of relevant data. There are three dataqueries endpoints:
/species/count/species/observations/species/observed_property/list
In this section, we will comprehensively cover all the essential variables that must be supplied as URL parameters and/or in the request body for each endpoint, providing users with a clear understanding of what output to anticipate from the API.
speciesname - URL Parameter
All three of the endpoints use the speciesname parameter within the URL to find data points that include the relevent species name. Multiple species names (full or partial taxonomic names) can be passed at once using multiple occurrences of speciesname in URL parameter.
For example:
https://ecoplots.tern.org.au/api/v1.0/species/count?speciesname=Allocasuarina torulosa&speciesname=Eucalyptus
NOTE: It is possible to pass only a family or genus name within a URL parameter. For example, let's say Eucalyptus is passed as the speciesname parameter, the API will return documents for all of the species of the genus Eucalyptus.
output - URL Parameter
The output parameter is only available for the /species/count endpoint. This specifies what output data needs to be discovered. Its value can be either scientific_name or taxon. As the same suggests, scientific_name returns only the scientific name of the species, while taxon returns the entire taxonomy associated with the species specified with speciesname.
For example:
https://ecoplots.tern.org.au/api/v1.0/species/count?speciesname=Allocasuarina torulosa&output=taxon
dformat - URL Parameter
The dformat parameter is only available for the /species/observations endpoint. This specifies the datatype of the returned values, and can be formatted as either csv or ndjson.
For example:
https://ecoplots.tern.org.au/api/v1.0/species/observations?speciesname=Allocasuarina torulosa&dformat=ndjson
Request Body
The request body for all the Dataqueries endpoint has “query” field under which values of facets for filtering can be plugged in. While the “query” field is common for all the endpoints, the /species/observations has two more fields namely, "page_number” and “page_size”.
All the fields in request body are similar to EcoPlots API search queries except for “exact_match” field under the “query”. The following are all the subfields under “query” field in request body.
"dataset": ["dataset-url-1", "dataset-url-2", ...]“date_from": "2020-01-01"“date_to": "2023-05-09"“exact_match": false
In comparison to the EcoPlots API search query, the only added field in the request body is related to the "query" parameter. This parameter provides users with the flexibility to choose between a full-text search or tokenised word search for a given species name across all the records stored in the database. For example, when the"exact_match"is set to true and the given speciesname is Allocasuarina torulosa. The API will be returning only the documents containing exact species name while setting it to false will result in documents that has either Allocasuarina or torulosa or full Allocasuarina torulosa.“feature_type": ["feature-type-url-1", "feature-type-url-2", ...]“observed_property": ["observed-property-url-1", ...]“region": ["region-url-1", "region-url-2", ...]“site_id": ["site-id-url-1", "site-id-url-2", ...]“spatial": { }
NOTE: Except for "exact_match" field, everything else is similar to EcoPlots API Search Query. More details about it can be found here -> https://ternaus.atlassian.net/wiki/spaces/TDSAG/pages/2676621402/NEW_EcoPlots+API+search+queries#Parameter-(observable-property)
Below is an example of mock request body. Please note that for endpoints other than /species/observations, "page_number" and "page_size" is NOT required.
{
"page_number": 1,
"page_size": 25,
"query": {
"dataset": [
"http://linked.data.gov.au/dataset/ausplots",
"http://linked.data.gov.au/dataset/corveg"
],
"date_from": "2006-01-01",
"date_to": "2021-07-30",
"exact_match": true,
"feature_type": [
"http://linked.data.gov.au/def/tern-cv/2cf3ed29-440e-4a50-9bbc-5aab30df9fcd"
],
"observed_property": [
"http://linked.data.gov.au/def/tern-cv/83ac0278-51cd-4d1a-8e05-7c1fc68cf020"
],
"region": [
"http://linked.data.gov.au/dataset/asgs2016/stateorterritory/6",
"http://linked.data.gov.au/dataset/bioregion/CYP"
],
"site_id": [
"http://linked.data.gov.au/dataset/ausplots/site-nsabbs0001"
],
"spatial": {
"type" : "Polygon",
"coordinates" : [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
]
}
}
}
Endpoints
Endpoint | Description | URI Example | Example Response Body |
|---|---|---|---|
| Method: POST Get the list all the unique species name or complete its taxanomy and count of it’s documents in the database by applying any combination following filters:
|
|
{
"species": [
{
"count": 1236,
"speciesname": "Allocasuarina torulosa"
}
],
"status": 200
}
{
"species": [
{
"acceptedName": "Allocasuarina torulosa (Aiton) L.A.S.Johnson",
"acceptedNameID": "https://id.biodiversity.org.au/node/apni/2898576",
"class": "Equisetopsida",
"conceptID": "https://id.biodiversity.org.au/instance/apni/598754",
"count": 1236,
"family": "Casuarinaceae",
"kingdom": "Plantae",
"nameAccordingTo": "CHAH (2005), Australian Plant Census",
"nameAccordingToID": "https://id.biodiversity.org.au/reference/apni/42312",
"nomenclaturalCode": "ICN",
"nomenclaturalStatus": "",
"scientificName": "Allocasuarina torulosa (Aiton) L.A.S.Johnson",
"scientificNameAuthorship": "(Aiton) L.A.S.Johnson",
"scientificNameID": "https://id.biodiversity.org.au/name/apni/82362",
"taxonomicStatus": "accepted"
}
],
"status": 200
}
|
| Method: POST Get the list all the unique observed property/parameter and its count by applying any combination following filters:
|
| {
"observable_property": [
{
"count": 2243,
"label": "tree alive status",
"observed_property": "http://linked.data.gov.au/def/tern-cv/e3e69168-a959-4b8e-a1ea-2413fc3c2e4e"
},
{
"count": 1664,
"label": "scientific name",
"observed_property": "http://linked.data.gov.au/def/tern-cv/56195246-ec5d-4050-a1c6-af786fbec715"
},
{
"count": 1664,
"label": "IUCN conservation status",
"observed_property": "http://linked.data.gov.au/def/tern-cv/6f59a7ac-7acf-4c98-8db6-002ebd9a315f"
}
],
"status": 200
}
|
| Method: POST Get the list all the observations made from the specified list of species by applying the following filters:
This endpoint uses pagination, hence the Completeness cannot be guaranteed due to database design and implemented limits (only the first 10,000 elements of the whole subset can be retrieved). If you desire to retrieve more than 10,000 elements, please SET the More details on pagenation can be found here. Setting In case of no |
|
{
"dataset": "QBEIS",
"datasetId": "http://linked.data.gov.au/dataset/corveg",
"siteId": "http://linked.data.gov.au/dataset/corveg/site-4507",
"siteName": "53_659013",
"latitude": "-27.0876",
"longitude": "153.429",
"siteVisitId": "http://linked.data.gov.au/dataset/corveg/sv-4507",
"siteVisitName": "53_659013",
"featureType": "plant population",
"featureTypeId": "http://linked.data.gov.au/def/tern-cv/ae71c3f6-d430-400f-a1d4-97a333b4ee02",
"featureId": "http://linked.data.gov.au/dataset/corveg/site_visit_id-4507-speciesid-1454",
"observationId": "http://linked.data.gov.au/dataset/corveg/tern_plant_population-obs-taxon-4507-1454",
"parameterId": "http://linked.data.gov.au/def/tern-cv/70646576-6dc7-4bc5-a9d8-c4c366850df0",
"parameter": "taxon",
"result": "Allocasuarina torulosa (Aiton) L.A.S.Johnson",
"resultUnitId": null,
"resultTime": "1997-04-09T00:00:00"
}
dataset,datasetId,siteId,siteName,latitude,longitude,siteVisitId,siteVisitName,featureType,featureTypeId,featureId,observationId,parameterId,parameter,result,resultUnitId,resultTime QBEIS,http://linked.data.gov.au/dataset/corveg,http://linked.data.gov.au/dataset/corveg/site-4507,53_659013,-27.0876,153.429,http://linked.data.gov.au/dataset/corveg/sv-4507,53_659013,plant population,http://linked.data.gov.au/def/tern-cv/ae71c3f6-d430-400f-a1d4-97a333b4ee02,http://linked.data.gov.au/dataset/corveg/site_visit_id-4507-speciesid-1454,http://linked.data.gov.au/dataset/corveg/tern_plant_population-obs-taxon-4507-1454,http://linked.data.gov.au/def/tern-cv/70646576-6dc7-4bc5-a9d8-c4c366850df0,taxon,Allocasuarina torulosa (Aiton) L.A.S.Johnson,,1997-04-09T00:00:00
|
Add Comment