---
title: "Getting started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(bunddev)
```

# Overview

`bunddev` provides a small registry of public APIs and helpers to explore
their OpenAPI specifications. Some APIs enforce rate limits; check the registry
details for service-specific guidance.

API-specific helpers return tidy tibbles by default. Use `bunddev_call()` for
raw responses.

When `flatten = TRUE`, set `flatten_mode` to "json" (default), "drop", or
"unnest". Note that "unnest" expands list-columns into multiple rows.

Use `bunddev_parameters("<api>")` to see the currently valid parameters for an
API if the upstream spec has changed. For endpoint-specific enums, use
`bunddev_parameter_values(smard_timeseries, "resolution")`.

Several adapters add parsed POSIXct time columns (suffix `_time`) using the
Europe/Berlin timezone (for example `time` in SMARD, `start_time` in DWD, and
`date_time` in Tagesschau).

The package separates a core OpenAPI layer from adapter helpers for specific
APIs.

## Browse the registry

```{r registry}
bunddev_list()
```

## Acknowledgements

This package builds on the work of the bund.dev team, who curate and centralize
public sector APIs for the community (https://bund.dev, https://github.com/bundesAPI).

Filter by tag to narrow down the list.

```{r registry-filter}
bunddev_list(tag = "jobs")
```

## Inspect one API

```{r registry-info}
bunddev_info("abfallnavi")
```

## List endpoints

```{r registry-endpoints}
endpoints <- bunddev_endpoints("abfallnavi")
head(endpoints, 5)
```

## Bewerberboerse workflow

```{r bewerberboerse, eval = FALSE}
Sys.setenv(BEWERBERBOERSE_API_KEY = "jobboerse-bewerbersuche-ui")
bunddev_auth_set("bewerberboerse", type = "api_key", env_var = "BEWERBERBOERSE_API_KEY")

bewerber <- bewerberboerse_search(
  params = list(was = "data", size = 10),
  flatten = TRUE
)

details <- bewerberboerse_details(bewerber$refnr[[1]], flatten = TRUE)
```

## Autobahn workflow

```{r autobahn, eval = FALSE}
roads <- autobahn_roads()
road_id <- roads$road_id[[1]]

roadworks <- autobahn_roadworks(road_id, flatten = TRUE)
warnings <- autobahn_warnings(road_id, flatten = TRUE)

roadwork_details <- autobahn_roadwork_details(roadworks$identifier[[1]], flatten = TRUE)
warning_details <- autobahn_warning_details(warnings$identifier[[1]], flatten = TRUE)
```

## Handelsregister workflow

```{r handelsregister, eval = FALSE}
companies <- handelsregister_search("deutsche bahn")
```

## SMARD workflow

```{r smard, eval = FALSE}
library(ggplot2)

timestamp <- 1627250400000
series <- smard_timeseries(410, region = "DE", resolution = "hour", timestamp = timestamp)

ggplot(series, aes(time, value)) +
  geom_line() +
  labs(x = "Time", y = "MW")
```

`series$time` is a POSIXct column parsed in Europe/Berlin.

## DWD workflow

```{r dwd, eval = FALSE}
stations <- dwd_station_overview(c("10865", "G005"), flatten = TRUE)
```

## Jobsuche workflow

```{r jobsuche, eval = FALSE}
Sys.setenv(JOBBOERSE_API_KEY = "jobboerse-jobsuche")
bunddev_auth_set("jobsuche", type = "api_key", env_var = "JOBBOERSE_API_KEY")

jobs <- jobsuche_search(params = list(was = "data", size = 5), flatten = TRUE)
```

## Parameter discovery

```{r params, eval = FALSE}
bunddev_parameters("smard")
bunddev_parameter_values(smard_timeseries, "resolution")
```