NEW_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.

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.

The following examples show how to structure a query and some commonly encountered syntax problems.

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"
    ]
}

*Each of these examples is separate

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": {}
}

{
    "query": {}
}

Remember that comments within JSON invalidates the syntax. For first invalid example below, there must be a page number is there is a page size.

Invalid request bodies

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

{}

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

Available facets in the 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

"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

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

Adding an empty list is a valid request but the response will be always empty.

"dataset": []