# Introduction to rbiodatacr

## Overview

`rbiodatacr` is an R client for querying BIODATACR, the national biodiversity information platform of Costa Rica managed by the Technical Office of CONAGEBIO. The platform is built on the Atlas of Living Australia (ALA) API infrastructure.

    library(rbiodatacr)
    library(dplyr)
    library(sf)
    library(ggplot2)

## 1. Taxonomic search

Before downloading occurrence records, use `bdcr_species_search()` to verify that the species name is recognized by BIODATACR and to retrieve its taxonomic identifier (GUID).

    bdcr_species_search("Panthera onca")

The function may return more than one row when both the species and subspecies are registered. The `guid` column contains the unique identifier for each taxonomic concept — useful for precise queries.

## 2. Counting records

Use `bdcr_count()` to check how many occurrence records are available before downloading.

    bdcr_count("Panthera onca")

For multiple species at once use `bdcr_count_batch()`, which returns a tidy tibble with one row per species.

    species <- c(
      "Tapirus bairdii",
      "Panthera onca",
      "Ara ambiguus",
      "Bradypus variegatus"
    )

    conteos <- bdcr_count_batch(species)
    conteos

## 3. Downloading occurrence records

`bdcr_occurrences()` downloads records for a single species and returns a tibble with 15 fields relevant for biodiversity analysis.

    df_jaguar <- bdcr_occurrences("Panthera onca", rows = 100)
    glimpse(df_jaguar)

For multiple species use `bdcr_occurrences_batch()`, which returns a named list of tibbles — one per species.

    spp_with_data <- filter(conteos, n_records >= 10)

    lista_occ <- bdcr_occurrences_batch(
      taxa = spp_with_data$taxon,
      rows = 100
    )

    # Number of records per species
    purrr::map_int(lista_occ, nrow)

## 4. Quality control

`bdcr_quality_check()` adds a `quality_flag` column to the occurrences tibble. Possible flags are:

Flag | Condition
--- | ---
`"ok"` | No issues detected
`"no_coords"` | Missing coordinates
`"geospatial_issue"` | `geospatialKosher == FALSE`
`"taxonomic_issue"` | `taxonomicKosher == FALSE`
`"old_record"` | Year before minimum threshold (default 1950)

    df_qc <- bdcr_quality_check(df_jaguar)

    count(df_qc, quality_flag, sort = TRUE)

Keep only clean records:

    df_clean <- filter(df_qc, quality_flag == "ok",
                             !is.na(decimalLatitude),
                             !is.na(decimalLongitude))
    nrow(df_clean)

## 5. Mapping occurrence records

Convert the clean tibble to an `sf` object and plot the records over Costa Rica.

    # Convert to sf
    df_sf <- st_as_sf(
      df_clean,
      coords = c("decimalLongitude", "decimalLatitude"),
      crs    = 4326
    )

    # Load Costa Rica national boundary included in rbiodatacr
    # Source: GADM (gadm.org), level 0 = country boundary
    data(cr_outline)

    # Map
    ggplot() +
      geom_sf(data = cr_outline, fill = "gray95", color = "gray50") +
      geom_sf(data = df_sf, color = "#E63946", size = 2, alpha = 0.7) +
      labs(
        title    = "Panthera onca — BIODATACR occurrence records",
        subtitle = paste0(nrow(df_sf), " clean records"),
        caption  = "Source: BIODATACR (biodiversidad.go.cr)",
        x = "Longitude",
        y = "Latitude"
      ) +
      theme_minimal()

## 6. Complete workflow

    # 1. Check availability
    species <- c("Tapirus bairdii", "Panthera onca",
                 "Ara ambiguus",    "Bradypus variegatus")

    conteos <- bdcr_count_batch(species)

    # 2. Download species with enough data
    con_datos <- filter(conteos, n_records >= 10)

    lista_occ <- bdcr_occurrences_batch(
      taxa = con_datos$taxon,
      rows = 200
    )

    # 3. Quality control
    lista_limpia <- purrr::map(lista_occ, bdcr_quality_check)

    # 4. Consolidate and filter
    df_final <- bind_rows(lista_limpia, .id = "taxon") |>
      filter(quality_flag == "ok",
             !is.na(decimalLatitude),
             !is.na(decimalLongitude))

    # 5. Summary
    df_final |>
      count(taxon, sort = TRUE) |>
      rename(clean_records = n)