EcoPlots API - Dataqueries Endpoints User Manual

The Dataqueries endpoints are an integral part of EcoPlots API V5, specifically designed to retrieve data from EcoPlots based on specified species. These endpoints, namely /species/count, /species/observations, and /species/observed_property/list, are intended to facilitate efficient querying of relevant data. In this manual, we will comprehensively cover all the essential variables that must be supplied as URL parameters and/or request body for each endpoint, providing users with a clear understanding of what to anticipate from the API.

Before we begin, please note that API key from TERN account will be required to make any request from the API. This is similar to any other endpoint from previous versions of EcoPlots API. More details on how to use the API key can be found here https://ternaus.atlassian.net/wiki/spaces/TERNSup/pages/2353496065 .

NOTE: In case, if you are using the test instance of API (https://ecoplots-test.tern.org.au), make sure to generate the API key from TERN test account.

URL Parameters

`speciesname`

All three of the endpoints use the “speciesname” parameter in URL to take species name. Multiple species name (full or part of species name/taxonomy) can be passed at once using multiple occurrences of “speciesname” in URL parameter. eg. https:/{ecoplots-api-url}/api/v1.0/species/count?speciesname=Allocasuarina torulosa&speciesname=Eucalyptus

NOTE: It is not required the pass the full name of species. For example, let's say Eucalyptus is passed as speciesname, the API will return documents for all of the sub species of Eucalyptus. Similarly, if a family or genus name is passed, API will return for all the species under that family/genus.

`output`

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

`dformat`

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

Request Body

The request body for all the Dataqueries endpoint has “query” field under which values of facets for filtering can be plugged in. While the “query” field is common for all the endpoints, the /species/observations has two more fields namely, "page_number” and “page_size”.

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.

"dataset": ["dataset-url-1", "dataset-url-2", ...]
“date_from": "2020-01-01"
“date_to": "2023-05-09"
“exact_match": false
In comparison to the EcoPlots API search query, the only added field in the request body is related to the "query" parameter. This parameter provides users with the flexibility to choose between a full-text search or tokenised word search for a given species name across all the records stored in the database. For example, when the "exact_match" is set to true and the given speciesname is Allocasuarina torulosa. The API will be returning only the documents containing exact species name while setting it to false will result in documents that has either Allocasuarina or torulosa or full Allocasuarina torulosa.
“feature_type": ["feature-type-url-1", "feature-type-url-2", ...]
“observed_property": ["observed-property-url-1", ...]
“region": ["region-url-1", "region-url-2", ...]
“site_id": ["site-id-url-1", "site-id-url-2", ...]
“spatial": { }

NOTE: Except for "exact_match" field, everything else is similar to EcoPlots API Search Query. More details about it can be found here -> https://ternaus.atlassian.net/wiki/spaces/TERNSup/pages/2393047118/EcoPlots+API+search+queries#Parameter-(observable-property)

Below is an example of mock request body. Please note that for endpoints other than /species/observations, "page_number" and "page_size" is NOT required.

{
    "page_number": 1,
    "page_size": 25,
    "query": {
        "dataset": [
            "http://linked.data.gov.au/dataset/ausplots",
            "http://linked.data.gov.au/dataset/corveg"
        ],
        "date_from": "2006-01-01",
        "date_to": "2021-07-30",
        "exact_match": true,
        "feature_type": [
            "http://linked.data.gov.au/def/tern-cv/2cf3ed29-440e-4a50-9bbc-5aab30df9fcd"
        ],
        "observed_property": [
            "http://linked.data.gov.au/def/tern-cv/83ac0278-51cd-4d1a-8e05-7c1fc68cf020"
        ],
        "region": [
            "http://linked.data.gov.au/dataset/asgs2016/stateorterritory/6",
            "http://linked.data.gov.au/dataset/bioregion/CYP"
        ],
        "site_id": [
            "http://linked.data.gov.au/dataset/ausplots/site-nsabbs0001"
        ],
        "spatial": {
            "type" : "Polygon",
            "coordinates" : [
                [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
            ]
        }
    }
}

Endpoints

Endpoint	Description	URI Example	Example Response 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

output = scientific_name

{
  "species": [
    {
      "count": 1236,
      "speciesname": "Allocasuarina torulosa"
    }
  ],
  "status": 200
}

output = taxon

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

/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

/species/observations?speciesname=eucalyptus&dformat=csv

dformat = ndjson

dformat = csv