Discovery endpoints

Discovery endpoints help to retrieve all the possible values of specific variables within EcoPlots (such as datasources, regions, parameters, FOI, etc). You can easily find the desired values to be used in your queries.

You can retrieve values from:

"region_type", "region", "dataset", "site_id", "site_visit_id", "feature_type", "observed_property"

Discovery endpoints differ from data endpoints because they will only return a set of possible values to be used in any kind of variable or facet in the query, rather than returning actual data. The returns from these endpoints will yield the possible values that can be queried. For instance, if the dataset discovery endpoint is queried, it will show that there are a number of datasets that can then be queried further: TERN surveillance, TERN EP, ausplots forest, BDBSA.

Knowing these values, user can create the search queries (e.g. give me all observation from X dataset, where X is one of the values returned by the discover endpoint).

This example Discovery request gets a list of all the filters that can be applied to further specify the desired criteria within a "feature_type" request. To request a value other than "feature_type", replace .../discover/feature_type with whatever value is of interest (ie. .../discover/region).

Request example:

curl -X GET "https://ecoplots.tern.org.au/api/v1.0/discover/feature_type" -H "accept: application/json" -H "X-Api-Key: aAbBcC...xXyYzZ"

Response excerpt:

[
  {
    "key": "soil-sample",
    "label": "soil sample",
    "uri": "http://linked.data.gov.au/def/tern-cv/06461021-a6c2-4175-9651-23653c2b9116"
  },
  {
    "key": "animal-occurrence",
    "label": "animal occurrence",
    "uri": "http://linked.data.gov.au/def/tern-cv/2361dea8-598c-4b6f-a641-2b98ff199e9e"
  },
  {
    "key": "landform",
    "label": "landform",
    "uri": "http://linked.data.gov.au/def/tern-cv/2cf3ed29-440e-4a50-9bbc-5aab30df9fcd"
  },
  {
    "key": "plant-specimen",
    "label": "plant specimen",
    "uri": "http://linked.data.gov.au/def/tern-cv/2e122e23-881c-43fa-a921-a8745f016ceb"
  },
  {
    "key": "vegetation-stratum",
    "label": "vegetation stratum",
    "uri": "http://linked.data.gov.au/def/tern-cv/32834f36-a478-45be-97f4-ff2ff51e9f5c"
  },
  {
    "key": "fungal-occurrence",
    "label": "fungal occurrence",
    "uri": "http://linked.data.gov.au/def/tern-cv/45a73139-f6bf-47b7-88d4-4b2865755545"
  },
  {
    "key": "plant-individual",
    "label": "plant individual",
    "uri": "http://linked.data.gov.au/def/tern-cv/60d7edf8-98c6-43e9-841c-e176c334d270"
  },
  {
    "key": "climate",
    "label": "climate",
    "uri": "http://linked.data.gov.au/def/tern-cv/6d40d71e-58cd-4f75-8304-40c01fe5f74c"
  },
  {
    "key": "land-surface-disturbance",
    "label": "land surface disturbance",
    "uri": "http://linked.data.gov.au/def/tern-cv/7e256d28-e686-4b6a-b64a-ac1b1a8f164d"
  },
  {
    "key": "soil-profile",
    "label": "soil profile",
    "uri": "http://linked.data.gov.au/def/tern-cv/80c39b95-0912-4267-bb66-2fa081683723"
  },
  {
    "key": "land-surface",
    "label": "land surface",
    "uri": "http://linked.data.gov.au/def/tern-cv/8282fb22-4135-415c-8ca2-317860d102fb"
  },
  {
    "key": "soil",
    "label": "soil",
    "uri": "http://linked.data.gov.au/def/tern-cv/98e8d72d-f361-41ed-af9d-6e7f90c1dfce"
  },
  {
    "key": "land-surface-substrate",
    "label": "land surface substrate",
    "uri": "http://linked.data.gov.au/def/tern-cv/aef12cd6-3826-4988-a54c-8578d3fb4c8d"
  },
  {
    "key": "geologic-substrate",
    "label": "geologic substrate",
    "uri": "http://linked.data.gov.au/def/tern-cv/afc81cca-9122-4e36-823d-31dd765e9257"
  },
  {
    "key": "plant-occurrence",
    "label": "plant occurrence",
    "uri": "http://linked.data.gov.au/def/tern-cv/b311c0d3-4a1a-4932-a39c-f5cdc1afa611"
  },
  {
    "key": "vegetation-disturbance",
    "label": "vegetation disturbance",
    "uri": "http://linked.data.gov.au/def/tern-cv/d4fc54b1-0ad3-4512-86b7-d42b121ece45"
  },
  {
    "key": "plant-community",
    "label": "plant community",
    "uri": "http://linked.data.gov.au/def/tern-cv/ea3a4c64-dac3-4660-809a-8ad5ced8997b"
  }
]

Following the use of this endpoint /discover/feature_type, we know that EcoPlots stores data about all items in the list of FOI returned. We can now use, for instance, the filter

"feature_type": ["http://linked.data.gov.au/def/tern-cv/98e8d72d-f361-41ed-af9d-6e7f90c1dfce"]

to only retrieve soil information.