Retrieving data

Getting taxonomic information

GBIF.taxonFunction

Get information about a taxon at any level

taxon(name::String)

This function will look for a taxon by its (scientific) name in the GBIF reference taxonomy.

Optional arguments are

  • rank::Union{Symbol,Nothing}=:SPECIES – the rank of the taxon you want. This is part of a controlled vocabulary, and can only be one of :DOMAIN, :CLASS, :CULTIVAR, :FAMILY, :FORM, :GENUS, :INFORMAL, :ORDER, :PHYLUM,, :SECTION, :SUBCLASS, :VARIETY, :TRIBE, :KINGDOM, :SUBFAMILY, :SUBFORM, :SUBGENUS, :SUBKINGDOM, :SUBORDER, :SUBPHYLUM, :SUBSECTION, :SUBSPECIES, :SUBTRIBE, :SUBVARIETY, :SUPERCLASS, :SUPERFAMILY, :SUPERORDER, and :SPECIES

  • strict::Bool=true – whether the match should be strict, or fuzzy

Finally, one can also specify other levels of the taxonomy, using kingdom, phylum, class, order, family, and genus, all of which can either be String or Nothing.

If a match is found, the result will be given as a GBIFTaxon. If not, this function will return nothing and give a warning.

source

Get information about a taxon at any level using taxonID

taxon(id::Int)

This function will look for a taxon by its taxonID in the GBIF reference taxonomy.

source

Searching for occurrence data

The most common task is to retrieve many occurrences according to a query. The core type of this package is GBIFRecord, which is a very lightweight type containing information about the query, and a list of GBIFRecord for every matching occurrence. Note that the GBIF "search" API is limited to 100000 results, and will not return more than this amount.

Single occurrence

GBIF.occurrenceFunction

Return an interpreted occurrence given its key

occurrence(key::Union{String, Integer})

The key can be given as a string or as an integer.

source

As an example, we can retrieve the occurrence with the key 1258202889, using the following code:

using GBIF
occurrence(1258202889)
GBIF record 1258202889	Alfaroa	(Panama)

Multiple occurrences

GBIF.occurrencesMethod

Retrieve latest occurrences based on a query

occurrences(query::Pair...)

This function will return the latest occurrences matching the queries – usually 20, but this is entirely determined by the server default page size. The query parametes must be given as pairs, and are optional. Omitting the query will return the latest recorded occurrences.

The arguments accepted as queries are the one documented on the GBIF API website.

source
GBIF.occurrencesMethod

Retrieve latest occurrences for a taxon based on a query

occurrences(t::GBIFTaxon, query::Pair...)

Returns occurrences that correspond to a filter, given in q as a dictionary. When first called, this function will return the latest 20 hits (or whichever default page size GBIF uses). Future occurrences can be queried with next! or complete!.

source

When called with no arguments, this function will return a list of the latest 20 occurrences recorded in GBIF. Note that the GBIFRecords type, which is the return type of occurrences, implements the iteration interface. For example, this allows writing the following:

using GBIF
o = occurrences()
for single_occ in o
  print(single_occ.taxon.name)
end
Trichoderma aureovirideBisporella citrinaMycena adscendensCryptosphaeria eunomiaCorticium roseumRosellinia corticiumBelenois javaBelenois javaLachnum impudicumLopadostoma gastrinumPlatystomum obtectumMollisia ligniTrechispora farinaceaNemania serpensAnisotome aromaticaLageniferaAciphylla hectoriOzothamnus vauvilliersiiHuperzia australianaMicroseris scapigera

Query parameters

The queries must be given as pairs of

GBIF.occurrencesMethod

Retrieve latest occurrences based on a query

occurrences(query::Pair...)

This function will return the latest occurrences matching the queries – usually 20, but this is entirely determined by the server default page size. The query parametes must be given as pairs, and are optional. Omitting the query will return the latest recorded occurrences.

The arguments accepted as queries are the one documented on the GBIF API website.

source
GBIF.occurrencesMethod

Retrieve latest occurrences for a taxon based on a query

occurrences(t::GBIFTaxon, query::Pair...)

Returns occurrences that correspond to a filter, given in q as a dictionary. When first called, this function will return the latest 20 hits (or whichever default page size GBIF uses). Future occurrences can be queried with next! or complete!.

