API Docs#

galah.atlas_counts(taxa=None, scientific_name=None, filters=None, group_by=None, total_group_by=False, use_data_profile=False, polygon=None, bbox=None, simplify_polygon=False, tolerance=0.05, config_file=None)#

Prior to downloading data, it is often valuable to have some estimate of how many records are available, both for deciding if the query is feasible, and for estimating how long it will take to download. Alternatively, for some kinds of reporting, the count of observations may be all that is required, for example for understanding how observations are growing or shrinking in particular locations, or for particular taxa.

To this end, galah.atlas_counts() takes arguments in the same format as galah.atlas_occurrences(), and provides either a total count of records matching the criteria, or a pandas dataframe of counts matching the criteria supplied to the group_by argument. It can also return the total number of groups by using the total_group_by argument.

Parameters:

  • taxa (string) – one or more scientific names. Use galah.search_taxa() to search for valid scientific names.

  • filters (pandas.DataFrame) – filters, in the form field logical value (e.g. "year=2021")

  • group_by (string) – zero or more individual column names (i.e. fields) to include. See galah.show_all() and galah.search_all() to see valid fields.

  • total_group_by (logical) – If True, galah gives total number of groups in data. Defaults to False.

  • use_data_profile (string) – A profile name. Should be a string - the name or abbreviation of a data quality profile to apply to the query. Valid values can be seen using galah.show_all(profiles=True)

  • polygon (shapely Polygon) – A polygon object denoting a geographical region. Defaults to None.

  • bbox (dict or shapely Polygon) – A polygon or dictionary object denoting four points, which are the corners of a geographical region. Defaults to None.

  • simplify_polygon (logical) – When using the polygon argument of galah.atlas_counts(), specifies whether or not to simplify the polygon and use this instead. Defaults to True.

  • config_file (string) – If you want to specify your own config file, put the path and name of the file here. This is applicable when you are running on a server and each user has different configurations. Defaults to None.

Return type:

An object of class pandas.DataFrame.

Examples

Return total records in your chosen atlas

galah.atlas_counts()

   totalRecords
0     167267751

Return records from 2020 onwards, grouped by year

galah.atlas_counts(filters="year>2019",group_by="year")

   year     count
0  2020   7312539
1  2021   8696470
2  2022   9431261
3  2023  11012769
4  2024  11945732
5  2025   9246525
6  2026    419091
galah.atlas_media(taxa=None, scientific_name=None, filters=None, fields=None, multimedia=None, use_data_profile=False, polygon=None, bbox=None, simplify_polygon=False, collect=False, path=None, thumbnail=False, progress_bar=True, config_file=None, mint_doi=False, doi=None, tolerance=0.05)#

In addition to text data describing individual occurrences and their attributes, ALA stores images, sounds and videos associated with a given record. galah.atlas_media() displays metadata for any and all of the media types.

Parameters:

  • taxa (string / list) – one or more scientific names. Use galah.search_taxa() to search for valid scientific names.

  • filters (string / list) – filters, in the form field logical value (e.g. "year=2021")

  • fields (string / list) –

    Name of one or more column groups to include. Valid options are “basic”, “event” and “assertions” Default is set to "fields=basic", which returns:

    • decimalLatitude, decimalLongitude, eventDate, scientificName, taxonConceptID, recordID, dataResourceName, occurrenceStatus

    Using "fields="event" returns:

    • eventRemarks, eventTime, eventID, eventDate, samplingEffort, samplingProtocol

    Using fields="media" returns:

    • multimedia, multimediaLicence, images, videos, sounds

    See galah.show_all() and galah.search_all() to see all valid fields.

  • multimedia (string / list) – This is for specifying what types of multimedia you would like, i.e “images”. Defaults to [‘images’,’videos’,’sounds’]

  • assertions (string) – Using “assertions” returns all quality assertion-related columns. These columns are data quality checks run by each living atlas. The list of assertions is shown by galah.show_all(assertions=True).

  • use_data_profile (logical) – if True, uses data profile set in galah_config(). Valid values can be seen using galah.show_all(profiles=True). Default is False

  • polygon (shapely Polygon) – A polygon shape denoting a geographical region. Defaults to None.

  • bbox (dict or shapely Polygon) – A polygon or dictionary type denoting four points, which are the corners of a geographical region. Defaults to None.

  • simplify_polygon (logical) – When using the polygon argument of galah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults to False.

  • collect (logical) – if True, downloads full-sized images and media files returned to a local directory.

  • path (string) – path to directory where downloaded media will be stored. Defaults to current directory.

  • thumbnail (logical) – if True, downloads thumbnail images rather than the full image. Defaults to False.

  • progress_bar (logical) – if True, shows a progress bar while images are downloading. Defaults to True.

  • config_file (string) – If you want to specify your own config file, put the path and name of the file here. This is applicable when you are running on a server and each user has different configurations. Defaults to None.

