Python SDK

topolab is a thin client over the Topolab REST API for data and analytics work in Python (install with pip install topolab). It wraps dataset metadata, samples, and downloads, and returns results as pandas or GeoPandas objects.

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

pip install topolab

The package imports as topolab. GeoPandas support requires the optional extras (pip install "topolab[geo]"), which pull in geopandas and its geometry dependencies.

Create a client

Construct a Client with an API key. The key carries your scope and addons, dataset downloads need API_ACCESS. See Authentication.

from topolab import Client

tl = Client(api_key="tlb_prod_...")

Load the key from the environment rather than hard-coding it:

import os
from topolab import Client

tl = Client(api_key=os.environ["TOPOLAB_API_KEY"])

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

Environments

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

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 GeoDataFrame

.to_geodataframe() downloads the dataset as GeoJSON and parses it into a GeoPandas GeoDataFrame, with geometry in WGS84 (EPSG:4326).

gdf = tl.dataset("transport_infrastructure_bushaltes").to_geodataframe()
gdf.plot()

This consumes credits and requires the API_ACCESS addon, because it pulls the full export. The GA equivalent is the GeoJSON download, 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

import geopandas as gpd

gdf = gpd.read_file("transport_infrastructure_bushaltes.geojson")

Read a plain DataFrame

For tabular analysis without geometry, take the GeoDataFrame from .to_geodataframe() and derive explicit longitude/latitude columns, a GeoDataFrame is a pandas DataFrame, so all the usual pandas operations work.

gdf = tl.dataset("transport_infrastructure_bushaltes").to_geodataframe()

df = gdf.drop(columns="geometry").assign(
    longitude=gdf.geometry.x,
    latitude=gdf.geometry.y,
)
df[["name", "city", "longitude", "latitude"]].head()

This consumes credits and requires API_ACCESS. The GA equivalent is the CSV download, read straight into pandas:

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

import pandas as pd

df = pd.read_csv("transport_infrastructure_bushaltes.csv")

Inspect a sample

.sample() returns the free sample rows so you can check the schema before spending credits. Samples are public and cost nothing.

sample = tl.dataset("transport_infrastructure_bushaltes").sample()
sample.head()

The GA equivalent is the sample endpoint, which needs no key:

curl "https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes/sample/json"

import pandas as pd

sample = pd.read_json("https://api.topolab.nl/v1/dataset/transport_infrastructure_bushaltes/sample/json")

Download to a file

.download(format, path=...) streams a full export to disk in any supported format: csv, json, geojson, kml, or shp.

tl.dataset("transport_infrastructure_bushaltes").download("geojson", path="transport_infrastructure_bushaltes.geojson")

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

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

SHP is delivered as a zipped shapefile bundle; the other formats stream as a single file.

Errors

The client raises a typed exception that mirrors the HTTP status:

Status	Meaning
401	Missing or invalid API key.
403	Key lacks the API_ACCESS addon required for downloads.
404	Unknown table or unsupported format.
429	Rate limited, see Rate limits & credits.

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

Next

• Quickstart, your first request end to end.
• Download files, the GA download endpoints in full.
• JavaScript SDK, the same operations from Node and the browser.