EcoPlots API endpoints introduction

EcoPlots API supports the discovery and download of survey-based ecological data. For this purpose, a series of endpoints are available to allow users to download subsets of data, organised in the following key concepts.

1 Data endpoints
- 1.1 Datasources
- 1.2 Datasets
- 1.3 Sites and SiteVisits
  - 1.3.1 Sites
  - 1.3.2 SiteVisits
  - 1.3.3 Site or SiteVisit attributes
- 1.4 Observations
  - 1.4.1 Observation attributes
- 1.5 Feature of interest attributes
- 1.6 Instrument attributes
- 1.7 Taxon
2 Discovery endpoints

Data endpoints

Datasources

All information in EcoPlots belongs to one of multiple datasources. To retrieve more details about the available datasources in EcoPlots, you should use the /datasources endpoint.

Request example:

curl -X POST "https://ecoplots-test.tern.org.au/api/v1.0/datasources?dformat=ndjson" -H "accept: */*" -H "X-Api-Key: aAbBcC...xXyYzZ" -H "Content-Type: application/json" -d "{\"query\":{}}"

Response example:

{
   "dataset":"TERN Surveillance Monitoring",
   "datasetId":"http://linked.data.gov.au/dataset/ausplots",
   "description":"<p> AusPlots is a collection of ecological data and samples gathered from a network of plots and transects across Australia by the TERN Ecosystem Surveillance team, using standardised methodologies. </p> <p>The AusPlots collection provides the ecological infrastructure to: </p> <ul><li>quantify the richness and cover of plant species (including weeds); </li><li>quantify the diversity and abundance of soil biodiversity; </li><li>assess the state, spatial heterogeneity and structural complexity of vegetation, including life-stage; </li><li>record vegetation and soil parameters that assist with the validation of remotely sensed ecological products;</li><li>analyse vegetation structure and change based on a series of photo reference images; </li><li>better estimate soil carbon and nutrient stocks; </li><li>conduct taxonomic validation studies based on collected plant voucher specimens; </li><li>conduct DNA barcoding and population genetic profiling based on collected tissue samples. </li></ul> <p> Overall this information will progress understanding of ecosystem processes, structure and function, and more generally progress understanding of the response to disturbance and longer-term environmental change of rangeland ecosystems, which underpins sustainable management practice.</p>.",
   "abstract":"N/A",
   "version":"2023-04-19",
   "created":null,
   "creator":"TERN Surveillance Monitoring ",
   "creatorId":"https://w3id.org/tern/resources/6be8678c-f354-47da-9667-46daf2a23ac7",
   "publisher":"Terrestrial Ecosystem Research Network (TERN)",
   "publisherId":"https://w3id.org/tern/resources/a083902d-d821-41be-b663-1d7cb33eea66",
   "spatial_extent_min_longitude":113.25800323486328,
   "spatial_extent_min_latitude":-42.09260177612305,
   "spatial_extent_max_longitude":152.89999389648438,
   "spatial_extent_max_latitude":-10.70300006866455
}
...
{ ... }

Datasets

Information in EcoPlots may belong to a smaller datasets, part off the main datasource (also called project). To retrieve more details about the available datasets in EcoPlots, you can use the /datasets endpoint.

Request example:

curl -X POST "https://ecoplots-test.tern.org.au/api/v1.0/datasets?dformat=ndjson" -H "accept: */*" -H "X-Api-Key: aAbBcC...xXyYzZ" -H "Content-Type: application/json" -d "{\"query\":{}}"

Response example:

Sites and SiteVisits

EcoPlots primarily contains on data collected in survey plots across Australia, hence other core information you can access is Plot/Site and SiteVisit. [Read more about Sites]

/sites and /sitevisits endpoints serve all the ecological sites (and their visits) information, including basic description of the site, latitude and longitude coordinates, establishment dates, visit dates and other useful details.

As any other endpoint from the Data category, a search query should be used in order to narrow the results. For example, a user may be only interested in sites that belong to a specific dataset, or sites within a specific geographic region across all datasets (see Search queries).

Sites

Request example:

Response example:

SiteVisits

Request example:

Response example:

Site or SiteVisit attributes

Site and SiteVisits can have additional attributes not defined in the Site and SiteVisits class as they may be dataset specific (i.e. the attribute is not shared/used across other datasets, so it is not explicitly defined in the ontology).

You can download all these attributes through the /sites/attributes and /sitevisits/attributes endpoints.

Request example:

Response example:

Observations

All ecological measurements (plant height, animal count, soil pH, air temperature) in Ecoiplots are represented as observations. [Read more about Observations]

You can use this endpoint to extract observations based on several search criteria (see Search queries).

Request example:

Response example:

Observation attributes

Observations can have additional attributes. E.g., an observation might have an attribute “angle count point name”, but not all sampling protocols record this attribute, so the property does not belong to the Observation itself and it is defined as an additional attribute.

You can download all these attributes through the /observations/attributes endpoint.

Request example:

Response example:

Feature of interest attributes

In the TERN Ontology, a Feature of Interest (FOI) is an ecological scale (e.g. plant individual, animal population, soil, climate). Observations are grouped by ecological scales (FOI) and the FOI type and feature id for each observation are returned with the observation. [Read more about Feature of Interest]

However, every instance of FOI may have additional attributes related exclusively to the instance. This information can be accessed via the /foi/attributes endpoint.

Request example:

Response example:

Instrument attributes

When an instrument was used to measure the result of an observation, the type of instrument and the instrument instance id is returned along the observation data.

However, an instance of an Instrument may have additional attributes related exclusively to the instance. This information can be accessed via the /instruments/attributes endpoint.

Request example:

Response example:

Taxon

EcoPlots stores Taxonomic information about all vegetative species collected in the various datasets. This information is sourced from Australian Plant Name Index, and it can be retrieved using the /taxon endpoint.

Request example:

Response example:

Discovery endpoints

Discover endpoint helps to retrieve all the possible values of specific variables within EcoPlots. You can easily find the desired values to be used in your queries.

You can retrieve values from:

"region_type", "region", "dataset", "site_id", "site_visit_id", "feature_type", "observed_property"

Request example:

Response example:

Following the use of this endpoint /discover/feature_type, we know that EcoPlots stores data about all items in the list of FOI returned. We can now use, for instance, the filter

to only retrieve soil information.