JavaScript SDK

@topolab/sdk is a typed client for the Topolab REST and OGC APIs, usable from Node and modern browsers. It wraps feature paging and dataset downloads behind a small promise-based 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

npm install @topolab/sdk

The package ships ES modules and TypeScript types. It uses the platform fetch, so Node 18+ or any modern browser works without a polyfill.

Create a client

Construct a Client with your API key. The key carries your scope and addons, OGC feature access needs GIS_ACCESS, downloads need API_ACCESS. See Authentication.

import { Client } from "@topolab/sdk";

const tl = new Client({ apiKey: "tlb_prod_..." });

Load the key from the environment rather than embedding it in client-side bundles:

import { Client } from "@topolab/sdk";

const tl = new Client({ apiKey: process.env.TOPOLAB_API_KEY });

Datasets are addressed by their table name, for example transport_infrastructure_bushaltes. Each method below operates on tl.dataset("<table>").

Environments

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

const tl = new Client({ apiKey: "...", environment: "staging" }); // https://api-staging.topolab.nl

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

Page through items

.items() queries the OGC API - Features items endpoint for a collection and returns GeoJSON features. Pass limit to page and bbox to filter to a bounding box (WGS84, [minLon, minLat, maxLon, maxLat]).

const fc = await tl.dataset("transport_infrastructure_bushaltes").items({
  limit: 100,
  bbox: [4.7, 52.2, 5.1, 52.5],
});

console.log(fc.features.length);

This requires the GIS_ACCESS addon. The GA equivalent is a direct call to the OGC items endpoint, see Items and BBox and filtering.

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=100&bbox=4.7,52.2,5.1,52.5"

const url = new URL(
  "https://api.topolab.nl/v1/ogc/collections/transport_infrastructure_bushaltes/items"
);
url.searchParams.set("limit", "100");
url.searchParams.set("bbox", "4.7,52.2,5.1,52.5");

const res = await fetch(url, {
  headers: { "X-API-Key": "tlb_prod_..." },
});
const fc = await res.json();

The response is a standard GeoJSON FeatureCollection; follow the next link in fc.links to page.

Download a dataset

.download(format) fetches a full export and resolves to a Blob (browser) or Buffer (Node) in any supported format: csv, json, geojson, kml, or shp.

const blob = await tl.dataset("transport_infrastructure_bushaltes").download("geojson");

This consumes credits and requires API_ACCESS. The GA equivalent is a direct download of the format endpoint, see Download files:

curl -H "X-API-Key: tlb_prod_..." \
  "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes/files/geojson" \
  -o transport_infrastructure_bushaltes.geojson

const res = await fetch(
  "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes/files/geojson",
  { headers: { "X-API-Key": process.env.TOPOLAB_API_KEY } }
);
const geojson = await res.json();

Keep downloads server-side: a key embedded in browser code is exposed to every visitor.

Errors

The client rejects with a typed error that mirrors the HTTP status:

Status	Meaning
401	Missing or invalid API key.
403	Key lacks GIS_ACCESS (items) or API_ACCESS (downloads).
404	Unknown collection, table, or unsupported format.
429	Rate limited, see Rate limits & credits.

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

Next

• Quickstart, your first request end to end.
• BBox and filtering, spatial and attribute filters on items.
• Python SDK, the same operations for data science.