API Docs#

galah.atlas_counts(taxa=None, scientific_name=None, filters=None, group_by=None, total_group_by=False, expand=True, use_data_profile=False, verbose=False, polygon=None, bbox=None, simplify_polygon=False)#

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.

  • expand (logical) – When using the group_by argument of galah.atlas_counts(), controls whether counts for each row value are combined or calculated separately. Defaults to True.

  • verbose (logical) – If True, galah gives more information like progress bars. 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 draw a bounding box around the polygon and use this instead. Defaults to False.

Return type:

An object of class pandas.DataFrame.

Examples

Return total records in your chosen atlas

galah.atlas_counts()
   totalRecords
0     132396926

Return records from 2020 onwards, grouped by year

galah.atlas_counts(filters="year>2019",group_by="year",expand=False)
   year    count
0  2020  7124862
1  2021  8255051
2  2022  8411624
3  2023  3487048
galah.atlas_media(taxa=None, scientific_name=None, filters=None, fields=None, verbose=False, multimedia=None, assertions=None, use_data_profile=False, polygon=None, bbox=None, simplify_polygon=False, collect=False, path=None)#

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.

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

  • 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.

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-08T07:26:47Z   
1       -30.300649        153.006628  2020-08-30T08:37:43Z   
2       -30.298361        153.007479  2020-08-30T08:35:00Z   
3       -30.298183        153.005912  2020-09-04T08:28:00Z   
4       -30.297841        153.005873  2020-09-26T07:39:00Z   
5       -28.678673        153.297699  2020-08-13T00:00:00Z   
6       -28.661653        153.300439  2020-10-12T06:20:00Z   
7       -28.661653        153.300439  2020-10-12T06:20:00Z   
8       -28.213785        153.386929  2020-01-17T07:09:00Z   
9       -28.213785        153.386929  2020-01-17T07:09:00Z   

             scientificName                              recordID  \
0  Ornithorhynchus anatinus  6882dfe3-5295-493d-a005-66f8392e9d5b   
1  Ornithorhynchus anatinus  72ad295f-112d-442f-83e1-fd385ef9163a   
2  Ornithorhynchus anatinus  42912016-2409-4125-a61f-13ffd4c32fcb   
3  Ornithorhynchus anatinus  dd885218-bdb9-404a-8441-e5cd329f6605   
4  Ornithorhynchus anatinus  072bc4f0-7581-44c6-b0ec-e3fe58d251fc   
5  Ornithorhynchus anatinus  12d8c7f9-9d66-4312-9245-87a0a1021557   
6  Ornithorhynchus anatinus  2a701513-b21d-4baa-bac4-5e6a3a65252b   
7  Ornithorhynchus anatinus  2a701513-b21d-4baa-bac4-5e6a3a65252b   
8  Ornithorhynchus anatinus  808b0c19-9616-45f1-994e-e3b33fc32836   
9  Ornithorhynchus anatinus  808b0c19-9616-45f1-994e-e3b33fc32836   

              dataResourceName occurrenceStatus multimedia  \
0        iNaturalist Australia          PRESENT      Image   
1        iNaturalist Australia          PRESENT      Image   
2        iNaturalist Australia          PRESENT      Image   
3        iNaturalist Australia          PRESENT      Image   
4        iNaturalist Australia          PRESENT      Image   
5        iNaturalist Australia          PRESENT      Image   
6        iNaturalist Australia          PRESENT      Image   
7        iNaturalist Australia          PRESENT      Image   
8  Earth Guardians Weekly Feed          PRESENT      Image   
9  Earth Guardians Weekly Feed          PRESENT      Image   

                                 images videos  sounds       creator  \
0  792a93d4-6436-4222-9a00-00cda0ec1f14    NaN     NaN  kerrycameron   
1  1aad7125-c6c0-4557-b9a2-112c03ac6709    NaN     NaN  Brett Vercoe   
2  09efd0a0-aa51-4d00-80f9-4e78e19aa89e    NaN     NaN  Brett Vercoe   
3  40aadbde-3918-4bba-9dc9-13fa1da3809b    NaN     NaN  Brett Vercoe   
4  14374712-1c37-4e2d-af28-4572f64e7d3a    NaN     NaN  Brett Vercoe   
5  393df479-5fbb-464e-82ed-4d6fd19dd863    NaN     NaN  julespetroff   
6  7424399a-f327-4ea1-9ffa-aa7a2b69f82b    NaN     NaN  julespetroff   
7  cee7bb9f-6b2e-4c47-8ba8-c9a3bdf92fa0    NaN     NaN  julespetroff   
8  66904cee-f8ca-4e3a-b7d5-d738f4bd0978    NaN     NaN          None   
9  dfdbd258-d90a-484b-af19-2070705f166c    NaN     NaN          None   

                                          license    mimetype  width  height  \
0  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg    927     701   
1  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg   1365    2048   
2  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg   2048    1238   
3  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg   2048    1365   
4  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg   2048    1365   
5  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg    638     426   
6  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg    713     401   
7  http://creativecommons.org/licenses/by-nc/4.0/  image/jpeg    661     500   
8                                            None  image/jpeg   2988    5312   
9                                            None  image/jpeg   2988    5312   

                                            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...  
