Page Comparison

Dataqueries are different to Queries - they allow a deeper inquiry of species.The Dataqueries queries - they are specifically designed to retrieve data from EcoPlots filtering data based on specified species. 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 and are intended to facilitate efficient querying of relevant data. There are three dataqueries endpoints:

/species/count

...

/species/observations

...

/species/observed_property/list

...

On this page, 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 Create and Use API Key to Access TERN Data Services .

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`

highlight the basic URL parameters that can be used to create a dataquery.

...

`speciesname` - URL Parameter

All three of the endpoints use the “speciesname” parameter in within the URL to take find data points that include the relevent species name. Multiple species name names (full or part of species name/taxonomypartial taxonomic names) can be passed at once using multiple occurrences of “speciesname” speciesname in URL parameter. eg.

For example:

https:/{ecoplots-api-url}/ecoplots.tern.org.au/api/v1.0/species/count?speciesname=Allocasuarina torulosa&speciesname=Eucalyptus

Info
NOTE: It is

...

possible to pass only a family or genus name within a URL parameter. For example, let's say Eucalyptus is passed as the speciesname parameter, the API will return documents for all of the

...

species of

...

the

...

genus Eucalyptus.

...

`output` - URL Parameter

The output parameter is only available for the /species/count endpoint. This specifies the what output data user wants needs to getbe discovered. Its value can be either “scientificscientific_name” name or “taxon” taxon. As the same name suggests, “scientific_name” returns only the scientific name of the species, while the “taxon” returns the entire taxonomy associated with that the species . e.g. specified with speciesname.

For example:

https://{ecoplots-api-url}ecoplots.tern.org.au/api/v1.0/species/count?speciesname=Allocasuarina torulosa&output=taxon

...

`dformat` - URL Parameter

The “dformat” dformat parameter is only available for the /species/observations endpoint. This species specifies the datatype for of the return returned values, and can either be "csv” or “ndjson” which returns the data be formatted 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/TDSAG/pages/2676621402/NEW_EcoPlots+API+search+queries#Parameter-(observable-property)

...

Code Block

breakoutMode	wide
language	json

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

...

/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

Info
`output=scientific_name` is set by default

...

output = scientific_name

Code Block

language	json

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

output = taxon

Code Block

language	json

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

...

Code Block

language	json

{
  "observable_property": [
    {
      "count": 2243,
      "label": "tree alive status",
      "observed_property": "http://linked.data.gov.au/def/tern-cv/e3e69168-a959-4b8e-a1ea-2413fc3c2e4e"
    },
    {
      "count": 1664,
      "label": "scientific name",
      "observed_property": "http://linked.data.gov.au/def/tern-cv/56195246-ec5d-4050-a1c6-af786fbec715"
    },
    {
      "count": 1664,
      "label": "IUCN conservation status",
      "observed_property": "http://linked.data.gov.au/def/tern-cv/6f59a7ac-7acf-4c98-8db6-002ebd9a315f"
    }
  ],
  "status": 200
}

...

/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

Note

This endpoint uses pagination, hence the "page_number" and "page_size" are to be specified in the request body. Pagination is meant to be used as a data discovery tool (quickly returning small chunks of data).

Completeness cannot be guaranteed due to database design and implemented limits (only the first 10,000 elements of the whole subset can be retrieved).

If you desire to retrieve more than 10,000 elements, please SET the "page_size" to -1.

More details on pagenation can be found here.

Note
Setting `"page_size"` to -1 will retrieve all the data which could possibly be millions of records. Depending on size of records and quality of connection, long wait times (10s of minutes) for response is expected.

Info
In case of no `"page_number"` and/or `"page_size"` is provided. The default value, i.e, 1 and 20 for `“page_number"`and `“page_size"` respectively, will be used.

...

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

Info
`dformat=ndjson` is set by default if no dformat is specified.

dformat = ndjson

Code Block

language	json

{
    "dataset": "QBEIS",
    "datasetId": "http://linked.data.gov.au/dataset/corveg",
    "siteId": "http://linked.data.gov.au/dataset/corveg/site-4507",
    "siteName": "53_659013",
    "latitude": "-27.0876",
    "longitude": "153.429",
    "siteVisitId": "http://linked.data.gov.au/dataset/corveg/sv-4507",
    "siteVisitName": "53_659013",
    "featureType": "plant population",
    "featureTypeId": "http://linked.data.gov.au/def/tern-cv/ae71c3f6-d430-400f-a1d4-97a333b4ee02",
    "featureId": "http://linked.data.gov.au/dataset/corveg/site_visit_id-4507-speciesid-1454",
    "observationId": "http://linked.data.gov.au/dataset/corveg/tern_plant_population-obs-taxon-4507-1454",
    "parameterId": "http://linked.data.gov.au/def/tern-cv/70646576-6dc7-4bc5-a9d8-c4c366850df0",
    "parameter": "taxon",
    "result": "Allocasuarina torulosa (Aiton) L.A.S.Johnson",
    "resultUnitId": null,
    "resultTime": "1997-04-09T00:00:00"
}

dformat = csv

Code Block

language	text

dataset,datasetId,siteId,siteName,latitude,longitude,siteVisitId,siteVisitName,featureType,featureTypeId,featureId,observationId,parameterId,parameter,result,resultUnitId,resultTime
QBEIS,http://linked.data.gov.au/dataset/corveg,http://linked.data.gov.au/dataset/corveg/site-4507,53_659013,-27.0876,153.429,http://linked.data.gov.au/dataset/corveg/sv-4507,53_659013,plant population,http://linked.data.gov.au/def/tern-cv/ae71c3f6-d430-400f-a1d4-97a333b4ee02,http://linked.data.gov.au/dataset/corveg/site_visit_id-4507-speciesid-1454,http://linked.data.gov.au/dataset/corveg/tern_plant_population-obs-taxon-4507-1454,http://linked.data.gov.au/def/tern-cv/70646576-6dc7-4bc5-a9d8-c4c366850df0,taxon,Allocasuarina torulosa (Aiton) L.A.S.Johnson,,1997-04-09T00:00:00

...

csv or ndjson.

For example:

https://ecoplots.tern.org.au/api/v1.0/species/observations?speciesname=Allocasuarina torulosa&dformat=ndjson

...

In the next pages of this section, we will comprehensively cover all the essential variables that must be supplied as URL parameters and/or in the request body for each endpoint, providing users with a clear understanding of what output to anticipate from the API.

Child pages (Children Display)

Versions Compared

Old Version 2

New Version Current

Key

URL Parameters

`speciesname`

`speciesname` - URL Parameter

`output` - URL Parameter

`dformat` - URL Parameter

Request Body

Endpoints

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

URL Parameters

speciesname

speciesname - URL Parameter

output - URL Parameter

dformat - URL Parameter

Request Body

Endpoints

`speciesname`

`speciesname` - URL Parameter

`output` - URL Parameter

`dformat` - URL Parameter