...
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):
Steps
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)
...
Figure 1
...
Figure 2
| Info |
|---|
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. |
...
First generate the API key (as outlined in the section above, namely, How to get a TERN API Key). Then follow the following steps.
Steps
Using your internet browser, navigate to the TERN EcoImages API Swagger Dashboard. (See figure 1 for the landing page of the API dashboard). Click on Authorize
...
Figure 3
2. In the ApiKeyAuth (apiKey) authentication section, paste your API Key in the Value field (2a). Click on Authorize button (2b). Then click on Close (2c)
...
1.1 Curl with API Key authentication type
In your computer, open the terminal then type in: curl -H 'Authorization: apikey-v1 <apikey>' https://ecoimages.tern.org.au/api/whoami (e.g. curl -H 'Authorization: apikey-v1 fakebmRSFNPXSF5aiI7OjpUM1s6eiANQmgyKF8NJjRpZFJqSGMlPWlRVQlGKndoUzI4JXhkVSY/b2IL' https://ecoimages.tern.org.au/api/whoami
The output should be similar to what is shown in figure 7:
...
Figure 7
This step shows that you are able to reach 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.
...
Figure 8
(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.2 The data will be downloaded to the folder data.tern.org.au.
4. Using ffmpeg
ffmpeg is the swiss army knife to work with audio and video data. It also works well with our acoustic data.
The following example extracts 30 seconds of audio data (starting from a specific offset), re-samples the audio to 22kHz and stores the result as WAV file. Total download for this example is about 600kb.
| Code Block |
|---|
# setup auth for ffmpeg
APIKEY="your api key here"
AUTH=$(echo "apikey:$APIKEY" | base64)
ffmpeg \
-ss 00:00:30 -t 00:00:30 \
-multiple_requests 1 -seekable 1 \
-headers "Authorization: Basic $AUTH" \
-i "https://data-test.tern.org.au:443/ecoacoustics/CapeTribulation/CapeTribulation01/audio_files/2018/01/capetrib-FNQ2-DRO_20180101_034910.flac" \
-af aresample=resampler=soxr \
-ar 22000 \
-o test.wav |
5. 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:
...