TERN Discovery Portal API Design Document

The API presents a simple interface based on the Opensearch standard. It’s a REST API that returns search results for HTTP queries. It supports for simple, list-based result formats makes the service suitable for AJAX style integration into web application.

The results are returned in JSON format. Alternate result formats such as Atom can be added in the future.

Endpoint

The base URL and service endpoint for the TERN Data Discovery Portal API is

http://portal-dev.tern.org.au/api_tern

Requested Format
http://portal-dev.tern.org.au/api_tern?keyword={KEYWORD}&count={COUNT}

It currently only support searches based on keyword, temporal, license, FoR, facility and states region. for example

http://portal-dev.tern.org.au/api_tern?keyword=koala&count=10

returns first 10 records that contain “koala” across all metadata fields

Result formats

Results are returned in JSON format. If no results found, the returned JSON object will be empty. 

Error
Errors are returned as JSON format like below

{"error":"Error occured"}

Use Cases:

1. search by keyword
   The example below returns first 15 records with koala in any of its metadata fields. If count parameter is not supplied, it iwll be set to 10 by default.
   http://portal-dev.tern.or.au/api_tern?keyword=koala&count=15
   
   
2. search by temporal
   The example below returns first 15 records with 'dated_from' before 2001 and 'dated_to' after 2005 
   http://portal-dev.tern.or.au/api_tern?temporal=2001-2005&count=15
   
   
3. search by FoR values
   The example below returns first 15 records which contains word 'environment' in their FoR values.
   http://portal-dev.tern.org.au/api_tern?for=environment&count=15
   
   

4. search by abbreviated facility name
   The exple below returns the first 15 records which belongs to Ozflux facility. 
   http://portal-dev.tern.org.au/api_tern?facility=ozflux
   The accepted values for the 'facility' parameter by each facility are as follow:

   Facility name	Accepted values
   Long-term ecological research network	ltern
   Advanced Ecological Knowledge and Observation System	ecoinformatics, aekos
   Australian Coastal Ecosystem Facility	acef,coastal
   ACEAS	aceas
   AusCover	auscover
   Australian Supersite Network	supersite, supersites
   Ozflux	ozflux
   National Computational Infrastructure	emast, nci
   Commonwealth Scientific and Industrial Research Organisation	soils,csiro,csiro_soils

   
   

5. search by license name
   The example below returns the first 15 records which has their license type "CC-BY". This api query is not a wildcard query so it will only return records with exact match in their license type.
   http://portal-dev.tern.org.au/api_tern?license=cc-by&count=15
   
   

6. search by topic. for example: http://portal-dev.tern.org.au/api_tern?topic=vegetation this query returns results by topic names

   Topic	Accepted values
   Plants and animals	plants_and_animal
   Vegetation	vegetation
   Terrestrial Ecosystems	terrestrial_ecosystems
   Ecological Dynamics	ecological_dynamics
   Fresh Water and Estuarine	fresh_water_and_estuarine
   Land surface and Soils	land_surface_and_soils
   Agriculture	agriculture
   Oceans and Coasts	oceans_and_coasts
   Climate	climate
   Human Nature Interactions	human_nature_interactions
   Energy Water and Gas Exchange	energy_water_and_gas_exchange

7. search by abbreviated states name
   This example returns first 20 records in a given Australian state. 
   http://portal-dev.tern.org.au/api_tern?state=qld&count=20
   The accepted values for the 'region' parameter are listed below

   State	Accepted values
   New South Wales	nsw
   Queensland	qld,queensland
   Victoria	vic, victoria
   South Australia	sa
   Western Australia	wa,
   Nothern Territory	nt
   Australian Capital Territory	act
   Tasmania	tas, tasmania