Represents an occurrence in the GBIF format

This is currently a subset of all the fields. This struct is not mutable – this ensures that the objects returned from the GBIF database are never modified by the user.

The taxon field is a GBIFTaxon object, and can therefore be manipulated as any other GBIFTaxon.

Generates an occurrence from the JSON response of GBIF

List of occurrences and metadata

This type has actually very few information: the query field stores the query parameters. This type is mutable and fully iterable.

The occurrences field is pre-allocated, meaning that it will contain #undef elements up to the total number of hits on GBIF. When iterating, this is taken care of automatically, but this needs to be accounted for if writing code that accesses this field directly.

Representation of a GBIF taxon

All taxonomic level fields can either be missing, or a pair linking the name of the taxon/level to its unique key in the GBIF database.

name - the vernacular name of the taxon

scientific - the accepted scientific name of the species

status - the status of the taxon

match - the type of match

kingdom - a Pair linking the name of the kingdom to its unique ID

phylum - a Pair linking the name of the phylum to its unique ID

class - a Pair linking the name of the class to its unique ID

order - a Pair linking the name of the order to its unique ID

family - a Pair linking the name of the family to its unique ID

genus - a Pair linking the name of the genus to its unique ID

species - a Pair linking the name of the species to its unique ID

confidence - an Int64 to note the confidence in the match

synonym - a Boolean indicating whether the taxon is a synonym

Show several occurrences

show(io::IO, o::GBIFRecords)

Displays the total number, and the number of currently unmasked records.

Show an occurrence

show(io::IO, o::GBIFRecord)

Displays the key, the taxon name, and the country of observation.

Show a taxonomic record

show(io::IO, t::GBIFTaxon)

Displays the taxon name.

enumerablevalues()

Returns an array of values that can be enumerated by the GBIF API.

enumeratedvalues(enumerable::String)

For a given enumerable value (given as a string as reported by the output of the enumerablevalues function), this function will return an array of possible values.

Internal function to format dates in records

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.

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.

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

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

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

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

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

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.

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.

validate_occurrence_query(query::Pair)

Checks that the queries for occurrences searches are well formatted.

This is used internally.

Everything this function does is derived from the GBIF API documentation, including (and especially) the values for enum types. This modifies the queryset. Filters that are not allowed are removed, and filters that have incorrect values are dropped too.

This feels like the most conservative option – the user can always filter the results when they are returned.