Retrieve a classification structure (levels and concepts) from a supported service

Source: R/dataStructure.R

Queries the selected service (e.g., CELLAR or FAO) to retrieve the structure of a classification scheme (levels, depth, and concept rows), with language-aware label fallback. You can return a compact summary table, a detailed concept-level table, or both.

The function first resolves the input classification using the in-package registry returned by classificationList(), then retrieves the structure and returns it as data frames. Network errors are handled with retry logic.

dataStructure(
  endpoint,
  prefix,
  conceptScheme = NULL,
  language = "en",
  showQuery = FALSE,
  return = c("summary", "details", "both"),
  timeout_sec = 60,
  retries = 3
)

Arguments

endpoint

Character scalar. Accepted values are "CELLAR" or "FAO".

prefix

Character. A classification prefix used in the registry (e.g. "NACE", "CPA", "CN2022"). Used to resolve the scheme.

conceptScheme

Character or NULL. Optional alternative identifier for the concept scheme. The resolver tries both prefix and conceptScheme using basic normalization (case-insensitive; dot removal).

language

Character scalar. Two-letter language code used to select labels (default: "en"). Fallback chain: requested language -> English ("en") -> no-language literal -> the local resource name.

showQuery

Logical. If TRUE, the generated queries are emitted via message() and also included in the returned list.

return

One of c("summary", "details", "both"). Controls which table(s) are fetched and returned.

timeout_sec

Numeric. HTTP timeout in seconds. Default: 60.

retries

Integer. Number of automatic retries on transient HTTP errors. Default: 3.

Value

A data.frame (for "summary" or "details"), or a list(summary, details) when return = "both".

Columns:

  • All returned tables include a leading Prefix column (lower-case token).

  • summary: Concept_Scheme, Depth, Level, Count.

  • details: Concept, Code, Label, Depth, Level, BroaderList, BroaderCodeList.

If showQuery = TRUE, the return value is a list containing:

  • resolved: metadata (endpoint, inputs, scheme_id, ns_uri, and optionally title)

  • the query text (one or two elements depending on return)

  • the retrieved table(s)

Details

Resolution of the scheme

The function calls classificationList(endpoint) and tries to match either prefix or conceptScheme using normalized keys. On success it extracts the classification namespace and scheme identifier needed to compose requests.

Language fallback

Labels for both the classification levels and concepts follow a multi-step fallback: requested language -> "en" -> no-language literal -> local name.

Errors and Warnings

  • Errors if endpoint is not "CELLAR" or "FAO", or if the scheme cannot be resolved from the registry.

  • Warns (and still returns rows) if no explicit levels are declared.

  • Propagates HTTP errors from the service after retry policy.

Examples

if (FALSE) { # \dontrun{
ds_cn <- dataStructure(
  endpoint      = "CELLAR",
  prefix        = "cn2022",
  conceptScheme = "cn2022",
  language      = "en",
  return        = "summary"
)
head(ds_cn)
} # }