Introduction to inkaR

Overview

The inkaR package provides a modern R interface to the BBSR INKAR database, Indikatoren und Karten zur Raum- und Stadtentwicklung (Indicators and Maps for Spatial and Urban Development). INKAR is published by the German Federal Institute for Research on Building, Urban Affairs and Spatial Development (BBSR) and contains hundreds of regional indicators at multiple spatial levels across Germany.

Key features:

Installation

# From GitHub
remotes::install_github("ofurkancoban/inkaR")

library(inkaR)

1. Browsing Indicators

The INKAR database contains hundreds of indicators. inkaR ships a local metadata table (indicators) so you can explore and filter without hitting the API.

View the full list

Opens a searchable, sortable table in the RStudio viewer:

view_indicators()          # German names (default)
view_indicators("en")      # English names

Search by keyword

search_indicators("GDP", lang = "en")
search_indicators("Arbeitslosigkeit")   # German search

Each result shows the ID (short code) and M_ID (numeric API key) you need to download data.

Retrieve as a data frame

df_meta <- get_indicators("en")
head(df_meta)

2. Interactive Wizard

For guided, step-by-step downloads, especially useful in the RStudio console:

# Step 1 – pick an indicator (searchable menu)
id <- select_indicator(lang = "en")

# Step 2 – pick the spatial level (e.g. KRE, GEM, BLD)
level <- select_level(id)

# Step 3 – pick the year(s)
years <- select_years(id, level)

# Step 4 – download
df <- get_inkar_data(id, level = level, year = years, lang = "en")

Each step can also be called independently when you already know some parameters:

select_indicator("employment")   # pre-filters by keyword before showing the menu

3. Downloading Data

get_inkar_data() is the main download function.

Basic download

# GDP (ID "011") for Districts (Kreise), latest available year
df <- get_inkar_data("011", level = "KRE")
head(df)
#>   Kennziffer        Raumeinheit Aggregat  Zeit              Indikator     Wert
#> 1      01001    Flensburg (KSt)      KRE  2022 Bruttoinlandsprodukt_... 1234.5

Specify year(s)

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

# Range of years
df_range <- get_inkar_data("011", level = "KRE", year = 2015:2021)

English output

df_en <- get_inkar_data("011", level = "KRE", year = 2021, lang = "en")
head(df_en)
#>   region_id        region_name level_name year         indicator_name   value
#> 1     01001  Flensburg (KSt)        KRE  2021  Gross domestic pro... 1234.5

Column names in English mode:

Column Description
region_id Administrative key (Kennziffer)
region_name Region name
level_name Spatial level (e.g. KRE)
year Reference year
indicator_name English indicator label
value Numeric value

Multiple indicators at once

Pass a vector of IDs to download and merge automatically:

df_multi <- get_inkar_data(c("011", "12"), level = "KRE", year = 2021, lang = "en")

# One column per indicator, named by its short ID (e.g. "bip")
df_wide <- get_inkar_data(c("011", "12"), level = "KRE", year = 2021, lang = "en", format = "wide")

By default the indicators are stacked in long format. With format = "wide" they are merged by region and year, one column per indicator. If an indicator cannot be resolved or has no data, it is left out with a warning.

Indicators can be addressed by their short ID from the INKAR indicator overview ("q_alo"), by M_ID ("12") or by INKAR’s official indicator number ("1101"); all three resolve to the same indicator. Topic areas are listed by get_themes().

Export to CSV

get_inkar_data("011", level = "KRE", csv = TRUE, export_dir = tempdir())
# Saves: inkar_011_KRE_Bruttoinlandsprodukt_<timestamp>.csv

4. Spatial Levels

Common levels:

Code German name English
KRE Kreise / Kreisfreie Staedte Districts
GEM Gemeinden Municipalities
ROR Raumordnungsregionen Spatial Planning Regions
BLD Bundeslaender Federal States
BND Bund Federal Territory (Germany)

Not all indicators are available at every level. Use select_level() to see which levels a given indicator supports, or call get_geographies() to list all available levels:

get_geographies()

5. Mapping

plot_inkar() visualizes a downloaded data frame on German administrative boundaries. It requires the ggplot2 and sf packages.

Automatic Maps via Eurostat GISCO

By default, the function uses the municipality boundaries of Eurostat GISCO (LAU 2024), which share INKAR’s territorial status, so every region is drawn. The file (about 43 MB) is downloaded once and cached. Higher levels are built from the municipalities:

Maps carry the attribution “(c) EuroGeographics for the administrative boundaries”. The boundaries are also available directly for your own analysis:

kreise <- get_inkar_geometry("KRE")   # sf object with a Kennziffer column
# Download GDP for Districts
df <- get_inkar_data("011", level = "KRE", year = 2021, lang = "en")

# Plot: light theme (default)
plot_inkar(df)

# Dark theme
plot_inkar(df, mode = "dark")

Below is an example of the dark mode map output generated by plot_inkar():

Dark-mode map of gross domestic product for German districts (Kreise) in 2021, colored with the viridis scale
Dark-mode map of gross domestic product for German districts (Kreise) in 2021, colored with the viridis scale

Custom Geometries

If you want to use custom boundaries (e.g. ROR Raumordnungsregionen, or custom shapefiles), you can pass an sf object directly to the geom parameter. plot_inkar() will skip the boundary download and merge your data with the custom spatial data frame:

# Load your custom spatial data frame (e.g. from an sf shapefile)
# my_shapes <- sf::read_sf("path/to/shapes.shp")

# Plot using custom geometry
# plot_inkar(df, geom = my_shapes)

6. Caching

inkaR caches API responses to your user data directory (tools::R_user_dir("inkaR", "cache")). Caches expire after 24 hours. To clear them manually:

clear_inkar_cache()

7. Analysis Helpers

Filter to specific regions or districts

You can filter downloaded datasets to specific regions using either the plural or singular helpers. For districts, you can also filter by their administrative key (Kennziffer/ID):

df <- get_inkar_data("011", level = "KRE", lang = "en")

# Filter regions (by name)
df_cities <- compare_regions(df, c("Berlin", "Hamburg", "München"))
df_city   <- compare_region(df, "Berlin") # Singular alias

# Filter districts (by name or district ID/Kennziffer)
df_districts <- compare_districts(df, c("01001", "Hamburg"))
df_district  <- compare_district(df, "02000") # Singular alias

Quick Reference

Function Purpose
inkar() English shortcut: latest year, EN output
get_inkar_data() Download indicator data from the API
inkaR() Full-featured download with interactive wizard
view_indicators() Browse all indicators in a viewer table
search_indicators() Search indicators by keyword
get_indicators() Return indicator metadata as a data frame
get_themes() List indicator themes/domains
select_indicator() Interactive menu to pick an indicator
select_level() Interactive menu to pick a spatial level
select_years() Interactive menu to pick year(s)
get_geographies() List available spatial levels
compare_regions() Filter downloaded data to named regions
compare_region() Singular alias for compare_regions()
compare_districts() Filter data by district names or IDs
compare_district() Singular alias for compare_districts()
inkar_trends() Line chart of indicator values over time
plot_inkar() Plot downloaded data on a map
clear_inkar_cache() Clear the local API response cache