Introduction to inkaR

Overview

The inkaR package provides a modern, user-friendly interface to access statistical data from the BBSR INKAR database (Indikatoren und Karten zur Raum- und Stadtentwicklung).

Key features include: - Easy Data Access: Download data using simple IDs or short codes. - Bilingual Support: Work with metadata in German (default) or English. - Offline Search: Quickly find indicators without needing to query the API repeatedly. - Direct Export: Save data directly to CSV files matching your workflow.

Installation

You can install the package from your local source or GitHub:

# If installing from local source
devtools::install()
library(inkaR)

1. Finding Indicators

The INKAR database contains hundreds of indicators. inkaR provides tools to find what you need.

# Opens a viewer in RStudio
view_indicators()

# View English metadata
view_indicators(lang = "en")

# Search in English names/descriptions
search_indicators("GDP", lang = "en")

# Search in German (default)
search_indicators("Arbeitslosigkeit")

2. Downloading Data

Use get_inkar_data() to fetch statistics. You need: 1. variable: The indicator ID (e.g., “011” for GDP). 2. level: The spatial level (e.g., “KRE” for Districts/Kreise).

# Download GDP (011) for Districts (KRE) for the latest available year
df <- get_inkar_data("011", level = "KRE")
head(df)

# Single year
df_2021 <- get_inkar_data("011", level = "KRE", year = 2021)

# Year range
df_range <- get_inkar_data("011", level = "KRE", year = 2015:2020)

df_en <- get_inkar_data("011", level = "KRE", lang = "en")
# Columns: region_id, region_name, indicator_name, year, value

3. Exporting Data

You can save the retrieved data directly to a CSV file. The filename is automatically generated based on the indicator name, level, and timestamp.

# Download and save immediately
get_inkar_data("011", level = "KRE", csv = TRUE, export_dir = tempdir())

# Output: Data saved to: inkar_011_KRE_Bruttoinlandsprodukt_....csv

4. Mapping Data (Geospatial Integration)

inkaR includes a built-in wrapper to easily visualize regional data on German administrative maps using the ggplot2, sf, and geodata packages.

If you have those packages installed, you can map Kreise (Districts) or Länder (States) with a single command:

# Download GDP for Kreise
df <- get_inkar_data("011", level = "KRE", year = 2021)

# Plot the data on a map
plot_inkar(df)

Note: plot_inkar() automatically downloads high-quality polygon boundaries from the GADM database on the first run and joins them to your INKAR data using the Kennziffer IDs.

5. Advanced Features & Architecture

inkaR uses advanced engineering to ensure the package is exceptionally fast and resilient:

1. Persistent Disk Caching (tools::R_user_dir) The INKAR API can take 15+ seconds to resolve the spatial dimensions (SelectLevel) for a complex indicator (e.g. GDP). inkaR queries the API once and caches the configuration to your hard drive permanently. Future R sessions will read this disk-cache in < 0.1 seconds. Caches expire every 24 hours automatically. You can manually reset it using clear_inkar_cache().
2. Parallel Probing (httr2::req_perform_parallel) When inkaR queries spatial levels from the server, it dispatches 6 asynchronous requests simultaneously. This concurrent approach slashes wait times from 15 seconds down to under 2 seconds.
3. Offline Resiliency (httptest2) The entire test suite (testthat) is fully mocked using httptest2. Tests will pass reliably in offline environments (like strict CI/CD servers or airplanes) without depending on the fragile INKAR backend.

Reference: Spatial Levels

Common spatial levels include: - KRE: Districts (Kreise / Kreisfreie Städte) - GEM: Municipalities (Gemeinden) - ROR: Spatial Planning Regions (Raumordnungsregionen) - BLD: Federal States (Bundesländer) - BND: Federal Territory (Bund)

Use get_geographies() to see all available levels.