R SDK

The topolab R package reads Topolab datasets into sf objects for spatial analysis and mapping in R. It wraps dataset metadata and feature access behind a pipe-friendly interface.

Preview, the official SDK is in preview. The REST and OGC APIs it wraps are generally available today; use the REST/curl equivalents below until the SDK ships.

Install

install.packages("topolab")

The package depends on sf for geometry handling. If sf is not already installed, CRAN resolves it as a dependency; on Linux you may also need the system GDAL, GEOS, and PROJ libraries that sf requires.

Create a client

Set up a client with your API key. The key carries your scope and addons, reading features over OGC needs GIS_ACCESS. See Authentication.

library(topolab)

tl <- tl_client(api_key = "tlb_prod_...")

Read the key from the environment rather than committing it to a script:

library(topolab)

tl <- tl_client(api_key = Sys.getenv("TOPOLAB_API_KEY"))

Datasets are addressed by their table name, for example transport_infrastructure_bushaltes.

Environments

The client targets production (https://api.topolab.nl) by default. Switch to staging with the environment argument:

tl <- tl_client(api_key = "...", environment = "staging") # https://api-staging.topolab.nl

You can also set TOPOLAB_ENV=staging. For self-hosting or tests, pass an explicit base_url, which overrides environment. Resolution precedence (most specific first): base_url → environment → TOPOLAB_BASE_URL → TOPOLAB_ENV → production.

Read a dataset into sf

tl_dataset() references a dataset by table; pipe it into as_sf() to materialize the features as an sf object with geometry in WGS84 (EPSG:4326).

poi <- tl_dataset(tl, "transport_infrastructure_bushaltes") |> as_sf()

plot(poi["city"])

This requires the GIS_ACCESS addon, because it reads features from the OGC API. The GA equivalent is to read the OGC items endpoint directly with sf::st_read. The endpoint serves GeoJSON, and the API key travels in the X-API-Key header, see Items.

Collection id. The OGC collectionId is the dataset's table name (e.g. transport_infrastructure_bushaltes), the same value you pass to tl_dataset(). List them with GET /v1/ogc/collections (see Collections).

curl -H "X-API-Key: tlb_prod_..." \
  "https://api.topolab.nl/v1/ogc/collections/transport_infrastructure_bushaltes/items?limit=1000" \
  -o transport_infrastructure_bushaltes.geojson

library(sf)

poi <- st_read("transport_infrastructure_bushaltes.geojson")

sf::st_read can also read the endpoint over HTTP via GDAL's OGC API - Features driver. Pass the key as an HTTP header through GDAL's config so it is not written to disk:

library(sf)

Sys.setenv(GDAL_HTTP_HEADERS = "X-API-Key: tlb_prod_...")

poi <- st_read(
  "OAPIF:https://api.topolab.nl/v1/ogc/collections/transport_infrastructure_bushaltes"
)

The result is a standard sf data frame; geometry is WGS84 (EPSG:4326). Use sf::st_transform() if you need a projected CRS such as RD New (EPSG:28992) for local analysis.

Errors

When a request fails, the package raises an R condition that carries the HTTP status:

Status	Meaning
401	Missing or invalid API key.
403	Key lacks the GIS_ACCESS addon required for feature access.
404	Unknown collection or table.
429	Rate limited, see Rate limits & credits.

Need GIS_ACCESS enabled, or want early access to the SDK preview? Contact us.

Next

• Collections, list the datasets available as feature collections.
• BBox and filtering, restrict an sf read to an area of interest.
• QGIS plugin, read the same collections in a desktop GIS.