The API key is used to connect to TERN API endpoints from the user’s custom applications (or by using simple tools such as Curl, or WGET, or any of the TERN API Swagger Dashboards) to get/download TERN data the user is interested in. All requests made from custom applications mustinclude the API key in the Authorization section of the header of each request.
To generate an API Key, please visit the TERN Account portal at (https://account.tern.org.au) and Sign In. After Sign In, follow the steps below (see figure 1 and figure 2):
In the menu on the left, click Create API key menu link (1)
Enter the name of the API key in the API key name field (can be arbitrary, for your records - but it's mandatory) (2)
Click the button Request API Key (3)
Copy the generated API key in the API key field (4)
After generating the API key, copy the key and store it in a secure place (Note: The API key is only displayed once in the API Key Information page [see figure 2 above] - and will not be shown or accessible after this - for security reasons). if you lose the API Key you need to generate new key.
How to use the API Key
The following sections present examples of how the API Key can be used to connect to any TERN portal to build your own applications (or scripts) to obtain the information you are interested in. (Furthermore, the examples given here are using the TERN EcoImages portal as an example portal in which a user could connect. However, the processes can be applied similarly to any TERN portal which has its API exposed to the public - see list of TERN Rest APIs here).
1. Using API Swagger Dashboard
For TERN portals that expose public APIs, Swagger API Dashboards that list all the available API methods are available to the user (see the list here). As an example here, we will use the TERN EcoImages portal using the EcoImages API Swagger Dashboard to list the packages the user has downloaded.
First generate the API key (as outlined in the section above, namely, How to get a TERN API Key). Then follow the following steps.
The output should be similar to what is shown in figure 7:
This step shows that you are able toreach the endpoint /api/whoami in the TERN EcoImages portal and that your API key is valid (because this endpoint requires a valid API key to allow you to retrieve your details). Subsequently, this means you can also use other publicly available endpoints from the TERN portals using the supplied API key.
1.2 Curl with Basic authentication type
In the terminal type in: curl --user <apikey>:<password> <tern application endpoint>. Make sure that the <password> is blank! (e.g. curl --user FAKEAPIKEY123: https://ecoimages.tern.org.au/api/v1.0/packages)
Figures 8 and 9 below demonstrate how you can retrieve a list of the packages you have downloaded from the TERN EcoImages Portal using curl with a basic authentication type method. Figure 8 is the curl command. Figure 9 is the JSON result of the packages.
(Hint: If you have installed the jq command-line tool, you can pipe the output to format the response JSON string nicely [pretty print], as figure 8 below shows!)
3. Using Wget command-line tool
Wget is another tool you can use to connect to TERN portal REST APIs to access data. The following is an example of how you can use Wget to download acoustic data from TERN (e.g. download acoustic data from the Calperum site and sensor Calperum01 for the 2013 period):
The data from this period is about 118G, so it might take a while to download - nevertheless it gives an indication of what you can download).
--mirror: instruct wget to follow links and download every link encountered on the same site --np: don’t follow links into parent directories --e robotos=off: wget mirroring follows instructions in robots.txt file. this option tells wget to ignore it
3.2 The data will be downloaded to the folder data.tern.org.au.
4. Using a Python Script
The same results can be achieved as in the above examples using a python script (or a full-blown python, Django, or React application). The following is an example of a small python script to retrieve your details using the endpoint /api/whoami in the EcoImages portal:
In the above examples, we have used the query parameters page_size=1&page_num=1 to return only one package. However, in your applications, you can use other values to return more packages and paginate based on the requirements of your application. The key idea here is to demonstrate that you can build your own applications as long as you have obtained a valid API key from TERN and include that key in the header of every request you make to a TERN service.
For more EcoImages Portal public API endpoints (which have been used in the above demonstrations), please refer to EcoImages production API dashboard https://ecoimages.tern.org.au/api/v1.0/ui#/ . From the endpoints listed in the API Dashboard, you can build your own extensive applications.