kvkapir

The goal of this R-package is to provide a R-package to access the API of the Dutch Champer of Commerce

https://github.com/coeneisma/kvkapir

Repository

The goal of this R-package is to provide a R-package to access the API of the Dutch Champer of Commerce

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# kvkapiR


[![CRAN status](https://www.r-pkg.org/badges/version/kvkapiR)](https://CRAN.R-project.org/package=kvkapiR)
[![R-CMD-check](https://github.com/coeneisma/kvkapiR/workflows/R-CMD-check/badge.svg)](https://github.com/coeneisma/kvkapiR/actions)


The goal of kvkapiR is to provide a convenient R programming language interface to the Dutch Chamber of Commerce (KvK) APIs. This package is built using the httr2 package and follows best practices for wrapping APIs in R, as outlined in the [httr2 documentation](https://httr2.r-lib.org/articles/wrapping-apis.html). It simplifies authentication, request handling, and response parsing when interacting with the KvK API.

The package provides access to [all the KvK APIs](https://developers.kvk.nl/documentation#available-apis):

* KvK Search API
* KvK Basisprofiel API
* KvK Vestigingsprofiel API
* KvK Naamgeving API

More details can be found [on the developers website of the KvK](https://developers.kvk.nl/apis).

## Installation

The package has been submitted to CRAN for review. Once it's accepted and the CRAN status badge shows "CRAN: OK", you can install the stable version from CRAN with:

``` r
install.packages("kvkapiR")
```

Until then, you can install the current stable version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("coeneisma/kvkapiR")
```

To install the latest development version:

``` r
# install.packages("devtools")
devtools::install_github("coeneisma/kvkapiR", ref = "development")
```

## Setting up API Access

### API Key

To use the KvK API, you need an API key. You can apply for one at the [KvK Developer Portal](https://developers.kvk.nl/apply-for-apis?step=api-overview).

```r
# Set API key for current session
kvk_set_api_key("your_api_key_here")

# Or add to .Renviron file manually:
# KVK_API_KEY=your_api_key_here
```

### Test Environment

The package includes support for the KvK test environment with fictional Donald Duck data:

```r
# No API key needed for test environment
test_results <- kvk_search(naam = "Donald Duck", test_environment = TRUE)
```

## Basic Usage

### Search for Businesses

```{r example}
library(kvkapiR)

# Search by location
koudum <- kvk_search(plaats = "Koudum")
koudum

# Combine search criteria
snackbar <- kvk_search(naam = "snackbar", plaats = "Utrecht")
snackbar

# Search by address
address_search <- kvk_search(postcode = "2594BD", huisnummer = "10")

# Filter by business type (multiple types allowed)
mixed_types <- kvk_search(
  plaats = "Amsterdam",
  type = "hoofdvestiging",
  type = "rechtspersoon"
)
```

### Retrieve Detailed Profiles

Each profile retrieval costs EUR 0.02 (free for government organizations):

```{r, eval = FALSE}
# Get basic company profile (using a social organization)
profile <- kvk_get_basisprofiel("01036576")

# Get establishment details
establishment <- kvk_get_vestigingsprofiel("000007810083")

# Get name history
names <- kvk_get_naamgeving("01036576")
```

## Usage Tracking and Cost Management

The package includes automatic session-based usage tracking:

```{r, eval = FALSE}
# View current session usage
kvk_usage_report()

# Set session alerts
kvk_usage_alert(max_cost = 5.00)

# Export session data
kvk_export_usage("session_usage.csv")
```

### Pricing
- **Monthly base fee**: EUR 6.20 (when you have API access)
- **Search API**: Free (after base fee)
- **Profile APIs**: EUR 0.02 per call
- **Government organizations**: All API calls are free
- **Access requirement**: Only authorized business representatives can apply

## More Information

For detailed examples and advanced usage, see `vignette("kvkapiR")` or visit the [package website](https://coeneisma.github.io/kvkapiR/).

Owner

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago

Packages