% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/INEClient.R
\name{INEClient}
\alias{INEClient}
\title{INE API Client}
\description{
An R6 class providing access to the Statistics Portugal (INE) API.
Holds configuration state (language, caching preferences) and provides
methods for retrieving data, metadata, and indicator catalog.

See \code{\link{INEClient-fields}} for configurable fields (language,
caching, timeouts, etc.).
}
\section{Data}{

\describe{
\item{\code{get_data(indicator, row_limit, ...)}}{Retrieve tidy data
for an indicator, with automatic chunking and optional caching.}
\item{\code{download_data(indicator, row_limit, ...)}}{Download data to
the file cache without loading into memory.}
\item{\code{load_raw_data(indicator)}}{Load previously downloaded raw
JSON data from the file cache.}
\item{\code{preview_chunks(indicator, row_limit, ...)}}{Preview how many
API chunks a download would require.}
}
}

\section{Metadata}{

\describe{
\item{\code{get_metadata(indicator)}}{Get cleaned metadata for an
indicator.}
\item{\code{info(indicator)}}{Print a summary of an indicator's key
properties.}
\item{\code{get_dim_info(indicator)}}{Get dimension descriptions.}
\item{\code{get_dim_values(indicator, dims)}}{Get possible values for
all dimensions.}
\item{\code{is_valid(indicator)}}{Check if an indicator exists.}
\item{\code{is_updated(indicator, last_updated, metadata)}}{Check if an
indicator has been updated since last download.}
}
}

\section{Catalog}{

\describe{
\item{\code{get_catalog()}}{Download and parse the full indicator
catalog (~10 min).}
\item{\code{download_catalog()}}{Download the catalog to the file
cache.}
}
}

\section{Cache}{

\describe{
\item{\code{list_cached()}}{List indicators present in the file cache.}
\item{\code{clear_cache(indicator)}}{Clear cached files.}
}
}

