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