PostGIS SQL access

Send a single read-only SELECT, including the full PostGIS spatial toolkit, to an HTTP endpoint and get JSON rows back. It is a programmatic HTTP+JSON API for your own code, scripts, notebooks, and the SDKs. It is not a PostgreSQL wire connection: desktop SQL clients and BI tools cannot connect to it directly.

Preview, PostGIS SQL access is documented here as a contract and is not yet live in production. The base URL below shows the intended endpoint; treat the request and response shapes as the specification, not a callable production URL today.

This is an Enterprise-only capability.

Endpoint

POST /v1/sql/query

Authenticated with an organization API key sent as X-API-Key. The key needs the READ permission on the DATA resource, and its organization must be on the Enterprise plan with the SQL_ACCESS addon and active licences for the datasets you query. See Authentication. Each query costs 25 credits; see Rate limits & credits.

Request

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

Body

Field	Type	Description
query	string	A single read-only SELECT statement. Required.

Rules

• Read-only, single statement. The query runs inside a read-only transaction and only one SELECT is accepted per request. Statements that write, change schema, or chain multiple commands are refused.
• Scoped to your licenses. Every table referenced must be a dataset your organization holds an active license for. Anything else is refused before execution.
• PostGIS allowed. The full PostGIS function library is available (ST_Intersects, ST_DWithin, ST_AsGeoJSON, …), so you can filter by geometry and return GeoJSON without pulling rows client-side.
• Limits. Results are capped at 10,000 rows and each query has a 30-second statement timeout. Add your own LIMIT to request fewer.

Response

{
  "columns": ["city", "geom"],
  "rows": [
    {
      "city": "Amsterdam",
      "geom": "{\"type\":\"Point\",\"coordinates\":[4.9003,52.3789]}"
    }
  ],
  "datasets": ["transport_infrastructure_bushaltes"]
}

Field	Description
columns	Column names in the order selected.
rows	Result rows as JSON objects keyed by column name.
datasets	The licensed relations the query read from, recorded for billing and audit.

Not a database connection

This is an HTTP+JSON endpoint, not the PostgreSQL wire protocol. You cannot point a Postgres client or BI tool at it:

• DBeaver, psql, DataGrip, Tableau, Power BI, cannot connect directly. Query from your own backend and feed the results in.
• QGIS, ArcGIS, use the OGC API via the GIS Access add-on, not this endpoint.

It is designed for code: Python, R, JavaScript, curl, scheduled jobs, and the Topolab SDKs.

Errors

Status	Meaning
400	The query body is missing, is not a single SELECT, or is otherwise rejected by the read-only parser.
401	Missing or invalid X-API-Key.
403	The key lacks READ on DATA, its organization is not on Enterprise or lacks the SQL_ACCESS addon, or the query references a dataset it does not license.
429	Rate limited, see Rate limits & credits.

Next

• Get a dataset, table identifiers and field analysis to write queries against.
• OGC API, the GIS path for QGIS and ArcGIS.