source

For example, we can get the data on observations of bats between -30 and 30 of latitude using the following syntax:

using GBIF
bats = GBIF.taxon("Chiroptera"; rank=:ORDER)
for occ in occurrences(bats, "decimalLatitude" => (-30.0, 30.0))
  println("$(occ.scientific) -- latitude = $(occ.latitude)")
end
Saccopteryx bilineata (Temminck, 1838) -- latitude = 10.722004
Rhynchonycteris naso (Wied-Neuwied, 1820) -- latitude = 8.642761
Desmodus rotundus (E.Geoffroy, 1810) -- latitude = 20.450366
Pteropus alecto Temminck, 1837 -- latitude = -27.387515
Nycteris hispida (Schreber, 1775) -- latitude = 2.985546
Pteropus scapulatus Peters, 1862 -- latitude = -17.4
Pteropus scapulatus Peters, 1862 -- latitude = -27.4
Rhinolophus luctus Temminck, 1834 -- latitude = 12.884783
Pteropus alecto Temminck, 1837 -- latitude = -23.180703
Cynomops greenhalli Goodwin, 1958 -- latitude = 8.998384
Balantiopteryx plicata Peters, 1867 -- latitude = 19.386168
Pteropus conspicillatus Gould, 1850 -- latitude = -16.261092
Pteropus scapulatus Peters, 1862 -- latitude = -26.400747
Pteropus poliocephalus Temminck, 1825 -- latitude = -28.248738
Rhinolophus megaphyllus Gray, 1834 -- latitude = -26.95494
Epomophorus wahlbergi (Sundevall, 1846) -- latitude = -29.803641
Pteropus conspicillatus Gould, 1850 -- latitude = -16.910088
Taphozous mauritianus E.Geoffroy, 1818 -- latitude = -13.885931
Thyroptera tricolor Spix, 1823 -- latitude = 4.884589
Ectophylla alba H.Allen, 1892 -- latitude = 10.236846

Batch-download of occurrences

When calling occurrences, the list of possible GBIFRecord will be pre-allocated. Any subsequent call to occurrences! (on the GBIFRecords variable) will retrieve the next "page" of results, and add them to the collection:

GBIF.occurrences!Function

Get the next page of results

This function will retrieve the next page of results. By default, it will walk through queries 20 at a time. This can be modified by changing the .query["limit"] value, to any value up to 300, which is the limit set by GBIF for the queries.

If filters have been applied to this query before, they will be removed to ensure that the previous and the new occurrences have the same status, but only for records that have already been retrieved.

source
using GBIF
can_most_recent = occurrences("hasCoordinate" => true, "country" => "CA")
occurrences!(can_most_recent)
20-element Array{GBIFRecord,1}:
 GBIF record 3017941775	Turdus migratorius	(Canada)

 GBIF record 3017941780	Fulica americana	(Canada)

 GBIF record 3017941786	Asio otus	(Canada)

 GBIF record 3017941789	Haliaeetus leucocephalus	(Canada)

 GBIF record 3017941879	Calypte anna	(Canada)

 GBIF record 3017941906	Falco peregrinus	(Canada)

 GBIF record 3017941939	Melanitta americana	(Canada)

 GBIF record 3017941986	Bucephala albeola	(Canada)

 GBIF record 3017942014	Polypodium glycyrrhiza	(Canada)

 GBIF record 3017942083	Gallinago delicata	(Canada)

 GBIF record 3017942093	Juniperus horizontalis	(Canada)

 GBIF record 3017942143	Poecile atricapillus	(Canada)

 GBIF record 3017942176	Plantago lanceolata	(Canada)

 GBIF record 3017942190	Dryobates pubescens	(Canada)

 GBIF record 3017942656	Meta ovalis	(Canada)

 GBIF record 3017942703	Sturnus vulgaris	(Canada)

 GBIF record 3017942729	Cygnus buccinator	(Canada)

 GBIF record 3017942734	Pseudotsuga menziesii	(Canada)

 GBIF record 3017942802	Anas	(Canada)

 GBIF record 3017942805	Rhytidiadelphus loreus	(Canada)