\examples{
\dontshow{if (identical(Sys.getenv("NOT_CRAN"), "true")) withAutoprint(\{ # examplesIf}
# -- Setup --
ine <- INEClient$new()
ine <- INEClient$new(lang = "EN", use_cache = TRUE)
print(ine)

# -- Metadata --
meta <- ine$get_metadata("0010003")
ine$info("0010003")
dims <- ine$get_dim_info("0010003")
vals <- ine$get_dim_values("0010003")

# -- Data --
df <- ine$get_data("0010003")
df <- ine$get_data("0010003", dim1 = "S7A2024", dim2 = c("11", "17"))
ine$preview_chunks("0008273")

# -- Validation --
ine$is_valid("0010003")
ine$is_updated("0010003", last_updated = "2024-01-01")

# -- Cache --
ine$list_cached()
ine$clear_cache()
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link{INEClient-fields}} for field descriptions.
}
\section{Active bindings}{
\if{html}{\out{<div class="r6-active-bindings">}}
\describe{
\item{\code{lang}}{Language code (\code{"PT"} or \code{"EN"}).}

\item{\code{use_cache}}{Whether caching is enabled.}

\item{\code{cache_dir}}{Cache directory path, or \code{NULL} for default.}

\item{\code{row_limit}}{Default maximum output rows per API request.}

\item{\code{max_retries}}{Maximum retry attempts for chunk downloads.}

\item{\code{progress_interval}}{Print progress every N chunks during downloads.}

\item{\code{timeout}}{Timeout in seconds for API requests.}
}
\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-INEClient-new}{\code{INEClient$new()}}
\item \href{#method-INEClient-get_data}{\code{INEClient$get_data()}}
\item \href{#method-INEClient-download_data}{\code{INEClient$download_data()}}
\item \href{#method-INEClient-load_raw_data}{\code{INEClient$load_raw_data()}}
\item \href{#method-INEClient-get_metadata}{\code{INEClient$get_metadata()}}
\item \href{#method-INEClient-get_catalog}{\code{INEClient$get_catalog()}}
\item \href{#method-INEClient-download_catalog}{\code{INEClient$download_catalog()}}
\item \href{#method-INEClient-info}{\code{INEClient$info()}}
\item \href{#method-INEClient-get_dim_info}{\code{INEClient$get_dim_info()}}
\item \href{#method-INEClient-get_dim_values}{\code{INEClient$get_dim_values()}}
\item \href{#method-INEClient-preview_chunks}{\code{INEClient$preview_chunks()}}
\item \href{#method-INEClient-is_valid}{\code{INEClient$is_valid()}}
\item \href{#method-INEClient-is_updated}{\code{INEClient$is_updated()}}
\item \href{#method-INEClient-list_cached}{\code{INEClient$list_cached()}}
\item \href{#method-INEClient-clear_cache}{\code{INEClient$clear_cache()}}
\item \href{#method-INEClient-print}{\code{INEClient$print()}}
\item \href{#method-INEClient-clone}{\code{INEClient$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-new"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-new}{}}}
\subsection{Method \code{new()}}{
Create a new INE API client.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$new(
  lang = "PT",
  use_cache = FALSE,
  cache_dir = NULL,
  row_limit = 1000000L,
  max_retries = 3L,
  progress_interval = 10L,
  timeout = 300
)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{lang}}{Language code: \code{"PT"} (default) or \code{"EN"}.}

\item{\code{use_cache}}{Logical. Whether to cache API responses. Default \code{FALSE}.}

\item{\code{cache_dir}}{Character or \code{NULL}. Cache directory path.
If \code{NULL} (default), uses \code{tools::R_user_dir("ineptr2", "cache")}.}

\item{\code{row_limit}}{Integer. Default maximum output rows per API request.
Default \code{1000000L}.}

\item{\code{max_retries}}{Integer. Maximum retry attempts for failed chunk
downloads. Default \code{3L}.}

\item{\code{progress_interval}}{Integer. Print a progress message every N chunks
during downloads. Default \code{10L}.}

\item{\code{timeout}}{Numeric. Timeout in seconds for API requests (metadata
and data endpoints). Default \code{300} (5 minutes). The catalog endpoint
uses a separate, longer timeout.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A new \code{INEClient} object.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-get_data"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-get_data}{}}}
\subsection{Method \code{get_data()}}{
Retrieve tidy data for an indicator.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$get_data(indicator, row_limit = NULL, ...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}

\item{\code{row_limit}}{Integer or \code{NULL}. Maximum output rows per API request
before splitting into multiple calls. If \code{NULL} (default), uses the
client's \code{row_limit} field. See \strong{Details}.}

\item{\code{...}}{Dimension filters. Each argument should be named \code{dimN}
(where N is the dimension number) with a character vector of values.
Omitted dimensions include all values.}
}
\if{html}{\out{</div>}}
}
\subsection{Details}{
\subsection{Row limit and chunking}{

The INE API limits each request to \strong{1 000 000 output rows}, counted
as the product of unique values across all dimensions. When the
estimated row count exceeds \code{row_limit}, the request is automatically
split into smaller chunks by iterating over one or more dimensions.

If requests are timing out, try lowering \code{row_limit} (or increasing
the client's \code{timeout} field) to produce more, smaller chunks.
}

\subsection{Caching}{

When \code{use_cache} is enabled, processed data is stored as an RDS file.
Subsequent calls with the same or narrower dimension filters return
the cached result without hitting the API. Changing filters to
include values outside the cached set triggers a fresh download.
}
}

\subsection{Returns}{
A data frame with the indicator data.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-download_data"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-download_data}{}}}
\subsection{Method \code{download_data()}}{
Download data for an indicator to the file cache without
loading it into memory. Caching is temporarily enabled for the
duration of the call regardless of the client's \code{use_cache} setting.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$download_data(indicator, row_limit = NULL, ...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}

\item{\code{row_limit}}{Integer or \code{NULL}. Maximum output rows per API request
before splitting into multiple calls. If \code{NULL} (default), uses the
client's \code{row_limit} field.}

\item{\code{...}}{Dimension filters in the form \code{dimN = value}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly, a list with \code{indicator}, \code{cache_dir}, \code{total_chunks},
and \code{complete}, or \code{invisible(NULL)} on partial download failure
(resume by calling again).
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-load_raw_data"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-load_raw_data}{}}}
\subsection{Method \code{load_raw_data()}}{
Load previously downloaded raw data from the file cache
as a list of parsed JSON responses. Use \code{download_data()} first to
populate the cache.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$load_raw_data(indicator)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A list with \code{responses} (parsed JSON) and \code{urls}.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-get_metadata"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-get_metadata}{}}}
\subsection{Method \code{get_metadata()}}{
Get cleaned metadata for an indicator.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$get_metadata(indicator)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
API response body as a list.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-get_catalog"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-get_catalog}{}}}
\subsection{Method \code{get_catalog()}}{
Get the full INE indicator catalog.
This operation is very time-consuming (~10 minutes) as it downloads
the entire catalog from the INE API. Consider using \code{download_catalog()}
to cache the result for subsequent calls.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$get_catalog()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
A data frame with one row per indicator.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-download_catalog"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-download_catalog}{}}}
\subsection{Method \code{download_catalog()}}{
Download the INE indicator catalog to the file cache
without loading it into memory. This operation is time-consuming
(~10 minutes) as it downloads the entire catalog from the INE API.
Subsequent calls return the cached file immediately. Caching is
temporarily enabled for the duration of the call regardless of
the client's \code{use_cache} setting.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$download_catalog()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
Invisibly, the cache file path.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-info"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-info}{}}}
\subsection{Method \code{info()}}{
Print a summary of an indicator's key properties:
code, name, periodicity and time range, last update date,
and a per-dimension breakdown of unique values.
Labels are displayed in the client's current language.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$info(indicator)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly, a list with \code{code}, \code{name}, \code{periodicity},
\code{first_period}, \code{last_period}, \code{last_updated}, and
\code{dimensions} (a data frame with \code{dim_num}, \code{name}, and
\code{n_values} columns).
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-get_dim_info"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-get_dim_info}{}}}
\subsection{Method \code{get_dim_info()}}{
Get dimension descriptions for an indicator.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$get_dim_info(indicator)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A data frame with dim_num, abrv, and versao columns.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-get_dim_values"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-get_dim_values}{}}}
\subsection{Method \code{get_dim_values()}}{
Get possible values for all dimensions of an indicator.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$get_dim_values(indicator, dims = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}

\item{\code{dims}}{Integer vector of dimension numbers to include,
or \code{NULL} (default) for all dimensions.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A tidy data frame with dimension values.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-preview_chunks"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-preview_chunks}{}}}
\subsection{Method \code{preview_chunks()}}{
Preview how many API chunks a download would require,
without fetching any data. Useful for estimating download time
before committing to a large request.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$preview_chunks(indicator, row_limit = NULL, ...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}

\item{\code{row_limit}}{Integer or \code{NULL}. Maximum output rows per API request
before splitting into multiple calls. If \code{NULL} (default), uses the
client's \code{row_limit} field.}

\item{\code{...}}{Dimension filters in the form \code{dimN = value}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly, a list with \code{chunks} and \code{estimated_rows}.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-is_valid"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-is_valid}{}}}
\subsection{Method \code{is_valid()}}{
Check if an indicator exists and is callable via the INE API.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$is_valid(indicator)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{TRUE} if indicator exists, \code{FALSE} otherwise.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-is_updated"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-is_updated}{}}}
\subsection{Method \code{is_updated()}}{
Check if an indicator has been updated since last download.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$is_updated(indicator, last_updated = NULL, metadata = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{INE indicator ID as a 7-digit string. Example: \code{"0010003"}.}

\item{\code{last_updated}}{A \code{Date} object or a character string in \code{"YYYY-MM-DD"} format.
If provided, takes precedence over cached metadata. If \code{NULL} (default),
the function looks for cached metadata or the \code{metadata} argument.}

\item{\code{metadata}}{A metadata list object as returned by \code{get_metadata()}.
If provided and \code{last_updated} is \code{NULL}, extracts \code{DataUltimaAtualizacao}.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
\code{TRUE} if updated, \code{FALSE} if not.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-list_cached"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-list_cached}{}}}
\subsection{Method \code{list_cached()}}{
List indicators present in the file cache.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$list_cached()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
A data frame with one row per cached indicator and columns
\code{indicator}, \code{has_metadata}, \code{has_data}, \code{chunks_downloaded},
\code{chunks_total}, and \code{download_complete}. Returns a zero-row data
frame if no cache exists.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-clear_cache"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-clear_cache}{}}}
\subsection{Method \code{clear_cache()}}{
Clear cached files.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$clear_cache(indicator = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{indicator}}{Optional INE indicator ID. If \code{NULL} (default), clears all cached files.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns \code{TRUE} if files were removed, \code{FALSE} otherwise.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-print"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-print}{}}}
\subsection{Method \code{print()}}{
Print a summary of the client configuration.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$print(...)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{...}}{Ignored.}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-INEClient-clone"></a>}}
\if{latex}{\out{\hypertarget{method-INEClient-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{INEClient$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}
