Welcome to TERN Knowledge Base
EcoPlots API search queries
All Data endpoints allow filtering using the query parameter in the request body. E.g. you can:
Retrieve only sites which contain a feature of interest (FOI) = “plant occurrence”
Retrieve only observations which contain a parameter = “basal area”
Data query
One of the strengths of EcoPlots is how powerful the query system is. Data are stored as atomic elements (observations) allowing to filter by 0 to many facets.
Before the user starts to define queries, it is important to understand how the underlying system has been built. Values for every search category store a URI (Uniform Resource Identifier), instead of any human-readable value. In EcoPlots case, this URI is actually a resolvable URL identifying a unique concept or instance of a class.
"http://linked.data.gov.au/dataset/ausplots"is the identifier of 1 instance of the class Dataset, in the example, TERN Surveillance Monitoring.
"http://linked.data.gov.au/def/tern-cv/b311c0d3-4a1a-4932-a39c-f5cdc1afa611"is the identifier of the class Concept, in the example, the Concept “plant occurrence” that belongs to the Concept Scheme “Feature types”.
This design offers multiple benefits (e.g., a URI is a unique and immutable identifier for a specific concept, we can easily modify the vocabulary changing the label, the description or any other property of the concept without having to update the data). The only drawback is that URIs are usually not human readable.
Query example:
"query": {
"dataset": [
"http://linked.data.gov.au/dataset/ausplots"
],
"feature_type": [
"http://linked.data.gov.au/def/tern-cv/b311c0d3-4a1a-4932-a39c-f5cdc1afa611"
],
"observed_property": [
"http://linked.data.gov.au/def/tern-cv/0bbd7fcd-0782-4efc-96e6-1f0f7669c655"
]
}All our URIs are resolvable using the HTTP protocol, meaning that you can paste the URI into your browser and retrieve all the details of the element.
There are different ways you can discover our vocabularies (i.e., possible values in queries):
Inspecting the TERN vocabularies, and using the vocabulary URI.
Using the
/discover/{field}endpoint. This endpoint returns a set of key (label) - value (uri) entries with all the possible values for every facet.Using the Ecoplots Portal as a data discovery tool. Then copy the used query and use it in your API request.
The filter query must be sent in the request body (content type JSON) along with the pagination parameters, it desired.
Valid request bodies
{
"page_number": 1, # optional
"page_size": 50, # optional
"query": { # mandatory, but query can be empty
"dataset": [
"http://linked.data.gov.au/dataset/ausplots"
]
}
}{
"page_number": 1,
"page_size": 50,
"query": {}
}
Invalid request bodies
Available facets in the query object
Notice that all values (even if it is 1 single value) must be enclosed between square brackets.
Adding an empty list is a valid request but the response will be always empty.
Region
Filter data whose site is located within a specific region.
Example 1 - Data collected in the Bioregion Cape York Peninsula
Example 2 - Data collected in the Queensland state
Example 3 - Data collected either in Tasmania or in Cape York Peninsula
Dataset
Filter data by dataset.
Example - Data from “Tern Surveillance Monitoring” or “Williams Wet Tropics Vertebrates”
Site
Retrieve data from 1 or more ecological monitoring sites.
Example - Retrieve all the data from Tern Surveillance Monitoring site nsabbs0001
Site Visit
Retrieve data from 1 or more ecological monitoring sites.
Example - Retrieve all the data from Tern Surveillance Monitoring sitevisit 58580
Feature type (feature of interest)
EcoPlots observations are categorised in Feature of Interest (FOI). Please see the FOI vocabularies for more detail.
Example - Retrieve all the data from Landform feature of interest
Parameter (observable property)
Each observation in EcoPlots is measuring an observable property (or parameter). Please see the Parameter vocabularies for more detail.
Example - Get all the data from Crown cover parameter.
Temporal extent (date)
In addition to all the vocabularised facets, you can filter data based on a temporal resolution.
Spatial extent
Statial queries in EcoPlots allows three different formats: GeoJSON, Well-Known Text (WKT) and Bounding Box. The spatial query will do an “intersect” between the given geometry and the geometry of the data.
Pagination
The EcoPlots API allows users to paginate their data request in order to retrieve small chunks of data at a time. This is great to discover the data, to inspect the shape of the response and to adjust the desired query to narrow the result subset.
In order to control the amount of computational resources needed to paginate over millions of elements, a limit of 10,000 has been established. This means that even if the count of the query (i.e., the total amount of elements) is greater than 10,000, you will be only able to paginate over and retrieve the first 10,000.
Once the query has been defined, you can remove pagination to retrieve the full set of elements.
Adding pagination to your request is as easy as include the “page_number” and “page_size” parameters to the request body.
Response headers are returned with information about the pagination:
Request example:
Using Ecoplots portal to auto-generate queries
The easiest method to create valid queries to be used in the API requests is building the query visually and dynamically through the EcoPlots Portal.
You can play around with the faceted search that the portal provides and inspect the results in the data table. Once your search has been refined, you can access the query (shown below) and use it in the API request.
Define the filter via the facets menu.
Inspect the returned data. Polish your query changing the filter values dynamically and clicking in the “Show results” button.
Click on the API button.
Copy the query dictionary using the copy button and use it directly in any API request.
Provide your feedback about the experience with Knowledge base