How do I download full dataset files?

Downloads and coordinates require a valid X-API-Key and an active license for the dataset. Historical archives are a Team / Enterprise plan capability.

1. List available files (free)

Before spending anything, call GET /v1/dataset/:table/files. It is public and costs no credits, and returns the export formats a dataset offers with the per-download credit cost for each — so you know what exists up front.

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

2. Download a full export

Call GET /v1/dataset/:table/files/:format with your X-API-Key. This requires an active license for the dataset and costs 10 credits per download. Supported formats are csv, json, geojson, kml and shp. The endpoint streams the file, so use -o to save it.

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

3. Coordinates only

If you only need points on a map, GET /v1/dataset/:table/coordinates returns a JSON array of WGS84 lng/lat pairs without every attribute. It also requires an active license for the dataset and costs 15 credits.

4. Historical archives

Past refreshes are kept as monthly snapshots. List them for free with GET /v1/dataset/:table/archives/list, which returns the available months. Download one with GET /v1/dataset/:table/archives/:month/:format where month is YYYY-MM; historical archives are a Team / Enterprise plan capability, and each archive month costs 20 credits.

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

Reading the errors

401 means a missing or invalid X-API-Key; 403 means the key lacks the required permission or you don't have an active license for that dataset (archives also need a Team / Enterprise plan); 402 means insufficient credits; 404 is an unknown table, unsupported format, or an unavailable archive month. Need access to a dataset you don't yet license? Contact us.