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:

Browse & Search: Find indicators offline with view_indicators() and search_indicators().
Interactive Wizard: Step-by-step guided download with select_indicator(), select_level(), and select_years().
Bilingual Output: All results available in German (default) or English (lang = "en").
Disk Caching: API responses are cached locally — repeated calls return instantly.
Mapping: Visualize downloaded data on German administrative maps with plot_inkar().

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", "q_alo"), level = "KRE", year = 2021, lang = "en")

Results are merged by region and year into a wide-format tibble.

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, sf, and geodata packages.

Automatic Maps via GADM

By default, the function downloads boundaries from GADM and caches them. It supports: - BND: Federal Territory (Germany as a whole - GADM Level 0) - BLD: Federal States (GADM Level 1) - KRE: Districts (GADM Level 2) - GEM: Municipalities (GADM Level 3)

# 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():

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 GADM 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

Plot trends over time

inkar_trends(df, regions = c("Berlin", "Hamburg"))

Theme-filtered search

get_themes()                                   # list all themes
search_indicators("employment", theme = "Arbeitsmarkt")
view_indicators("en", theme = "Bevölkerung")

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