6  https://images.ala.org.au/store/b/2/8/f/742439...  
7  https://images.ala.org.au/store/0/a/f/2/cee7bb...  
8  https://images.ala.org.au/store/8/7/9/0/66904c...  
9  https://images.ala.org.au/store/c/6/6/1/dfdbd2...
galah.atlas_occurrences(taxa=None, scientific_name=None, filters=None, test=False, verbose=False, fields=None, assertions=None, use_data_profile=False, species_list=False, status_accepted=True, polygon=None, bbox=None, simplify_polygon=False)#

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 re-use 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.

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

  • 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.

  • 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 False.

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-26T02:58:13Z  Vulpes vulpes   
2          -39.029077        146.323238  2023-01-12T19:16:00Z  Vulpes vulpes   
3          -39.026141        146.332604  2023-07-16T00:00:00Z  Vulpes vulpes   
4          -39.021544        146.443742  2023-03-14T04:40:48Z  Vulpes vulpes   
...               ...               ...                   ...            ...   
5053        38.900000        -77.000000  2023-11-04T01:55:00Z  Vulpes vulpes   
5054        39.300000        -75.400000  2023-11-02T04:54:00Z  Vulpes vulpes   
5055        40.000000        -81.500000  2023-07-14T11:15:00Z  Vulpes vulpes   
5056        43.600000        145.300000  2023-08-09T10:50:47Z  Vulpes vulpes   
5057        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-...   
...                                                 ...   
5053  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
5054  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
5055  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
5056  https://biodiversity.org.au/afd/taxa/2869ce8a-...   
5057  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   
...                                    ...                          ...   
5053  493a16e9-5107-4656-a390-e27126a3ea42  Earth Guardians Weekly Feed   
5054  531ca541-8c12-4bdd-834d-31980cd127ab  Earth Guardians Weekly Feed   
5055  4065886d-ce29-48d2-b8b3-9bc4195ba8b3  Earth Guardians Weekly Feed   
5056  47b6921d-3891-4e52-b1aa-9fbd57e76823  Earth Guardians Weekly Feed   
5057  65fc1040-5675-4f6c-8c92-40f8de159bed  Earth Guardians Weekly Feed   

     occurrenceStatus  
0             PRESENT  
1             PRESENT  
2             PRESENT  
3             PRESENT  
4             PRESENT  
...               ...  
5053          PRESENT  
5054          PRESENT  
5055          PRESENT  
5056          PRESENT  
5057          PRESENT  

[5058 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     2022-12-31T14:56:00Z
1     2022-12-31T21:21:27Z
2     2023-01-01T00:00:00Z
3     2023-01-01T00:00:00Z
4     2023-01-01T00:00:00Z
...                    ...
5053  2023-12-17T00:00:00Z
5054  2023-12-17T00:00:00Z
5055  2023-12-17T00:00:00Z
5056  2023-12-18T00:00:00Z
5057  2023-12-18T00:00:00Z

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

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")

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

  • 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.

Return type:

An object of class pandas.DataFrame.

Examples

galah.atlas_species(taxa="Heleioporus")
                                             Species  \
0  https://biodiversity.org.au/afd/taxa/cf991494-...   
1  https://biodiversity.org.au/afd/taxa/20119b25-...   
2  https://biodiversity.org.au/afd/taxa/c1d18a1e-...   
3  https://biodiversity.org.au/afd/taxa/0efbf288-...   
4  https://biodiversity.org.au/afd/taxa/c527388c-...   
5  https://biodiversity.org.au/afd/taxa/16fcc761-...   

                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, usernameGBIF=None, passwordGBIF=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()

  • usernameGBIF (string) – Your username for GBIF atlas. Default is “”.

  • passwordGBIF (string) – Your password for GBIF atlas. Default is “”.

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)#

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_children   
2   Australia        spatial             spatial_layers   
3   Australia        records            records_species   
4   Australia        records              records_query   
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_multiple   
12  Australia        species  names_search_bulk_species   
13  Australia  name-matching               names_lookup   
14  Australia         logger             logger_reasons   
15  Australia          lists               lists_lookup   
16  Australia          lists                  lists_all   
17  Australia         images             image_metadata   
18  Australia         images             image_licences   
19  Australia            doi               doi_download   
20  Australia   data-quality            profiles_lookup   
21  Australia   data-quality               profiles_all   
22  Australia    collections      collections_providers   
23  Australia    collections       collections_datasets   
24  Australia        species             species_lookup   
25  Australia    occurrences            occurrences_qid   

                                              api_url  \
