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. Include a sentence explaining the counts.

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