% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/retrieveCorrespondenceTable.R
\name{retrieveCorrespondenceTable}
\alias{retrieveCorrespondenceTable}
\title{Download a correspondence (mapping) table between two classifications}
\usage{
retrieveCorrespondenceTable(
  endpoint,
  prefix,
  ID_table,
  language = "en",
  showQuery = FALSE
)
}
\arguments{
\item{endpoint}{Character. The online service to query. Case-insensitive.
Supported values are those returned by the internal endpoint registry
(e.g., \code{"CELLAR"}, \code{"FAO"}).}

\item{prefix}{Character. Catalogue prefix where the correspondence is
published (e.g., \code{"nace2"}, \code{"cpa21"}, \code{"cn2022"}).
Use \code{\link{correspondenceTableList}()} to discover valid values.}

\item{ID_table}{Character. Identifier of the correspondence, typically of
the form \code{"A_B"} such as \code{"NACE2_CPA21"} or \code{"CN2022_NACE2"}.
Discover identifiers via \code{\link{correspondenceTableList}()}.}

\item{language}{Character. Preferred label language as a BCP‑47 code.
Defaults to \code{"en"} (English). Examples: \code{"fr"}, \code{"de"}.}

\item{showQuery}{Logical. If \code{TRUE}, returns a list with the SPARQL
query and the result data frame; otherwise (default) returns just the data frame.}
}
\value{
A \code{data.frame} where each row represents one mapping from the source
classification (\strong{A}) to the target classification (\strong{B}).

Columns (when available):
\itemize{
  \item \code{CorrespondenceID}:  Requested identifier (e.g., \code{"NACE2_CPA21"}).
  \item \code{Prefix}: Catalogue prefix (constant per table).
  \item \code{A}: Source code (\code{A} parsed from \code{ID_table}).
  \item \code{B}: Target code (\code{B} parsed from \code{ID_table}).
  \item \code{Label_A}, \code{Label_B}: Human‑readable labels in \code{language}.
  \item \code{Include_A}, \code{Exclude_A}, \code{Include_B}, \code{Exclude_B}: Notes, if available.
  \item \code{Comment}: Free‑text comment on the mapping, if any.
  \item \code{URL}: URI of the mapping association.
}

Attributes attached for traceability:
\itemize{
  \item \code{endpoint}, \code{endpoint_url}, \code{prefix}, \code{ID_table}
  \item \code{A}, \code{B}, \code{language}, \code{normalized_codes}, \code{anchor_mode}, \code{anchor}
}
}
\description{
Downloads a correspondence table, a mapping of codes, from one statistical
classification (A) to another (B) from an online service (CELLAR or
FAO), and returns it as a plain data frame. The function has no side effects
(it does not read or write files).

A correspondence table tells you which codes in classification A relate
to which codes in classification B (e.g., \code{NACE2} → \code{CPA21}).
}
\details{
\strong{When to use this.} Use \code{retrieveCorrespondenceTable()} when you
know (or have discovered) the \code{prefix} and \code{ID_table} of a
correspondence and want the mapping rows as a standard data frame.

\strong{How it works (short).}
\enumerate{
  \item Validates the selected service (\code{endpoint}).
  \item Optionally resolves a stable anchor via \code{\link{correspondenceTableList}()}.
  \item Builds a SPARQL query returning source/target codes, labels, notes, and link URI.
  \item Issues an HTTP request and parses the response into a data frame.
}
}
\section{Notes}{

\itemize{
  \item The function focuses on retrieval. Any code normalization is left to
        downstream steps.
}
}

\examples{
\dontrun{
# 1) Discover available correspondences at CELLAR
ct <- correspondenceTableList(endpoint = "CELLAR")
subset(ct, grepl("NACE2", ID) & grepl("CPA21", ID))

# 2) Retrieve one correspondence (English labels)
x <- retrieveCorrespondenceTable(
  endpoint = "CELLAR",
  prefix   = "nace2",
  ID_table = "NACE2_CPA21",
  language = "en"
)
head(x)

# 3) Save to CSV explicitly if needed (no automatic writing)
# utils::write.csv(x, "NACE2_CPA21.csv", row.names = FALSE)

# 4) Inspect the generated SPARQL query
dbg <- retrieveCorrespondenceTable(
  endpoint = "FAO",
  prefix   = "cpa21",
  ID_table = "NACE2_CPA21",
  showQuery = TRUE
)
message(substr(dbg$SPARQL.query, 1, 400), "...")
}

}
