Getting started

Install and load

# From GitHub
install.packages("ineptr2")

library(ineptr2)

Create a client

The INEClient object holds your configuration — language, caching preferences, timeouts — so you don’t have to repeat them on every call.

ine <- INEClient$new(lang = "EN")
ine

You can change settings at any time:

ine$lang <- "PT"
ine$lang <- "EN"

Inspect an indicator

Suppose you want to work with indicator "0008273" (Resident population). Start by checking what it contains:

ine$info("0008273")

This shows the indicator name, periodicity, time range, last update date, and a breakdown of dimensions with their sizes.

For more detail on each dimension, use get_dim_info():

ine$get_dim_info("0008273")

To see the actual values available in each dimension:

# All dimensions
vals <- ine$get_dim_values("0008273")
head(vals)

# Only dimensions 1 and 3
ine$get_dim_values("0008273", dims = c(1, 3))

The categ_cod column contains the codes you pass to get_data() as dimension filters.

Preview before downloading

Before fetching data, you can check how many API requests will be needed. 1 API request = 1 chunk:

ine$preview_chunks("0008206")

This is especially useful for large indicators. You can also preview with filters to see how they reduce the number of chunks:

ine$preview_chunks("0008206", dim1 = "S7A2023")

Fetch data

The simplest way to get data is get_data(), which downloads and processes in one step:

df <- ine$get_data("0008273", dim1 = "S7A2023", dim2 = c("PT", "1", "2", "3"))
head(df)

Dimension filters use the categ_cod values from get_dim_values(). If you omit a dimension, all values are returned.

Download large indicators

For large indicators, you may prefer to download first and load later. This streams data to disk without holding it in memory:

ine$use_cache <- TRUE
ine$cache_dir <- file.path(tempdir(), "ineptr2_vignette")
ine$download_data("0008273", dim1 = "S7A2023")

If a download is interrupted, calling download_data() again resumes from where it left off.

Load the raw data later (even in a new session):

raw <- ine$load_raw_data("0008273")
str(raw, max.level = 2)

Enable caching

By default, every call hits the API. Enable caching to avoid redundant requests:

ine$use_cache <- TRUE

With caching on, get_data() stores the processed result. Subsequent calls with the same or narrower filters are served from cache. See the How caching works article for details.

Check for updates

If you’ve previously downloaded data and want to know whether the indicator has been updated since:

ine$is_updated("0008273", metadata = ine$get_metadata("0008273"))
# OR
ine$is_updated("0008273", last_updated = "2024-01-01")

Assuming you had cached metadata for indicator 0008206, the field DataUltimaAtualizacao would be used. Alternatively, provide a specific last_updated date.

Validate an indicator

Not sure if an indicator code exists?

ine$is_valid("0008273")
ine$is_valid("0000000")

Browse the indicator catalog

Not sure which indicator you need? You can download the full INE catalog — a table with all 13,000+ indicators, their codes, names, and themes:

ine$download_catalog()
catalog <- ine$get_catalog()
head(catalog)

The catalog download is slow (~10 minutes) but is cached on disk, so subsequent calls return instantly.

Switch language

All output, including dimension labels and descriptions, follows the client’s language setting:

ine_pt <- INEClient$new(lang = "PT")
ine_pt$info("0008273")

Clear cache

No longer need the indicator? Clean the cache on your way out.

# cleanup - single indicator
ine$clear_cache("0008273")

# everything
# WARNING: This will remove `cache_dir` and all its contents.
ine$clear_cache()