How do I query datasets with PostGIS SQL?

Enterprise plan, an organization API key sent as X-API-Key, and an active license for every dataset your query references. Preview: documented as a contract, not yet live in production.

1. What it is (and is not)

PostGIS SQL access lets you send a single read-only SELECT, including the full PostGIS spatial toolkit, to POST /v1/sql/query and receive JSON rows. It is a programmatic HTTP+JSON API for your own code, scripts, notebooks and the SDKs — it is not a PostgreSQL wire connection. It is an Enterprise-only capability, and is currently documented in preview as a contract rather than a callable production URL.

2. Send a query

Authenticate with an organization API key as X-API-Key. The body takes sql (a single read-only SELECT, required) and an optional maxRows cap.

curl -X POST \
  -H "X-API-Key: tlb_prod_..." \
  -H "Content-Type: application/json" \
  -d '{ "sql": "SELECT name, city, ST_AsGeoJSON(geom) AS geom FROM nl_domino_poi WHERE city = '\''Amsterdam'\'' LIMIT 100", "maxRows": 100 }' \
  "https://api.topolab.nl/v1/sql/query"

3. The rules and limits

Only one read-only SELECT is accepted per request — anything that writes, changes schema, or chains commands is refused. Every table you reference must be a dataset your organization holds an active license for; anything else is refused before execution. The full PostGIS library is available (ST_Intersects, ST_DWithin, ST_AsGeoJSON, …). Results are capped at 10,000 rows with a 30-second statement timeout; use maxRows to request fewer, and check the truncated flag when the cap cuts the result short.

4. Not a database connection

You cannot point a Postgres client or BI tool at this endpoint — DBeaver, psql, DataGrip, Tableau and Power BI cannot connect directly. Query from your own backend and feed the results in. For QGIS or ArcGIS, use the OGC API — a Team / Enterprise plan capability — instead.

Reading the errors

400 means the sql body is missing, is not a single SELECT, or is rejected by the read-only parser; 401 is a bad key; 403 means the organization is not on Enterprise or the query references an unlicensed dataset; 429 is rate limiting.