This function provides a high-level interface to download observation data from the Minka-SDG API. It automatically handles pagination and rate limits by subdividing large queries by month or day.
Usage
mnk_obs(
query = NULL,
taxon_name = NULL,
taxon_id = NULL,
user_id = NULL,
project_id = NULL,
place_id = NULL,
endemic = NULL,
introduced = NULL,
threatened = NULL,
quality = NULL,
geo = NULL,
annotation = NULL,
year = NULL,
month = NULL,
day = NULL,
bounds = NULL,
quiet = FALSE,
limit_download = TRUE
)Arguments
- query
A generic query string for the 'q' parameter in the API. The exact behavior is not specified by the API documentation.
- taxon_name
A character string for the taxon name (common or scientific).
- taxon_id
A numeric ID for the taxon.
- user_id
A numeric ID for a specific user.
- project_id
A numeric ID for a specific project.
- place_id
A numeric ID for a specific place.
- endemic
A logical value (`TRUE`/`FALSE`). Filter for endemic species.
- introduced
A logical value (`TRUE`/`FALSE`). Filter for introduced species.
- threatened
A logical value (`TRUE`/`FALSE`). Filter for threatened species.
- quality
A character string. Must be either "casual" or "research".
- geo
A logical value. If `TRUE`, filters for observations with geographic coordinates.
- annotation
A numeric vector of length 2 (`c(term_id, term_value_id)`). The exact IDs for terms and values are not specified.
- year
A numeric value for the year.
- month
A numeric value for the month (1-12).
- day
A numeric value for the day (1-31).
- bounds
An object representing a bounding box. Can be an `sf` object or a numeric vector of 4 elements in the order: `c(nelat, nelng, swlat, swlng)`.
- quiet
A logical value. If `TRUE`, all console messages during download will be suppressed. Defaults to `FALSE`.
- limit_download
A logical value. If `TRUE` (default), the download is capped at 10,000 records. If `FALSE`, it attempts to download all matching records.
Value
A `tibble::tibble` containing the downloaded observation data, or an empty tibble if no data is found or an error occurs.
Examples
if (FALSE) { # \dontrun{
# Download up to 10,000 observations of "Diplodus sargus" for August 2025 (default limit)
d_sargus <- mnk_obs(taxon_name = "Diplodus sargus", year = 2025, month = 8)
# Attempt to download ALL observations from a project for the entire year 2024
project_data <- mnk_obs(project_id = 419, year = 2024, limit_download = FALSE)
# Download threatened species quietly (up to 10,000)
threatened_data <- mnk_obs(threatened = TRUE, quiet = TRUE)
} # }