Tutorial#
Note: You will need to register your email address at the atlas you want to download data for, otherwise you will get no data!
Now that you have successfully installed galah-python, we’ll provide a quick introduction on the functions you will
mainly be using to get data. If you’re looking for a quick reference guide for commands, the
User Guide collates all the available commands with examples.
This tutorial serves as an initial method to get you used to using different commands.
Configuring galah#
First, you will need to set some stored parameters to get full use out of the galah package. There are two
key parameters that you will need to set, especially to get occurrences: atlas and email.
Choosing an Atlas
First, you will need to choose an atlas to get information from. If you’re not sure what atlases galah-python
has on offer, run the command
>> import galah
>> galah.show_all(atlases=True)
and a list like this will appear:
atlas institution acronym url
0 Australia Atlas of Living Australia ALA https://www.ala.org.au
1 Austria Biodiversitäts-Atlas Österreich BAO https://biodiversityatlas.at
2 Brazil Sistemas de Informações sobre a Biodiversidade Brasileira SiBBr https://sibbr.gov.br
3 Flanders Vlaams Biodiversiteitsportaal VBP https://natuurdata.inbo.be
4 Global Global Biodiversity Information Facility GBIF https://gbif.org
5 Kew Kew Data Portal KDP https://data.kew.org
6 Spain GBIF Spain GBIF.es https://www.gbif.es
7 Sweden Swedish Biodiversity Data Infrastructure SDBI https://biodiversitydata.se
8 United Kingdom National Biodiversity Network NBN https://nbn.org.uk
To choose an atlas, select the region that the atlas represents. By default, the atlas is set to Australia, which is
what we will sue for this example. However, for those interested in the other atlases on offer, say the Brazilian atlas,
type
>>> galah.galah_config(atlas="Brazil")
Storing Your Email
To download data from the atlases, you will need a registered email address. For the ALA, go to https://auth.ala.org.au/userdetails/registration/createAccount.
Once you have registered your email, you can store it in galah like so:
>>> import galah
>>> galah.galah_config(email="youremail@example.com")
atlas in galah_config: None
atlas in galah_config again: None
This will not return anything. No error messages means it is configured correctly. To see what your configuation settings are, type
>>> galah.galah_config()
atlas in galah_config: None
atlas in galah_config again: None
Configuration Value
0 email amanda.buyan@csiro.au
1 email_notify False
2 atlas Australia
3 data_profile ALA
4 ranks all
5 reason 10
6 verbose False
7 timeout 600
8 usernamegbif
9 passwordgbif
10 authenticate False
11 client_id
12 client_secret
13 access_token
14 refresh_token
15 scopes
16 expires_at
17 qgis False
Building queries#
Now that galah is configured, we will get counts of records, so you know how many you are downloading. To see how
many records are currently in the ALA, type
>>> galah.atlas_counts()
atlas in galah_config: None
atlas in galah_config again: None
[19]
totalRecords
0 185090015
If you are not interested in a specific species, but in the number of records in the atlas from the year 2020 onwards, you can
add this to the filters argument of atlas_counts().
>>> galah.atlas_counts(filters="year>=2020")
[19]
totalRecords
0 68586328
If you are wondering how the number of records for all species in the ALA changed over each year from 2020 onwards, you can
tell galah to group your results by year, to get yearly counts.
>>> galah.atlas_counts(filters="year>=2020",group_by="year")
[19]
year count
0 2020 8188386
1 2021 9717209
2 2022 10636634
3 2023 12542573
4 2024 13633019
5 2025 10815812
6 2026 3052695
To narrow down your search by a specific species, you can use the search_taxa() function to check whether or not the
taxonomic information for the species you are wanting to search. For this example, lLet’s choose the taxa Vulpes vulpes,
or the red fox.
>>> galah.search_taxa(taxa="Vulpes vulpes")
[17]
scientificName scientificNameAuthorship taxonConceptID rank matchType kingdom phylum classs order family genus species issues vernacularName
0 Vulpes vulpes Linnaeus, 1758 https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 species exactMatch Animalia Chordata Mammalia Carnivora Canidae Vulpes Vulpes vulpes [noIssue] Fox
Now that we can see we indeed have the red fox, we can see how many records the ALA has of the red fox.
>>> import galah
>>> galah.atlas_counts(taxa="Vulpes vulpes")
[19]
[17]
totalRecords
0 170791
Now, we can put our filters query together with our red fox query, to see how many occurrences of red foxes in the ALA
were seen each year from 2020 onwards.
>>> import galah
>>> galah.atlas_counts(taxa="Vulpes vulpes",filters="year>=2020",group_by="year")
[19]
[17]
year count
0 2020 6977
1 2021 8746
2 2022 9438
3 2023 10535
4 2024 10289
5 2025 11091
6 2026 2559
Downloading records#
Now that we know the number of red fox occurrences in each year starting with 2020, we will now download these records.
To do this, we will take the query from above and change the function name from atlas_counts() to atlas_occurrences().
>>> import galah
>>> galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year>=2020")
[23]
[17]
recordID scientificName taxonConceptID decimalLatitude decimalLongitude eventDate dataResourceName occurrenceStatus
0 0000b436-0613-4991-839a-14b57e573bc9 Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -34.892754 138.557344 2023-12-07T00:00:00Z FeralScan PRESENT
1 00010cc2-5f23-47fb-b153-ba00890dbe11 Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -37.638530 145.200730 2022-11-03T00:00:00Z Victorian Biodiversity Atlas PRESENT
2 00010f5d-f8fd-4546-be65-3a1c954e85aa Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -34.194160 139.634240 2023-03-26T00:00:00Z SA Fauna PRESENT
3 0001d2c1-5044-4a0a-bc51-315e99144286 Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -37.388868 144.267693 2025-11-19T23:58:00Z iNaturalist Australia PRESENT
4 00022581-7451-492f-87ab-ac3e4fd6484f Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -33.814819 151.297418 2020-07-05T00:00:00Z NSW BioNet Atlas PRESENT
... ... ... ... ... ... ... ... ...
59630 fff87988-89de-4533-837c-61f6cf8a82e6 Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -37.388981 144.266958 2023-01-05T15:16:00Z iNaturalist Australia PRESENT
59631 fff9da02-92bd-4268-80e3-9db8b042fb8c Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -33.852635 151.076607 2021-09-15T00:00:00Z NSW BioNet Atlas PRESENT
59632 fffa62de-d3b9-4af0-b64b-debae0165fc5 Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -27.436579 152.996672 2025-11-27T21:58:43Z iNaturalist Australia PRESENT
59633 fffc35aa-9e55-40ba-a888-f68177c0ff9d Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -37.902693 144.727749 2026-02-08T00:00:00Z FeralScan PRESENT
59634 fffecf5e-1e7f-47d9-b9d8-ab08ec59934f Vulpes vulpes https://biodiversity.org.au/afd/taxa/2869ce8a-8212-46c2-8327-dfb7fabb8296 -35.351889 138.438865 2025-03-24T11:27:00Z iNaturalist Australia PRESENT
[59635 rows x 8 columns]
If you are only interested in the scientific name, as well as latitude and longitude, use the fields option as follows:
import galah
galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year>=2020",fields=["scientificName","decimalLatitude","decimalLongitude"])
[23]
[17]
scientificName decimalLatitude decimalLongitude
0 Vulpes vulpes -34.191000 139.636000
1 Vulpes vulpes -37.389000 144.267300
2 Vulpes vulpes -37.167160 144.039838
3 Vulpes vulpes -37.279840 142.622530
4 Vulpes vulpes -37.085990 145.568900
... ... ... ...
59630 Vulpes vulpes -38.125588 147.070659
59631 Vulpes vulpes -34.473932 150.433184
59632 Vulpes vulpes -26.298146 152.819393
59633 Vulpes vulpes -32.844006 151.325928
59634 Vulpes vulpes -34.201959 142.596441
[59635 rows x 3 columns]
Check out other vignettes and the API docs for more information on how to use each of these functions, as well as to learn more about searching for information on how to filter your data.