Retrieving data

Getting taxonomic information

GBIF.taxon Function

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.occurrence Function

occurrence(key::String)

Returns a GBIF occurrence identified by a key. The key can be given as a string or as an integer (there is a second method for integer keys). In case the status of the HTTP request is anything other than 200 (success), this function will throw an error.

source

Multiple occurrences

GBIF.occurrences Method

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 parameters must be given as pairs, and are optional. Omitting the query will return the latest recorded occurrences for all taxa.

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

Note that this function will return even observations where the "occurrenceStatus" is "ABSENT"; therefore, for the majority of uses, your query will at least contain "occurrenceStatus" => "PRESENT".

source

GBIF.occurrences Method

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

Returns occurrences for a given taxon – the query arguments are the same as the occurrences function.

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.

Query parameters

The queries must be given as pairs of values.

GBIF.occurrences Method

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 parameters must be given as pairs, and are optional. Omitting the query will return the latest recorded occurrences for all taxa.

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

Note that this function will return even observations where the "occurrenceStatus" is "ABSENT"; therefore, for the majority of uses, your query will at least contain "occurrenceStatus" => "PRESENT".

source

GBIF.occurrences Method

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

Returns occurrences for a given taxon – the query arguments are the same as the occurrences function.

source

GBIF.occurrences Method

occurrences(t::Vector{GBIFTaxon}, query::Pair...)

Returns occurrences for a series of taxa – the query arguments are the same as the occurrences function.

source

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