EcoPlots API - dataqueries request endpoints

Similar to the other types of EcoPlots API endpoints, requests can be used with a request written in cURL, python, postman, R, or another programming language.

The "status": 200 message at the end of the response body means that the search has run successfully.

Please note that /species/observations does not return the "status": 200 message upon success.

Endpoints

Endpoint and Description

URI Example

Example Response Body excerpts

/species/count

Method: POST

Outputs: scientific_name (default) or taxon

Format: As no format has been specified in this example, results will be displayed as NDJSON. Results can be output from the API as ndjson or csv. dformat=ndjson is set by default if no dformat is specified.

Response: Returns a list with all the unique species' names (output=scientific_name) or the complete taxonomy (output=taxon) and counts of related documents in the database for the specified species. The count reflects the number of occurrences of a species appearing in the database (and each occurrence may have many related observations).

To reveal these results, this dataqueries API endpoint automatically applies 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

https://ecoplots.tern.org.au/api/v1.0/species/count?speciesname=eucalyptus&speciesname=acacia?output=scientific_name

output=scientific_name and output=taxon both give the same outputs in the tests that I have run. I can get first example output for scientific_name, but not the second for taxon.

Additionally, if only one speciesname is used (ie. speciesname=acacia) it returns an empty results container.

output=scientific_name

{
  "species": [
    ...
    {
      "count": 6072,
      "speciesname": "eucalyptus crebra"
    },
    ...
    { ... }
  ],
  "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

Format: As no format has been specified in this example, results will be displayed as NDJSON. Results can be output from the API as ndjson or csv. dformat=ndjson is set by default if no dformat is specified.

Response: Will retrieve a list of all the unique observed properties or parameters and their counts. The count refers to the number of occurrences of the species that have that specific observed property.

Results 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

https://ecoplots.tern.org.au/api/v1.0/species/observed_property/list?speciesname=eucalyptus

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

Format: Results can be output from the API as ndjson or csv. In this example, dformat=csv has been used so that the results are formatted as comma seperated values. dformat=ndjson is set by default if no dformat is specified.

Response: Returns a list of all the individual observations made from the specified list of species.

The following filters are applied:

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

Unique features:

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). The default values of 1 and 20 for “page_number"and “page_size" respectively are used if nothing is specified.

Visit EcoPlots API- paginating results for more details on pagination.

https://ecoplots.tern.org.au/api/v1.0/species/observations?speciesname=eucalyptus&dformat=csv

dformat = csv

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

dformat = ndjson

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