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:
...
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-api-url}/ecoplots.tern.org.au/api/v1.0/species/count?speciesname=Allocasuarina torulosa&speciesname=Eucalyptus
...
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 |
...
...
...
...
output - URL Parameter
The output parameter is only available for the /species/count endpoint. This specifies the output data user wants to get. Its value can be either “scientific_name” or “taxon”. As the same suggests, “scientific_name” returns only the scientific name of the species while the “taxon” returns the entire taxonomy associated with that species. e.g. https:/{ecoplots-api-url}/api/v1.0/species/count?speciesname=Allocasuarina torulosa&output=taxon
...
The “dformat” parameter is only available for the /species/observations endpoint. This species the datatype for the return values and can either be "csv” or “ndjson” which returns the data as either as CSV or JSON respectively. e.g. https:/{ecoplots-api-url}/api/v1.0/species/observations?speciesname=Allocasuarina torulosa&dformat=ndjson
...
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.
...
Endpoint | Description | URI Example | Example Response Body |
|---|
/species/count
| 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: taxonomy keyword (part of the species name, kingdom, family, genus, etc.) spatial extent (point, line-transect, bounding box) temporal extent (date_from and date_to) site_id region dataset feature type
| /species/count?speciesname=eucalyptus&speciesname=acacia?output=scientific_name
| Info |
|---|
output=scientific_name is set by default
|
| output = scientific_name
| Code Block |
|---|
| {
"species": [
{
"count": 1236,
"speciesname": "Allocasuarina torulosa"
}
],
"status": 200
} |
output = taxon
| Code Block |
|---|
| {
"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
} |
|
/species/observed_property/list
| Method: POST Get the list all the unique observed property/parameter and its count by applying any combination following filters: taxonomy keyword (part of the species name, kingdom, family, genus, etc.) spatial extent (point, line-transect, bounding box) temporal extent (date_from and date_to) site_id region dataset observed property (parameter) feature type
| /species/observed_property/list?speciesname=eucalyptus
| | Code Block |
|---|
| {
"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
} |
|
/species/observations
| Method: POST Get the list all the observations made from the specified list of species by applying the following filters: taxonomy keyword (part of the species name, kingdom, family, genus, etc.) spatial extent (point, line-transect, bounding box) temporal extent (date_from and date_to) site_id region dataset observed property (parameter) feature type
| Note |
|---|
This endpoint uses pagination, hence the "page_number" and "page_size" are to be specified in the request body. Pagination is meant to be used as a data discovery tool (quickly returning small chunks of data). 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 "page_size" to -1. More details on pagenation can be found here. |
| Note |
|---|
Setting "page_size" to -1 will retrieve all the data which could possibly be millions of records. Depending on size of records and quality of connection, long wait times (10s of minutes) for response is expected. |
| Info |
|---|
In case of no "page_number" and/or "page_size" is provided. The default value, i.e, 1 and 20 for “page_number"and “page_size" respectively, will be used. |
| /species/observations?speciesname=eucalyptus&dformat=csv
| Info |
|---|
dformat=ndjson is set by default if no dformat is specified.
|
| dformat = ndjson
| Code Block |
|---|
| {
"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"
} |
dformat = csv
| Code Block |
|---|
| 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 |
| Info |
|---|
/species/observations does not return the "status": 200 upon success.
|
|
...