# 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.

### List All Indicators

To see a sortable, searchable list of all available indicators:

    # Opens a viewer in RStudio
    view_indicators()

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

### Search by Text

If you are looking for a specific topic, like “GDP” or “Population”:

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

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

The search results includes the `ID` (Shortname) and `M_ID` which you will need to download data.

## 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).

### Basic Download

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

### Specifying Years

You can request a specific year or a range of years:

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

### Bilingual Output

By default, column names are in German (matching the original source). You can switch to English:

    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.