Python SDK

topolab-py is een dunne client bovenop de Topolab REST API voor data- en analyticswerk in Python. Het verpakt datasetmetadata, monsters en downloads, en retourneert resultaten als pandas of GeoPandas objecten.

Preview — de officiële SDK is in preview. De REST en OGC API's die het verpakt zijn vandaag algemeen beschikbaar; gebruik de REST/curl-equivalenten hieronder totdat de SDK wordt uitgebracht.

Installeren

pip install topolab

Het pakket importeert als topolab. GeoPandas-ondersteuning vereist de optionele extra's (pip install "topolab[geo]"), die geopandas en de geometrie-afhankelijkheden binnenhalen.

Maak een client

Construeer een Client met een API-sleutel. De sleutel bevat jouw scope en add-ons — datasetdownloads hebben API_ACCESS nodig. Zie Authenticatie.

from topolab import Client

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

Laad de sleutel vanuit de omgeving in plaats van deze hard-coded in te voeren:

import os
from topolab import Client

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

Datasets worden aangesproken op hun table naam, bijvoorbeeld nl-domino-poi. Elke methode hieronder werkt op tl.dataset("<table>").

Lees een GeoDataFrame

.to_geodataframe() downloadt de dataset als GeoJSON en parseert deze in een GeoPandas GeoDataFrame, met geometrie in WGS84 (EPSG:4326).

gdf = tl.dataset("nl-domino-poi").to_geodataframe()
gdf.plot()

Dit verbruikt credits en vereist de API_ACCESS add-on, omdat het de volledige export binnenhaalt. Het GA-equivalent is de GeoJSON-download — zie Bestanden downloaden:

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

import geopandas as gpd

gdf = gpd.read_file("nl-domino-poi.geojson")

Lees een DataFrame

.to_dataframe() retourneert een gewone pandas DataFrame met longitude/latitude kolommen (WGS84), geschikt voor tabulaire analyse zonder geometrie.

df = tl.dataset("nl-domino-poi").to_dataframe()
df[["name", "city", "longitude", "latitude"]].head()

Dit verbruikt ook credits en vereist API_ACCESS. Het GA-equivalent is de CSV of JSON-download:

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

import pandas as pd

df = pd.read_csv("nl-domino-poi.csv")

Inspecteer een monster

.sample() retourneert de gratis monster rijen zodat je het schema kunt controleren voordat je credits uitgeeft. Monsters zijn openbaar en kosten niets.

sample = tl.dataset("nl-domino-poi").sample()
sample.head()

Het GA-equivalent is het monster-eindpunt, waarvoor geen sleutel nodig is:

curl "https://api.topolab.nl/v1/dataset/nl-domino-poi/sample/json"

import pandas as pd

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

Download naar een bestand

.download(format, path=...) streamt een volledige export naar de schijf in elk ondersteund formaat: csv, json, geojson, kml, of shp.

tl.dataset("nl-domino-poi").download("geojson", path="nl-domino-poi.geojson")

Dit verbruikt credits en vereist API_ACCESS. Het GA-equivalent is een directe download van het formaat-eindpunt:

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

SHP wordt geleverd als een gecomprimeerd shapefile-pakket; de andere formaten worden gestreamd als een enkel bestand.

Fouten

De client genereert een getypte uitzondering die de HTTP-status weerspiegelt:

Status	Betekenis
401	Ontbrekende of ongeldige API-sleutel.
403	Sleutel mist de API_ACCESS add-on die vereist is voor downloads.
404	Onbekende table of niet-ondersteund formaat.
429	Rate limited — zie Rate limits & credits.

Heb je API_ACCESS nodig, of wil je vroegtijdige toegang tot de SDK-preview? Neem contact met ons op.

Volgende

• Quickstart — jouw eerste verzoek van begin tot eind.
• Bestanden downloaden — de GA-download-eindpunten in volle omvang.
• JavaScript SDK — dezelfde operaties vanuit Node en de browser.