KorAPConnection: Connect to KorAP Server

In RKorAPClient: 'KorAP' Web Service Client Package

Connect to KorAP Server

Description

KorAPConnection() creates a connection to a KorAP server for corpus queries. This is your starting point for all corpus analysis tasks.

Usage

KorAPConnection(
  KorAPUrl = defaultKorAPUrl(),
  apiVersion = "v1.0",
  apiUrl,
  accessToken = getAccessToken(KorAPUrl),
  oauthClient = NULL,
  oauthScope = "search match_info",
  authorizationSupported = TRUE,
  userAgent = "R-KorAP-Client",
  timeout = 240,
  verbose = FALSE,
  cache = TRUE
)

Arguments

KorAPUrl	URL of the web user interface of the KorAP server instance you want to access. Defaults to the environment variable KORAP_URL if set and to the IDS Mannheim KorAP main instance to query DeReKo, otherwise. In order to access the KorAP instance at the German National Library (DNB) to query the contemporary fiction corpus DeLiKo@DNB, for example, set KorAPUrl to https://korap.dnb.de/.
apiVersion	which version of KorAP's API you want to connect to. Defaults to "v1.0".
apiUrl	URL of the KorAP web service. If not provided, it will be constructed from KorAPUrl and apiVersion.
accessToken	OAuth2 access token. For queries on corpus parts with restricted access (e.g. textual queries on IPR protected data), you need to authorize your application with an access token. You can obtain an access token in the OAuth settings of your KorAP web interface. More details are explained in the authorization section of the RKorAPClient Readme on GitHub. To use authorization based on an access token in subsequent queries, initialize your KorAP connection with: kco <- KorAPConnection(accessToken="<access token>") In order to make the API token persistent for the currently used KorAPUrl (you can have one token per KorAPUrl / KorAP server instance), use: persistAccessToken(kco) This will store it in your keyring using the keyring::keyring-package. Subsequent KorAPConnection() calls will then automatically retrieve the token from your keying. To stop using a persisted token, call clearAccessToken(kco). Please note that for DeReKo, authorized queries will behave differently inside and outside the IDS, because of the special license situation. This concerns also cached results which do not take into account from where a request was issued. If you experience problems or unexpected results, please try kco <- KorAPConnection(cache=FALSE) or use clearCache() to clear the cache completely. An alternative to using an access token is to use a browser-based oauth2 workflow to obtain an access token. This can be done with the auth() method.
oauthClient	OAuth2 client object.
oauthScope	OAuth2 scope. Defaults to "search match_info".
authorizationSupported	logical that indicates if authorization is supported/necessary for the current KorAP instance. Automatically set during initialization.
userAgent	user agent string. Defaults to "R-KorAP-Client".
timeout	timeout in seconds for API requests (this does not influence server internal timeouts). Defaults to 240 seconds.
verbose	logical that decides whether following operations will default to be verbose. Defaults to FALSE. If not explicitly provided, this can be overridden via environment variable KORAP_VERBOSE (accepted true-ish values: 1, true, yes, on) or R option rkorap.verbose (logical).
cache	logical that decides if API calls are cached locally. You can clear the cache with clearCache(). Defaults to TRUE.

Details

Use KorAPConnection() to connect, then corpusQuery() to search, and fetchAll() to retrieve results. For authorized access to restricted corpora, use auth() or provide an accessToken.

The KorAPConnection object contains various configuration slots for advanced users: KorAPUrl (server URL), apiVersion, accessToken (OAuth2 token), timeout (request timeout), verbose (logging), cache (local caching), and other technical parameters. Most users can ignore these implementation details.

Value

KorAPConnection() object that can be used e.g. with corpusQuery()

Basic Workflow

# Connect to KorAP
kcon <- KorAPConnection()

# Search for a term
query <- corpusQuery(kcon, "Ameisenplage")

# Get all results
results <- fetchAll(query)

Authorization

For access to restricted corpora, authorize your connection:

kcon <- KorAPConnection() |> auth()

See Also

Other initialization functions: auth,KorAPConnection-method, clearAccessToken,KorAPConnection-method, persistAccessToken,KorAPConnection-method

RKorAPClient documentation built on Sept. 9, 2026, 5:11 p.m.