Classify a PedonRecord via Embrapa's SmartSolosExpert REST API

Sends a soilKey PedonRecord to the SmartSolosExpert REST endpoint maintained by Embrapa (Glauber Vaz's PROLOG-based implementation of the SiBCS classifier) and returns the resulting four-level classification (Ordem / Subordem / Grande Grupo / Subgrupo) wrapped in a soilKey ClassificationResult.

Usage

classify_via_smartsolos_api(
  pedon,
  api_key = Sys.getenv("AGROAPI_TOKEN"),
  endpoint = c("classification", "verification"),
  drenagem = NULL,
  reference_sibcs = NULL,
  base_url = "https://api.cnptia.embrapa.br/smartsolos/expert/v1",
  timeout_seconds = 30,
  post_fn = NULL,
  verbose = TRUE
)

Arguments

pedon: A PedonRecord.
api_key: Bearer token. Defaults to Sys.getenv("AGROAPI_TOKEN"). Required unless post_fn is supplied (test injection).
endpoint: One of "classification" (default; classify only) or "verification" (classify + compare against user-supplied reference_sibcs).
drenagem: Optional drainage class. Integer 1..8 or Portuguese string ("bem drenado" etc.).
reference_sibcs: Optional named list (ordem, subordem, gde_grupo, subgrupo) used by the "verification" endpoint as the user's reference.
base_url: Override base URL. Default "https://api.cnptia.embrapa.br/smartsolos/expert/v1".
timeout_seconds: HTTP timeout (default 30).
post_fn: Internal: function with signature function(payload) -> response_list for unit tests. When supplied, the network is bypassed.
verbose: If TRUE (default), emits a one-line summary.

Value

A ClassificationResult with system = "SiBCS 5a edicao (SmartSolosExpert API)" and the four taxonomic levels in rsg_or_order (Ordem) and qualifiers (Subordem / GdeGrupo / Subgrupo). Verification-mode responses additionally carry trace$smartsolos_summary (the per-level match counters L0..L4).

Details

This is an **external classifier** – the package does not host or replicate the PROLOG rules. The function exists so soilKey users can cross-validate the local classifier against an authoritative Embrapa-hosted reference. Use the "verification" endpoint to compare against your own user-supplied reference classification (the API returns a per-level match summary with counters L0..L4).

Authentication: register a free AgroAPI account at https://www.agroapi.cnptia.embrapa.br/portal/, subscribe to the SmartSolosExpert API and generate an access token. Pass it via the AGROAPI_TOKEN environment variable or the api_key argument.

References

Vaz, G. J., Silva Neto, L. de F. da, & Barbedo, J. G. A. (2025). SmartSolos Expert: an expert system for Brazilian soil classification. Smart Agricultural Technology, 10, 100735. doi:10.1016/j.atech.2024.100735 .

Vaz, G. J., Silva Neto, L. de F. da, Lima, R. N., & Oliveira, S. R. de M. (2019). Uma API para a classificacao de solos do Brasil. In Anais do 12 Congresso Brasileiro de Agroinformatica (SBIAGRO 2019), pp. 63-72. Ponta Grossa.

Vaz, G. J., Silva Jr, A. F., & Silva Neto, L. de F. da (2023). Brazilian soil data for taxonomic classification. Redape, V1. doi:10.48432/PYKKA7 .

Examples

if (FALSE) { # \dontrun{
Sys.setenv(AGROAPI_TOKEN = "<your token>")
res <- classify_via_smartsolos_api(make_argissolo_canonical())
res$rsg_or_order      # "ARGISSOLO"
res$qualifiers
#> $subordem  "VERMELHO"
#> $gde_grupo "Distrofico"
#> $subgrupo  "tipico"
} # }