Quick Start Guide

This vignette demonstrates a typical workflow using the bunddev package to discover an API, inspect its parameters, set up authentication (if needed), retrieve tidy data, and visualise it.

1. Install and load the package

# Install the development version (if not already installed)
# remotes::install_github("mchlbckr/bunddev")

library(bunddev)

2. List available APIs

# Show the first few entries in the bundled registry
available <- bunddev_registry()
head(available)

You can filter by tag or authentication type, for example:

bunddev_list(tag = "jobs")          # APIs related to job searching
bunddev_list(auth = "api_key")      # APIs that require an API key

3. Inspect parameters for a chosen API

Suppose we are interested in the SMARD electricity market API.

bunddev_parameters("smard")                     # All parameters
bunddev_parameters("smard", name = "resolution")  # Specific parameter details

4. Set up authentication (if required)

You can store your API keys securely in a .Renviron file, which R loads automatically at startup. Add a line like the following to ~/.Renviron (or a project‑specific .Renviron in the package root):

SMARD_API_KEY=your-secret-key

Then reference the variable in R without hard‑coding the key:

bunddev_auth_set("smard", type = "api_key", env_var = "SMARD_API_KEY", scheme = "Bearer")

Alternatively, for a quick session you can set the variable directly with Sys.setenv() as shown earlier.

5. Retrieve tidy data

Fetch a time‑series from SMARD and flatten list‑columns:

# Get hourly electricity generation for region DE, series ID 410
ts <- smard_timeseries(410, region = "DE", resolution = "hour")
head(ts)

6. Visualise the result

library(ggplot2)
ggplot(ts, aes(x = time, y = value)) +
  geom_line() +
  labs(title = "SMARD Time Series", x = "Time", y = "MW")

7. Rate‑limit handling

If you need to enforce a custom rate limit:

bunddev_rate_limit_set("smard", max_per_hour = 60)

8. Further help

All functions come with detailed help pages (e.g., ?smard_timeseries). Use bunddev_parameters() and bunddev_parameter_values() to explore allowed enum values.

This vignette is intentionally simple and runs without contacting any live API (except when you actually execute the examples). It is designed to work during package checks and as a quick reference for users.