EcoPlots API - creating search queries

Search queries can be created manually or by building a query using the query generator within the EcoPlots portal search page.

Search queries are independent of the tools that are used for sending the query request. For example, the same query body can be used with a request written in cURL, python, postman, R, or another programming language.

Remember that all data endpoints allow filtering!

The query parameter in the request body allows the data requested from any endpoint to be filtered according to the parameters specified. For example:

retrieve only sites which contain a feature of interest (FOI), such as “plant occurrence”
retrieve only observations which contain a parameter (ie. “basal area”)

Understanding EcoPlots data queries

One of the strengths of EcoPlots is its powerful query system. 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. Within EcoPlots, this URI is actually a resolvable URL that identifies a unique concept or instance of a class.

"http://linked.data.gov.au/dataset/ausplots" is the identifier of “ausplots” in TERN Surveillance Monitoring (a single instance of the Dataset class)
"http://linked.data.gov.au/def/tern-cv/b311c0d3-4a1a-4932-a39c-f5cdc1afa611"is the identifier of “plant occurrence” (within the Concept class of the Concept Scheme “Feature types”).

The RDF data model (RDF - Semantic Web Standards (w3.org)) used in Ecoplots offers multiple benefits. Because a URI is a unique and immutable identifier for a specific concept, we can easily modify the vocabulary by changing the label, the description or any other property of the concept without having to update the data.

The only drawback to using URIs is that they are usually not human readable. However, 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.

What can be queried?

There are several different ways you can discover our vocabularies (the possible values in queries):

Inspecting the TERN vocabularies, then use the vocabulary URI of interest
Using the /discover/{field} endpoint. This endpoint returns a set of “key: value” (consisting of a label and URI) entries with all the possible values for every facet.

The filter query must be sent in the request body (content type JSON) along with any pagination parameters.

General examples

Examples of valid queries

Each of the below examples are syntactically valid ways to write a query requests for the EcoPlots API. All queries must contain a query (even though it may be empty).

"query": {
    "dataset": [
        "http://linked.data.gov.au/dataset/ausplots"
    ]
}

{
    "page_number": 1, 
    "page_size": 50, 
    "query": {
        "dataset": [
            "http://linked.data.gov.au/dataset/ausplots"
        ]
    }
}

"query": {
    "feature_type": [
        "http://linked.data.gov.au/def/tern-cv/b311c0d3-4a1a-4932-a39c-f5cdc1afa611"
    ]
}

"query": {
    "observed_property": [
        "http://linked.data.gov.au/def/tern-cv/0bbd7fcd-0782-4efc-96e6-1f0f7669c655"
    ]
}

{
    "page_number": 1,
    "page_size": 50,
    "query": {}
}
{
    "query": {}
}

Common query syntax errors

If a query includes pagination, both the page_number and the page_size parameters must be included.

Example of an invalid request.

This request is invalid due to only including the page_number. The page_number has not been defined.

{
    "page_number": 1,
    "query": {}
}

Example of an invalid request.

This request is invalid as the request body is empty. At a minimum, requests must contain a query.

{}

Example of an invalid request.

This request is invalid as the request body is empty. At a minimum, requests must contain a query.

{
    "page_number": 1,
    "page_size": 50
}

Formatting the facets of a query object

Probably need a link to the index of possible query bodies.

Notice that all values (even if it is 1 single value) must be enclosed between square brackets.

Valid query bodies

In these two examples, each value (in the first example http://linked.data.gov.au/dataset/ausplots and in the second example both http://linked.data.gov.au/dataset/ausplots and http://linked.data.gov.au/dataset/corveg) is enclosed within double quotations.

In the second example, the values are separated by a comma and both values are enclosed within square brackets [].

"dataset": [
    "http://linked.data.gov.au/dataset/ausplots"
]

"dataset": [
    "http://linked.data.gov.au/dataset/ausplots",
    "http://linked.data.gov.au/dataset/corveg"
]

Invalid query bodies

The first example is invalid as there are no enclosing square brackets [].

The second example is not technically invalid, however it will yield no results as the dataset list empty and contains no search parameter.

"dataset": "http://linked.data.gov.au/dataset/ausplots"

"dataset": []

For more information about how to create search queries, please refer to EcoPlots API - autogenerating queries and EcoPlots API - Example search queries.