flags: Geospatial Quality Flags
Description
This document describes how the Geospatial Quality API (service for which
this package works as a wrapper) works. Specifically, it describes the data
input format and enumerates and briefly describes the possible geospatial
quality flags that the API returns.
Input
The API operates on Primary Biodiversity Records, i.e., the most basic,
interpretation-free pieces of information about the occurrence of an
organism (taxonomic identification, or "what") in a specific place
(geospatial location, or "where") and a moment in time (temporal location,
or "when"). It feeds on a single record or a set of records that describe
such occurrence. Specifically, the geospatial issues service works with the
"what" and the "where", meaning it is more useful if such pieces of
information are provided to the API. While there is no minimum set of required values to pass to the service in
order for it to work, the amount of tests to be performed depends on the
information provided. One can simply call the base URL and it will return a
set of empty fields. To fully leverage the potential of the API, however, a
user should send a well-defined set of values. These values must conform to
the DarwinCore Standard, and
currently, the API works on these variables:
- decimalLatitude
- Value for the Latitude in decimal degrees
format (e.g. 42.332)
- decimalLongitude
- Value for the Longitude in
decimal degrees format (e.g. -1.833)
- countryCode
- 2 character ISO
code for the country
- scientificName
- Species the record belongs to
Caveat: while the API accepts scientific names as specified in the
DarwinCore Standard, currently some tools only work if the
"Genus"+"Specific Epithet" binomial is provided in this field. Thus,
instead of "Puma concolor (Linnaeus, 1771)", we recommend using just "Puma
concolor" in the 'scientificName' field. When working with multiple records (using the add_flags
function in this package), the API accepts more than just these fields. One
can send a data.frame with as many columns as he/she wants, and the API
will just by-pass them. They will be presented in the output, though, so it
is a good practice to include a field with any type of identification (like
an occurrenceID).Output format
The output of the API will always be a JSON document, which will be
transformed into a data.frame in this package. Actually, the API will
return the same document that was provided, with the addition of the flags
element. This new element contains the results of the geospatial and
spatio-taxonomic checks the API has performed. The attributes in this flags
element are one or more of these (depending on the information provided): - hasCoordinates
- always. TRUE if coordinates have been sent to the
API. FALSE otherwise.
- hasCountry
- always. TRUE if a country value has been sent to the API.
FALSE otherwise.
- hasScientificName
- always. TRUE if a scientific name has been sent to
the API. FALSE otherwise.
- validCoordinates
- only if hasCoordinates is TRUE. TRUE if supplied
values conform to the natural limits of coordinates. FALSE otherwise.
- validCountry
- only if hasCountry is TRUE. TRUE if supplied value
corresponds to an existing 2-character code for a country. FALSE
otherwise.
- highPrecisionCoordinates
- only if validCoordinates is TRUE. TRUE if
coordinates have at least 3 decimal figures. FALSE otherwise.
- nonZeroCoordinates
- only if validCoordinates is TRUE. FALSE if both
coordinates are 0. TRUE otherwise.
- coordinatesInsideCountry
- Only if validCoordinates and validCountry
are TRUE. TRUE if coordinates fall inside the specified country. FALSE
otherwise.
- transposedCoordinates
- Only if coordinatesInsideCountry is FALSE.
TRUE if swapping the coordinates makes them right. FALSE otherwise. This
operation can be performed along negatedLatitude and negatedLongitude.
- negatedLatitude
- Only if coordinatesInsideCountry is FALSE. TRUE if
negating the latitude makes coordinates right. FALSE otherwise. This
operation can be performed along transposedCoordinates and
negatedLongitude.
- negatedLongitude
- Only if coordinatesInsideCountry is FALSE. TRUE if
negating the longitude makes coordinates right. FALSE otherwise. This
operation can be performed along transposedCoordinates and
negatedLatitude.
- distanceToCountryInKm
- Only if coordinatesInsideCountry,
transposedCoordinates, negatedLatitude and negatedLongitude are FALSE. This
will show the distance to the closest point of the country boundaries, in
Km.
- coordinatesInsideRangeMap
- Only if hasScientificName and
validCoordinates are TRUE. TRUE if coordinates fall inside the IUCN range
map for the specified species. FALSE otherwise.
- distanceToRangeMapInKm
- Only if coordinatesInsideRangeMap is FALSE.
This will show the distance to the closest point of the species range map,
in Km.