|Jump to section:|
We provide access to our data via a set of REST APIs documented on Swagger. You can find the list of published APIs and relevant Swagger documentation at docs.ala.org.au*.
You can use these APIs in your work to access our open-source data more easily and feed into downstream analyses using your own system. You may also wish to combine the data with information from other domains in novel ways.
Most of our APIs use REST conventions and support JSON as a data format.
Our data are open and freely accessible. This means that most of our APIs do not require authentication and can be accessed freely as documented in the relevant Swagger specifications found at docs.ala.org.au.
For the protected APIs (such as sensitive or private data), you’ll need a JSON Web Token (JWT), which can be generated via a Client ID and Client Secret – to request these details, visit tokens.ala.org.au.
*Please note, this portal is still quite new, so we've retained the previous portal at https://api-legacy.ala.org.au/.
Examples of ALA APIs
1. Explore our species information (using autocomplete search)
It can be interesting to look for species with similar names, but that are very different and widely placed in the tree of life! Let’s look for species with ‘green tree’ in their name. Note, the default maximum result is 10. We've left that as is for now.
curl -X 'GET' \ 'https://api.ala.org.au/species/search/auto?q=green%20tree&idxType=TAXON&limit=10' \ -H 'accept: */*'
Results will appear like this (we’ve used Postman):
We can visualise this a bit better, here we’ve used JSON Crack to tidy up the results:
We can see that 10 species have been returned, these are (by common name):
- Coastal Aspen / Green Tree
- Mallee Teatree
- Green-Eyed Tree Frog
- Green Treehopper
- A-Gurninymiyah / Green Tree Snake
- Ngayrrngayrr / Green Tree Frog
- Green Tree Ant
- Cascade Treefrog
- Leaf-Green Tree Frog
- Narrow Fringed Frog
2. Find an image's link and attribution information (using image details)
Now let’s say you’ve browsed through the available images for a species, and found several images you’d like to use in your work. Rather than manually type out each image's attribution details, here's how to get the URL to link to the image, plus the information needed to give attribution to the creator.
For example, for this photo of a Leaf-green Tree Frog (Litoria phyllochroa):
Leaf-green Tree Frog (Litoria phyllochroa). Photo: Nathan Ruser (CC-BY)
Once you have the image ID, you can use the following API, shown with the image ID included:
curl -X 'GET' \ 'https://api.ala.org.au/images/image/details?id=208f80fd-da53-4569-8fcc-21798e3d9cb6' \ -H 'accept: application/json'
Don't forget the accept: application/json here. Postman or similar applications are handy for this.
Results will appear like this:
Again, we can visualise the results. We’ve added arrows to point out the image URL on line 10 and attribution license details from line 27:
We can see from line 27 that this license is CC-BY 4.0 – meaning attribution of the creator is required. This means you'll need the creator's name (line 25), license acronym (line 28) as well as a link to the license (line 30).
(For more information about licenses and what to include for each, see https://creativecommons.org/licenses/)
Now that you have the image link and attribution information, you can include it in your downstream work.