Ecoplots API Query Dashboard

This section will cover the EcoPlots API Dashboard (EcoPlots API Query Dashboard) and will run through examples of how to use the dashboard to extract and visualise data.

The API Dashboard is another way that users can query data stored within EcoPlots using an API. The dashboard provides a lightweight interface for EcoPlots APIs to query datasets hosted on the EcoPlots Platform. The interface offers standard pre-defined query patterns to retrieve data from multiple data sources based on simple selection criteria. Users can use this dashboard to construct queries and get a code snippet to access data in any programming language. The interface provides sample data for a constructed query. Hence, users must use generated code snippets to retrieve the complete dataset for any constructed query. Alternatively, users can use the EcoPlots search dashboard to perform more detailed search and download data.

To navigate to the dashboard, go to the EcoPlots home page (https://ecoplots.tern.org.au/) and click on the tab in the menu bar and select the API Query Dashboard. For more information and detailed instructions on using the API Query Dashboard, you can select the button, which will generate the following screen:

Now we can go through the steps of selecting and extracting data. User can query the data by either “Dataset” or “Region” (as seen below).

Once a selection has been made, you can use additional search parameters: Datasource, Feature Type, Survey sites and Observable properties to narrow down the results.

In the below example, we are using the “Dataset” query endpoint and have selected the TERN Ecosystem Processes datasource. For this basic example, we are interested in extracting all observable properties involving above-ground biomass, stem diameter, stem height and species' scientific names.

Once the search parameters have been selected, click on the button and the following screen will be displayed.

Here we can either select the data format (either CSV or GeoJson) . In this example, we have selected the CSV option. In the grey “search body” section, we can see the query results showing the respective URLs of the “dataset” and the observable properties (above-ground biomass, stem diameter, stem height and species' scientific names.

To access the data, there are two methods: 1) select the API button or 2) select the Execute Data Query button . The choice of which method to use will depend on the amount of resulting observations from the data query which we will go over in the examples below.

If the query produces large amounts of data (>10,000 observations/rows), the best way to extract the data is using the the code snippet produced after selecting the API button . Here we see that a code generator appears with the dataset and observable properties and the user has the option to customise the programming language, variant and output format.

In this example , we have selected the programming language R, CSV output and httr variant. Now we can copy the code snippet by pressing the copy snippet button. In R studio, we can paste this snippet.

It is important to note that you will need to enter your own individual API-key into the code. All API endpoints need a system generated API Key to access and retrieve data. Users can create API Key by visiting their TERN Account.

library(httr)

## you will need to enter your own individaul API key ##
headers = c(
  'X-Api-Key' = 'your-api-key',
  'Content-Type' = 'application/json'
)

body = '{
  "query": {
    "dataset": [
      "http://linked.data.gov.au/dataset/tern-ecosystem-processes"
    ],
    "observed_property": [
      "http://linked.data.gov.au/def/tern-cv/56195246-ec5d-4050-a1c6-af786fbec715",
      "http://linked.data.gov.au/def/tern-cv/5701d307-bbea-415a-8857-fbf27d5b93ed",
      "http://linked.data.gov.au/def/tern-cv/c3d26c6f-91b7-4627-91e6-2147fa44ad03",
      "http://linked.data.gov.au/def/tern-cv/c3111898-8404-4306-9599-e7866a749de7"
    ]
  }
}';

res <- VERB("POST", url = "https://ecoplots.tern.org.au/api/v1.0/data/tern-ecosystem-processes?dformat=csv", body = body, add_headers(headers))

## "cat" converts arguments to character strings, concatenates them, separating them by the given sep= string.
cat(content(res, 'text'))

Once this code has been run, we can now create a dataset and inspect the output.

## create dataframe called "biomass_DF"
biomass_DF <- read.table(text = content(res, 'text'), sep =",", header = TRUE, stringsAsFactors = FALSE)

## explore dataframe
head(biomass_DF)

We now have a dataframe that we can work with that contains The output below show that site information, date of surveys, scientific names of plant species, stem diameter and height, above ground biomass and links to the methods used to obtain these values.

Another option for when the data queried is <10,000 observations, is to select the Execute Data Query button . In the below example, we will use the same dataset, yet only select the above ground biomass observable property.

After selecting the button, we are presented with the data in a text output.

We can inspect the data by pressing the view button

Now we can copy the data by pressing the copy button and paste directly into an excel spreadsheet:

To convert the text to columns, following these steps:

Highlight the column that contains your list.
Go to Data > Text to Columns.
Choose Delimited. Click Next.
Choose Comma. Click Next.
Choose General or Text, whichever you prefer.
Leave Destination as is, or choose another column. Click Finish.