0        https://collections.ala.org.au/ws/collection   
1     https://bie-ws.ala.org.au/ws/childConcepts/{id}   
2                https://spatial.ala.org.au/ws/layers   
3   https://biocache-ws.ala.org.au/ws/occurrences/...   
4   https://biocache-ws.ala.org.au/ws/webportal/pa...   
5   https://biocache-ws.ala.org.au/ws/occurrences/...   
6      https://biocache-ws.ala.org.au/ws/index/fields   
7   https://biocache-ws.ala.org.au/ws/occurrence/f...   
8   https://biocache-ws.ala.org.au/ws/occurrences/...   
9   https://biocache-ws.ala.org.au/ws/assertions/c...   
10  https://namematching-ws.ala.org.au/api/search?...   
11  https://namematching-ws.ala.org.au/api/searchB...   
12   https://bie-ws.ala.org.au/ws/species/lookup/bulk   
13  https://namematching-ws.ala.org.au/api/getByTa...   
14  https://api.ala.org.au/logger/service/logger/r...   
15  https://lists.ala.org.au/ws/speciesListItems/{...   
16            https://lists.ala.org.au/ws/speciesList   
17  https://api.ala.org.au/images/ws/getImageInfoF...   
18               https://images.ala.org.au/ws/licence   
19   https://doi.ala.org.au/doi/{doi_string}/download   
20  https://data-quality-service.ala.org.au/api/v1...   
21  https://data-quality-service.ala.org.au/api/v1...   
22     https://collections.ala.org.au/ws/dataProvider   
23     https://collections.ala.org.au/ws/dataResource   
24          https://bie-ws.ala.org.au/ws/species/{id}   
25  https://biocache-ws.ala.org.au/ws/webportal/pa...   

                           called_by  functional method  
0               show_all-collections        True    GET  
1                     atlas_taxonomy        True    GET  
2                    show_all-fields        True    GET  
3                      atlas_species        True    GET  
4                  atlas_occurrences       False    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                     atlas_species        True   POST  
13                search_identifiers        True    GET  
14                  show_all-reasons        True    GET  
15                 show_values-lists        True    GET  
16                    show_all-lists        True    GET  
17                    media_metadata        True   POST  
18                 show_all-licences        True    GET  
19                      doi_download        True    GET  
20              show_values-profiles        True    GET  
21                 show_all-profiles        True    GET  
22                show_all-providers        True    GET  
23                 show_all-datasets        True    GET  
24                    atlas_taxonomy        True    GET  
25                 atlas_occurrences        True   POST
galah.search_taxa(taxa=None, identifiers=None, specific_epithet=None, scientific_name=None, verbose=False)#

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  ... vernacularName   issues
0  Vulpes vulpes           Linnaeus, 1758  ...            Fox  noIssue

[1 rows x 12 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  kingdom  \
0  https://id.biodiversity.org.au/node/apni/2914510  species  Plantae   

       phylum     order     family       genus              species  \
0  Charophyta  Myrtales  Myrtaceae  Eucalyptus  Eucalyptus blakelyi   

      vernacularName   issues  
0  Blakely's Red Gum  noIssue

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   kingdom  \
0  https://biodiversity.org.au/afd/taxa/5254fe03-...  species  Animalia   

     phylum          order        family       genus               species  \
0  Chordata  Passeriformes  Pardalotidae  Pardalotus  Pardalotus punctatus   

      vernacularName   issues  
0  Spotted Pardalote  noIssue

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)   
0           Malurus (Malurus) cyaneus            (Ellis, 1782)   

                                      taxonConceptID     rank   kingdom  \
0  https://biodiversity.org.au/afd/taxa/e3103245-...  species  Animalia   
0  https://biodiversity.org.au/afd/taxa/760401df-...  species  Animalia   

     phylum          order        family       genus              species  \
0  Chordata  Passeriformes  Pardalotidae  Pardalotus  Pardalotus striatus   
0  Chordata  Passeriformes     Maluridae     Malurus      Malurus cyaneus   

       vernacularName   issues  
0  Striated Pardalote  noIssue  
0   Superb Fairy-wren  noIssue
galah.search_values(field=None, value=None, column_name=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.

  • 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")
           field             category
0  basisOfRecord          OBSERVATION
1  basisOfRecord    HUMAN_OBSERVATION
2  basisOfRecord  MACHINE_OBSERVATION
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)#

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     10 year trend of levels of organochlorine poll...   
...                                                 ...   
3966  Zooplankton abundance in the Kerguelen Axis re...   
3967  Zooplankton Abundance_Umbrella net_sea ice zon...   
3968  Zooplankton samples from Heron net trawls alon...   
3969  Zooplankton sampling in the coastal waters of ...   
3970                         Zoos Victoria Moth Tracker   

                                                    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...  dr16247  
...                                                 ...      ...  
3966  https://collections.ala.org.au/ws/dataResource...  dr16244  
3967  https://collections.ala.org.au/ws/dataResource...  dr16265  
3968  https://collections.ala.org.au/ws/dataResource...  dr23120  
3969  https://collections.ala.org.au/ws/dataResource...  dr15943  
3970  https://collections.ala.org.au/ws/dataResource...  dr22371  

[3971 rows x 3 columns]
galah.show_values(field=None, verbose=False)#

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.

  • 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          OBSERVATION
3  basisOfRecord           OCCURRENCE
4  basisOfRecord  MACHINE_OBSERVATION
5  basisOfRecord      MATERIAL_SAMPLE
6  basisOfRecord      LIVING_SPECIMEN
7  basisOfRecord    MATERIAL_CITATION
8  basisOfRecord      FOSSIL_SPECIMEN