---
title: "Introduction to inkaR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to inkaR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>"
)
```

## Overview

The `inkaR` package provides a modern, user-friendly interface to access statistical data from the [BBSR INKAR](https://www.inkar.de/) 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:

```r
# 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:

```r
# 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":

```r
# 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

```r
# 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:

```r
# 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:

```r
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.

```r
# 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:

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