Return type:

An object of class pandas.DataFrame. If collect=True, available image & media files are downloaded to a user local directory.

Examples

galah.galah_config(atlas="Australia",email="youremail@example.com")
galah.atlas_media(taxa="Ornithorhynchus anatinus",filters=["year=2020","decimalLongitude>153.0")

   decimalLatitude  decimalLongitude             eventDate  \
0       -30.311448        153.015910  2020-09-08T17:26:47Z   
1       -30.300649        153.006628  2020-08-30T18:37:43Z   
2       -30.298361        153.007479  2020-08-30T18:35:00Z   
3       -30.298183        153.005912  2020-09-04T18:28:00Z   
4       -30.297841        153.005873  2020-09-26T17:39:00Z   
5       -28.678673        153.297699  2020-08-13T00:00:00Z   

             scientificName  \
0  Ornithorhynchus anatinus   
1  Ornithorhynchus anatinus   
2  Ornithorhynchus anatinus   
3  Ornithorhynchus anatinus   
4  Ornithorhynchus anatinus   
5  Ornithorhynchus anatinus   

                                      taxonConceptID  \
0  https://biodiversity.org.au/afd/taxa/ac61fd14-...   
1  https://biodiversity.org.au/afd/taxa/ac61fd14-...   
2  https://biodiversity.org.au/afd/taxa/ac61fd14-...   
3  https://biodiversity.org.au/afd/taxa/ac61fd14-...   
4  https://biodiversity.org.au/afd/taxa/ac61fd14-...   
5  https://biodiversity.org.au/afd/taxa/ac61fd14-...   

                               recordID       dataResourceName  \
0  6882dfe3-5295-493d-a005-66f8392e9d5b  iNaturalist Australia   
1  72ad295f-112d-442f-83e1-fd385ef9163a  iNaturalist Australia   
2  42912016-2409-4125-a61f-13ffd4c32fcb  iNaturalist Australia   
3  dd885218-bdb9-404a-8441-e5cd329f6605  iNaturalist Australia   
4  072bc4f0-7581-44c6-b0ec-e3fe58d251fc  iNaturalist Australia   
5  12d8c7f9-9d66-4312-9245-87a0a1021557  iNaturalist Australia   

  occurrenceStatus multimedia                                images videos  \
0          PRESENT      Image  792a93d4-6436-4222-9a00-00cda0ec1f14    NaN   
1          PRESENT      Image  1aad7125-c6c0-4557-b9a2-112c03ac6709    NaN   
2          PRESENT      Image  09efd0a0-aa51-4d00-80f9-4e78e19aa89e    NaN   
3          PRESENT      Image  40aadbde-3918-4bba-9dc9-13fa1da3809b    NaN   
4          PRESENT      Image  14374712-1c37-4e2d-af28-4572f64e7d3a    NaN   
5          PRESENT      Image  393df479-5fbb-464e-82ed-4d6fd19dd863    NaN   

   sounds       creator                                         license  \
0     NaN  kerrycameron  http://creativecommons.org/licenses/by-nc/4.0/   
1     NaN  Brett Vercoe  http://creativecommons.org/licenses/by-nc/4.0/   
2     NaN  Brett Vercoe  http://creativecommons.org/licenses/by-nc/4.0/   
3     NaN  Brett Vercoe  http://creativecommons.org/licenses/by-nc/4.0/   
4     NaN  Brett Vercoe  http://creativecommons.org/licenses/by-nc/4.0/   
5     NaN  julespetroff  http://creativecommons.org/licenses/by-nc/4.0/   

     mimeType  width  height  \
0  image/jpeg    927     701   
1  image/jpeg   1365    2048   
2  image/jpeg   2048    1238   
3  image/jpeg   2048    1365   
4  image/jpeg   2048    1365   
5  image/jpeg    638     426   

                                            imageUrl  
0  https://images.ala.org.au/store/4/1/f/1/792a93...  
1  https://images.ala.org.au/store/9/0/7/6/1aad71...  
2  https://images.ala.org.au/store/e/9/8/a/09efd0...  
3  https://images.ala.org.au/store/b/9/0/8/40aadb...  
4  https://images.ala.org.au/store/a/3/d/7/143747...  
5  https://images.ala.org.au/store/3/6/8/d/393df4...
galah.atlas_occurrences(taxa=None, scientific_name=None, filters=None, fields=None, use_data_profile=False, species_list=False, status_accepted=True, polygon=None, bbox=None, simplify_polygon=False, mint_doi=False, doi=None, config_file=None, tolerance=0.05)#

The most common form of data stored by living atlases are observations of individual life forms, known as ‘occurrences’. This function allows the user to search for occurrence records that match their specific criteria, and return them as a pandas.DataFrame for analysis. Optionally, the user can also request a DOI for a given download to facilitate citation and reuse of specific data resources.

Parameters:

  • taxa (string) – one or more scientific names. Use galah.search_taxa() to search for valid scientific names.

  • filters (string / list) – filters, in the form field logical value (e.g. "year=2021")

  • test (logical) – Test if the API is up and running correctly. Prints status of Atlas and returns.

  • fields (string / list) –

    Name of one or more column groups to include. Valid options are “basic”, “event” and “assertions” Default is set to "fields=basic", which returns:

    • decimalLatitude, decimalLongitude, eventDate, scientificName, taxonConceptID, recordID, dataResourceName, occurrenceStatus

    Using "fields="event" returns:

    • eventRemarks, eventTime, eventID, eventDate, samplingEffort, samplingProtocol

    Using fields="media" returns:

    • multimedia, multimediaLicence, images, videos, sounds

    Using fields="assertions returns:

    • all available assertions from the ALA

    See galah.show_all() and galah.search_all() to see all valid fields.

  • assertions (string / list) – Using “assertions” returns all quality assertion-related columns. These columns are data quality checks run by each living atlas. The list of assertions is shown by galah.show_all(assertions=True).

  • use_data_profile (string) – A profile name. Should be a string - the name or abbreviation of a data quality profile to apply to the query. Valid values can be seen using galah.show_all(profiles=True)

  • species_list (logical) – Denotes whether or not you want a species list for GBIF. Default to False. For species lists, refer to atlas_species

  • status_accepted (logical) – Denotes whether or not you want only accepted taxonomic ranks for GBIF. Default to True. For species lists, refer to atlas_species

  • polygon (shapely Polygon) – A polygon shape denoting a geographical region. Defaults to None.

  • bbox (dict or shapely Polygon) – A polygon or dictionary type denoting four points, which are the corners of a geographical region. Defaults to None.

  • simplify_polygon (logical) – When using the polygon argument of galah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults to True.

  • config_file (string) – If you want to specify your own config file, put the path and name of the file here. This is applicable when you are running on a server and each user has different configurations. Defaults to None.

Return type:

An object of class pandas.DataFrame.

Examples

Download records of Vulpes vulpes in 2023

import galah
galah.galah_config(atlas="Australia",email="your-email@example.com")
galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year=2023")

      decimalLatitude  decimalLongitude             eventDate scientificName  \
0          -39.083564        146.383184  2023-02-02T00:00:00Z  Vulpes vulpes   
1          -39.055892        146.448243  2023-09-26T12:58:13Z  Vulpes vulpes   
2          -39.029077        146.323238  2023-01-13T06:16:00Z  Vulpes vulpes   
3          -39.026141        146.332604  2023-07-16T00:00:00Z  Vulpes vulpes   
4          -39.021544        146.443742  2023-03-14T15:40:48Z  Vulpes vulpes   
...               ...               ...                   ...            ...   
8511        39.300000        -75.400000  2023-11-02T04:54:00Z  Vulpes vulpes   
8512        40.000000        -81.500000  2023-07-14T11:15:00Z  Vulpes vulpes   
8513        42.100000        -71.600000  2023-12-18T13:33:00Z  Vulpes vulpes   
8514        43.600000        145.300000  2023-08-09T10:50:47Z  Vulpes vulpes   
8515        51.100000         -0.500000  2023-03-17T12:04:54Z  Vulpes vulpes   

                                         taxonConceptID  \
0     https://biodiversity.org.au/afd/taxa/2869ce8a-...   
1     https://biodiversity.org.au/afd/taxa/2869ce8a-...   
2     https://biodiversity.org.au/afd/taxa/2869ce8a-...   
3     https://biodiversity.org.au/afd/taxa/2869ce8a-...   
4     https://biodiversity.org.au/afd/taxa/2869ce8a-...   
...                                                 ...   
8511  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
8512  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
8513  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
8514  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
8515  https://biodiversity.org.au/afd/taxa/2869ce8a-...   

                                  recordID             dataResourceName  \
0     572341b6-94ca-4d96-bf4f-889cbd5e26f0                    FeralScan   
1     c9e41540-1253-4db8-b13a-25b353dc93b5        iNaturalist Australia   
2     cab54c0e-c06a-4998-8788-f918cf104154        iNaturalist Australia   
3     147fbb76-92b6-460c-bb12-4f9fc5f353b0                    FeralScan   
4     e82ec752-fbcc-40e4-97e4-41adbfdee088        iNaturalist Australia   
...                                    ...                          ...   
8511  531ca541-8c12-4bdd-834d-31980cd127ab  Earth Guardians Weekly Feed   
8512  4065886d-ce29-48d2-b8b3-9bc4195ba8b3  Earth Guardians Weekly Feed   
8513  d35e6a68-ca70-42d2-beae-e6747d1138cf  Earth Guardians Weekly Feed   
8514  47b6921d-3891-4e52-b1aa-9fbd57e76823  Earth Guardians Weekly Feed   
8515  65fc1040-5675-4f6c-8c92-40f8de159bed  Earth Guardians Weekly Feed   

     occurrenceStatus  
0             PRESENT  
1             PRESENT  
2             PRESENT  
3             PRESENT  
4             PRESENT  
...               ...  
8511          PRESENT  
8512          PRESENT  
8513          PRESENT  
8514          PRESENT  
8515          PRESENT  

[8516 rows x 8 columns]

Download records of Vulpes vulpes in 2023, returning only eventDate field

import galah
galah.galah_config(atlas="Australia",email="your-email@example.com")
galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year=2023",fields="eventDate")

                 eventDate
0     2023-01-01T00:00:00Z
1     2023-01-01T00:00:00Z
2     2023-01-01T00:00:00Z
3     2023-01-01T00:00:00Z
4     2023-01-01T00:00:00Z
...                    ...
8511  2023-12-31T00:00:00Z
8512  2023-12-31T00:00:00Z
8513  2023-12-31T00:00:00Z
8514  2023-12-31T14:01:00Z
8515  2023-12-31T16:56:00Z

[8516 rows x 1 columns]
galah.atlas_species(taxa=None, scientific_name=None, rank='species', group_by=None, filters=None, status_accepted=True, use_data_profile=False, counts=False, polygon=None, bbox=None, simplify_polygon=False, config_file=None, tolerance=None, mint_doi=None)#

While there are reasons why users may need to check every record meeting their search criteria (i.e. using galah.atlas_occurrences()), a common use case is to simply identify which species occur in a specified region, time period, or taxonomic group. This function returns a pandas.DataFrame with one row per species, and columns giving associated taxonomic information.

Parameters:

  • taxa (string / list) – one or more scientific names. Use galah.search_taxa() to search for valid scientific names.

  • rank (string) – the rank you ultimately want to get names for, i.e. “genus” or “species”. Default is species.

  • filters (string) – filters, in the form field logical value (e.g. "year=2021")

  • status_accepted (logical) – If True, galah gives you only the accepted taxonomic ranks. Default is False. **FOR GBIF ONLY

  • polygon (shapely Polygon) – A polygon shape denoting a geographical region. Defaults to None.

  • bbox (dict or shapely Polygon) – A polygon or dictionary type denoting four points, which are the corners of a geographical region. Defaults to None.

  • simplify_polygon (logical) – When using the polygon argument of galah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults to False.

  • config_file (string) – If you want to specify your own config file, put the path and name of the file here. This is applicable when you are running on a server and each user has different configurations. Defaults to None.

Return type:

An object of class pandas.DataFrame.

Examples

galah.atlas_species(taxa="Heleioporus")

                                             Species  \
0  https://biodiversity.org.au/afd/taxa/4437371b-...   
1  https://biodiversity.org.au/afd/taxa/d497c571-...   
2  https://biodiversity.org.au/afd/taxa/f0d1bb06-...   
3  https://biodiversity.org.au/afd/taxa/55de9548-...   
4  https://biodiversity.org.au/afd/taxa/4f42e8dd-...   
5  https://biodiversity.org.au/afd/taxa/40389159-...   

                Species Name Scientific Name Authorship Taxon Rank   Kingdom  \
0          Heleioporus eyrei               (Gray, 1845)    species  Animalia   
1   Heleioporus australiacus      (Shaw & Nodder, 1795)    species  Animalia   
2  Heleioporus albopunctatus                 Gray, 1841    species  Animalia   
3   Heleioporus psammophilus         (Lee & Main, 1954)    species  Animalia   
4     Heleioporus barycragus                  Lee, 1967    species  Animalia   
5      Heleioporus inornatus         (Lee & Main, 1954)    species  Animalia   

     Phylum     Class  Order           Family        Genus  \
0  Chordata  Amphibia  Anura  Limnodynastidae  Heleioporus   
1  Chordata  Amphibia  Anura  Limnodynastidae  Heleioporus   
2  Chordata  Amphibia  Anura  Limnodynastidae  Heleioporus   
3  Chordata  Amphibia  Anura  Limnodynastidae  Heleioporus   
4  Chordata  Amphibia  Anura  Limnodynastidae  Heleioporus   
5  Chordata  Amphibia  Anura  Limnodynastidae  Heleioporus   

        Vernacular Name  
0          Moaning Frog  
1  Giant Burrowing Frog  
2  Western Spotted Frog  
3             Sand Frog  
4    Western Marsh Frog  
5           Plains Frog
galah.galah_config(email=None, email_notify=None, atlas=None, data_profile=None, ranks=None, reason=None, verbose=None, timeout=600, usernameGBIF=None, passwordGBIF=None, config_file=None, authenticate=None, auth_filename=None, auth_clear=None)#

The galah package supports large data downloads, and also interfaces with the ALA which requires that users of some services provide a registered email address and reason for downloading data. The galah_config() function provides a way to manage these issues as simply as possible.

Parameters:

  • email (string) – An email address that has been registered with the chosen atlas. For the ALA, you can register here.

  • email_notify (string) – Used to receive an email for each query to galah.atlas_occurrences(). Defaults to None, but can be useful in some instances, for example for tracking DOIs assigned to specific downloads for later citation.

  • atlas (string) – Living Atlas to point to, Australia by default. Can be an organisation name, acronym, or region (see show_all(atlases=True) for admissible values)

  • data_profile (string) – A profile name. Should be a string - the name or abbreviation of a data quality profile to apply to the query. Valid values can be seen using galah.show_all(profiles=True)

  • ranks (string) – A string letting galah know what taxonomic ranks to show. Use ‘all’ to see all 69 possible ranks, and ‘gbif’ to see the 9 most common ranks.

  • reason (integer) – A number (integer) providing the reason you are downloading data. Default is set to 4 (scientific research). For a list of all possible reasons run galah.show_all_reasons()

  • verbose (logical) – If True, galah gives you the URLs used to query all the data. Default to False.

  • usernameGBIF (string) – Your username for GBIF atlas. Default is ‘’.

  • passwordGBIF (string) – Your password for GBIF atlas. Default is ‘’.

  • authenticate (logical) – An argument to

Returns:

  • - No arguments (A pandas.DataFrame of all current configuration options.)

  • - >=1 arguments (None)

Examples

import galah
galah.galah_config(email='yourname@example.com')
galah.search_all(assertions=None, atlases=None, apis=None, collection=None, datasets=None, fields=None, licences=None, lists=None, profiles=None, providers=None, ranks=None, reasons=None, column_name=None, verbose=False, config_file=None)#

The living atlases store a huge amount of information, above and beyond the occurrence records that are their main output. In galah, one way that users can investigate this information is by searching for a specific option or category for the type of information they are interested in. search_all() is a helper function that can do searches within multiple types of information.

Parameters:

  • assertions (string) – Search for results of data quality checks run by each atlas

  • atlases (string) – Search for what atlases are available

  • apis (string) – Search for what APIs & functions are available for each atlas

  • collection (string) – Search for the specific collections within those institutions

  • datasets (string) – Search for the data groupings within those collections

  • fields (string) – Search for fields that are stored in an atlas

  • licences (string) – Search for copyright licences applied to media

  • lists (string) – Search for what species lists are available

  • profiles (string) – Search for what data profiles are available

  • providers (string) – Search for which institutions have provided data

  • ranks (string) – Search for valid taxonomic ranks (e.g. Kingdom, Class, Order, etc.)

  • reasons (string) – Search for what values are acceptable as ‘download reasons’ for a specified atlas

  • column_name (string) – Determines what column in the table this function will search for the string specified as the argument

Return type:

An object of class pandas.DataFrame containing all data of interest.

Examples

import galah
galah.search_all(apis='Australia')

        atlas          system                   api_name  \
0   Australia     collections    collections_collections   
1   Australia         species             species_lookup   
2   Australia         species           species_children   
3   Australia         spatial             spatial_layers   
4   Australia         records            records_species   
5   Australia         records        records_occurrences   
6   Australia         records             records_fields   
7   Australia         records             records_facets   
8   Australia         records             records_counts   
9   Australia         records         records_assertions   
10  Australia   name-matching        names_search_single   
11  Australia   name-matching       names_search_epithet   
12  Australia   name-matching      names_search_multiple   
13  Australia     occurrences            occurrences_qid   
14  Australia         species  names_search_bulk_species   
15  Australia          logger             logger_reasons   
16  Australia           lists               lists_lookup   
17  Australia           lists                  lists_all   
18  Australia          images             image_download   
19  Australia          images        image_bulk_metadata   
20  Australia          images             image_metadata   
21  Australia          images             image_licences   
22  Australia             doi               doi_download   
23  Australia    data-quality            profiles_lookup   
24  Australia    data-quality               profiles_all   
25  Australia     collections      collections_providers   
26  Australia     collections       collections_datasets   
27  Australia   name-matching               names_lookup   
28  Australia  authentication             authentication   

                                              api_url  \
0       https://api.ala.org.au/metadata/ws/collection   
1   https://api.ala.org.au/species/childConcepts/{id}   
2   https://api.ala.org.au/species/childConcepts/{...   
3       https://api.ala.org.au/spatial-service/fields   
4   https://api.ala.org.au/occurrences/occurrences...   
5   https://api.ala.org.au/occurrences/occurrences...   
6     https://api.ala.org.au/occurrences/index/fields   
7   https://api.ala.org.au/occurrences/occurrences...   
8   https://api.ala.org.au/occurrences/occurrences...   
9   https://api.ala.org.au/occurrences/assertions/...   
10  https://api.ala.org.au/namematching/api/search...   
11  https://api.ala.org.au/namematching/api/search...   
12  https://api.ala.org.au/namematching/api/search...   
13             https://api.ala.org.au/occurrences/qid   
14  https://api.ala.org.au/species/species/lookup/...   
15  https://api.ala.org.au/logger/service/logger/r...   
16  https://api.ala.org.au/specieslist/ws/speciesL...   
17  https://api.ala.org.au/specieslist/ws/speciesList   
18  https://api.ala.org.au/images/ws/image/{id}/or...   
19  https://api.ala.org.au/images/ws/getImageInfoF...   
20   https://api.ala.org.au/images/ws/image/{imageID}   
21           https://api.ala.org.au/images/ws/licence   
22  https://api.ala.org.au/doi/api/doi/{doi_string...   
23  https://api.ala.org.au/dqf-service/api/v1/data...   
24  https://api.ala.org.au/dqf-service/api/v1/data...   
25    https://api.ala.org.au/metadata/ws/dataProvider   
26    https://api.ala.org.au/metadata/ws/dataResource   
27  https://api.ala.org.au/namematching/api/getByT...   
28    https://api.ala.org.au/common/api/getAuthConfig   

                           called_by  functional method  
0               show_all-collections        True    GET  
1                     atlas_taxonomy        True    GET  
2                     atlas_taxonomy        True    GET  
3                    show_all-fields        True    GET  
4                      atlas_species        True    GET  
5                  atlas_occurrences        True    GET  
6                    show_all-fields        True    GET  
7   atlas_counts, show_values-fields        True    GET  
8                       atlas_counts        True    GET  
9                show_all-assertions        True    GET  
10                       search_taxa        True    GET  
11                       search_taxa        True    GET  
12                       search_taxa        True   POST  
13                 atlas_occurrences        True   POST  
14                     atlas_species        True   POST  
15                  show_all-reasons        True    GET  
16                 show_values-lists        True    GET  
17                    show_all-lists        True    GET  
18                    media_download        True    GET  
19                    media_metadata        True   POST  
20                    media_metadata        True    GET  
21                 show_all-licences        True    GET  
22                      doi_download        True    GET  
23              show_values-profiles        True    GET  
24                 show_all-profiles        True    GET  
25                show_all-providers        True    GET  
26                 show_all-datasets        True    GET  
27                search_identifiers        True    GET  
28         get_authentication_tokens        True    GET
galah.search_taxa(taxa=None, identifiers=None, specific_epithet=None, scientific_name=None, config_file=None)#

Look up taxonomic names before downloading data from the ALA, using atlas_occurrences(), atlas_species() or atlas_counts(). Taxon information returned by search_taxa() may be passed to the taxa argument of atlas functions.

search_taxa() allows users to disambiguate homonyms (i.e. where the same name refers to taxa in different clades) prior to downloading data.

Parameters:

  • taxa (string) – one or more scientific names to search.

  • identifiers (string / list) – one or more taxonomic identifiers (such as guid or taxonConceptID) to search.

  • specific_epithet (list) – search taxonomic levels by using the argument “specificEpithet”.

  • scientific_name (dictionary) – search taxonomic levels by using the argument “scientificName”.

  • verbose (logical) – If True, galah gives more information like URLs of your queries. Defaults to False

Return type:

An object of class pandas.DataFrame.

Examples

Get taxonomic identifiers for “Vulpes vulpes”

import galah
galah.search_taxa(taxa="Vulpes vulpes")

  scientificName scientificNameAuthorship  ...   issues vernacularName
0  Vulpes vulpes           Linnaeus, 1758  ...  noIssue            Fox

[1 rows x 14 columns]

Get the species name from a taxonomic identifier

import galah
galah.search_taxa(identifiers="https://id.biodiversity.org.au/node/apni/2914510")

        scientificName scientificNameAuthorship  \
0  Eucalyptus blakelyi                   Maiden   

                                     taxonConceptID     rank     matchType  \
0  https://id.biodiversity.org.au/node/apni/2914510  species  taxonIdMatch   

   kingdom      phylum         classs     order     family       genus  \
0  Plantae  Charophyta  Equisetopsida  Myrtales  Myrtaceae  Eucalyptus   

               species   issues     vernacularName  
0  Eucalyptus blakelyi  noIssue  Blakely's Red Gum

Search taxonomic levels by using the key word “specificEpithet”

import galah
galah.search_taxa(specific_epithet=["class=aves","family=pardalotidae","genus=pardalotus","specificEpithet=punctatus"])

                      scientificName scientificNameAuthorship  \
0  Pardalotus (Pardalotus) punctatus             (Shaw, 1792)   

                                      taxonConceptID     rank   matchType  \
0  https://biodiversity.org.au/afd/taxa/5254fe03-...  species  exactMatch   

    kingdom    phylum classs          order        family       genus  \
0  Animalia  Chordata   Aves  Passeriformes  Pardalotidae  Pardalotus   

                species   issues     vernacularName  
0  Pardalotus punctatus  noIssue  Spotted Pardalote

Search taxonomic levels by using the key word “scientificName”

import galah
galah.search_taxa(scientific_name={"family": ["pardalotidae","maluridae"],"scientificName": ["pardolatus striatus","malurus cyaneus"]})

                       scientificName scientificNameAuthorship  \
0  Pardalotus (Pardalotinus) striatus           (Gmelin, 1789)   

                                      taxonConceptID     rank   matchType  \
0  https://biodiversity.org.au/afd/taxa/e3103245-...  species  fuzzyMatch   

    kingdom    phylum classs          order        family       genus  \
0  Animalia  Chordata   Aves  Passeriformes  Pardalotidae  Pardalotus   

               species   issues      vernacularName  
0  Pardalotus striatus  noIssue  Striated Pardalote
galah.search_values(field=None, value=None, lists=False, all_fields=False, column_name=None, config_file=None)#

Users may wish to see the specific values within a chosen field, profile or list to narrow queries or understand more about the information of interest. search_values() allows users for search for specific values within a specified field.

Parameters:

  • field (string) – A string to specify what type of parameters should be searched.

  • value (string) – A string specifying a search term. Not case sensitive.

  • lists (logical) – This lets show_values() know if you want to look up fields, or if you want to look up species in lists. Default is False.

  • all_fields (logical) – For threatened and sensitive lists, this argument will give you the option of downloading species statuses. Default is False.

  • verbose (logical) – This option is available for users who want to know what URLs this function is using to get the value. Default to False.

Return type:

An object of class pandas.DataFrame.

Examples

import galah
galah.search_values(field='basisOfRecord',value='OBS')

#.. program-output:: python -c ‘import galah; print(galah.search_values(field='basisOfRecord',value='obs'))’

galah.show_all(assertions=False, atlases=False, apis=False, collection=False, datasets=False, fields=False, licences=False, lists=False, profiles=False, providers=False, ranks=False, reasons=False, verbose=False, config_file=None)#

The living atlases store a huge amount of information, above and beyond the occurrence records that are their main output. In galah, one way that users can investigate this information is by showing all the available options or categories for the type of information they are interested in. show_all() is a helper function that can display multiple types of information, displaying all valid options for the information specified.

Parameters:

  • assertions (logical) – Show results of data quality checks run by each atlas

  • atlases (logical) – Show what atlases are available

  • apis (logical) – Show what APIs & functions are available for each atlas

  • collection (logical) – Show the specific collections within those institutions

  • datasets (logical) – Shows all the data groupings within those collections

  • fields (logical) – Show fields that are stored in an atlas

  • licences (logical) – Show what copyright licenses are applied to media

  • lists (logical) – Show what species lists are available

  • profiles (logical) – Show what data profiles are available

  • providers (logical) – Show which institutions have provided data

  • ranks (logical) – Show valid taxonomic ranks (e.g. Kingdom, Class, Order, etc.)

  • reasons (logical) – Show what values are acceptable as ‘download reasons’ for a specified atlas

Return type:

An object of class pandas.DataFrame containing all data of interest.

Examples

import galah
galah.show_all(datasets=True)

                                                    name  \
0       ALA Taxonomy List for Species Missing from Co...   
1                                         "A" Flora EPBC   
2                                    "H to O" flora EPBC   
3                                    "P to Z" flora EPBC   
4                  (Acrostichum speciosum) Mangrove Fern   
...                                                  ...   
14206  Zooplankton sampling in the coastal waters of ...   
14207                         Zoos Victoria Moth Tracker   
14208                            Zosteria fulvipubescens   
14209                            Zosteria fulvipubescens   
14210                                                zza   

                                                     uri      uid  
0      https://collections.ala.org.au/ws/dataResource...  dr23929  
1      https://collections.ala.org.au/ws/dataResource...  dr24170  
2      https://collections.ala.org.au/ws/dataResource...  dr24172  
3      https://collections.ala.org.au/ws/dataResource...  dr24173  
4      https://collections.ala.org.au/ws/dataResource...  dr34493  
...                                                  ...      ...  
14206  https://collections.ala.org.au/ws/dataResource...  dr15943  
14207  https://collections.ala.org.au/ws/dataResource...  dr22371  
14208  https://collections.ala.org.au/ws/dataResource...  dr27880  
14209  https://collections.ala.org.au/ws/dataResource...  dr27881  
14210  https://collections.ala.org.au/ws/dataResource...  dr33432  

[14211 rows x 3 columns]
galah.show_values(field=None, lists=False, all_fields=False, verbose=False, config_file=None)#

Users may wish to see the specific values within a chosen field, profile or list to narrow queries or understand more about the information of interest. show_values() provides users with these values.

Parameters:

  • field (string) – A string to specify what type of parameters should be shown.

  • lists (logical) – This lets show_values() know if you want to look up fields, or if you want to look up species in lists. Default is False.

  • all_fields (logical) – For threatened and sensitive lists, this argument will give you the option of downloading species statuses. Default is False.

  • verbose (logical) – This option is available for users who want to know what URLs this function is using to get the value. Default is False.

Return type:

An object of class pandas.DataFrame.

Examples

import galah
galah.show_values(field='basisOfRecord')

           field             category
0  basisOfRecord    HUMAN_OBSERVATION
1  basisOfRecord   PRESERVED_SPECIMEN
2  basisOfRecord           OCCURRENCE
3  basisOfRecord  MACHINE_OBSERVATION
4  basisOfRecord          OBSERVATION
5  basisOfRecord      MATERIAL_SAMPLE
6  basisOfRecord      LIVING_SPECIMEN
7  basisOfRecord      FOSSIL_SPECIMEN
8  basisOfRecord    MATERIAL_CITATION