GeoLens
Overview
PostGIS-native geospatial data catalog with OGC API Features and Records support
GeoLens API 1.14.2
Section titled “GeoLens API 1.14.2”Overview
GeoLens is a self-hosted spatial data catalog that ingests vector files (GeoPackage, Shapefile, GeoJSON, CSV), stores them in PostGIS, and exposes them through OGC API endpoints.
OGC Conformance Classes
- OGC API Common 1.0 — Core, Landing Page, JSON, OAS 3.0
- OGC API Features Part 1 — Core, GeoJSON, OAS 3.0
- OGC API Features Part 3 — Filtering (CQL2-Text, CQL2-JSON)
QGIS Quick-start
- Layer > Add Layer > WFS / OGC API Features
- URL:
{your-server}/api/ - GeoLens advertises collections automatically.
GDAL / ogr2ogr Quick-start
# List collections
ogrinfo OAPIF:{your-server}/api/
# Download a collection to GeoPackage
ogr2ogr -f GPKG output.gpkg OAPIF:{your-server}/api/ {collection-id}Authentication
GeoLens supports three authentication methods. Public datasets are accessible without credentials; private/restricted datasets require one of:
| Method | Usage |
|---|---|
| API Key header | X-Api-Key: <key> |
| JWT Bearer token | Authorization: Bearer <token> |
| API Key query param (deprecated) | ?api_key=<key> |
Priority: header API key > query param API key > JWT > anonymous.
The ?api_key= query parameter is deprecated. A key sent in the URL is
recorded by server access logs and any proxy in between. Prefer the
X-Api-Key header; keep the query parameter only for clients that cannot
send headers (e.g. XYZ tile URLs in desktop GIS tools).
API keys may carry an optional expiry (expires_at at mint time). Expired
keys stop authenticating, and keys are also invalidated by security events
on the owner’s account (password change or role change). Logging out of the
web UI does not affect API keys.
What a rejected credential looks like
Send no credential and you are served anonymously: public datasets come back, private ones do not.
Send a credential that cannot be resolved (expired, revoked, or mistyped)
and every endpoint that reads credentials answers 401, including the ones
that also serve anonymous callers. It is never quietly ignored. A 200
carrying only the public subset would look exactly like a catalog holding
nothing more, so a client whose key died overnight would go on working
against a smaller view of the data and never be told. The 401 is also the
signal a client needs to refresh and retry.
Three cases sit outside that rule.
POST /auth/logout accepts a dead access token so a stale session can still
be cleared, and falls back to the refresh credential. It still answers 401
when nothing you present resolves.
A request that something other than your identity already authorized is
served, and the dead credential is ignored: a valid X-Embed-Token, or a
valid signed tile template (sig, exp, scope). Each authorizes one
specific resource on its own, so an embed viewer carrying a stale browser
session still renders. An invalid or absent capability puts the request back
under the rule above, so a junk X-Embed-Token cannot be used to suppress
the 401.
GET /maps/shared/{token} answers 404 for an unknown share link and 410
for a revoked one whatever you send. No credential could have made that link
work, and reporting the credential instead would hide the answer you can act
on.
A few endpoints read no credential at all, such as the landing page and the
conformance declaration, and answer 200 either way.
GDAL / ogr2ogr with API Key
# List collections (including private ones accessible to your key)
ogrinfo --config GDAL_HTTP_HEADERS "X-Api-Key: YOUR_KEY" "OAPIF:{your-server}/api/"
# Download a private collection
ogr2ogr -f GPKG out.gpkg --config GDAL_HTTP_HEADERS "X-Api-Key: YOUR_KEY" "OAPIF:{your-server}/api/" {collection-id}QGIS with API Key
In the WFS / OGC API Features connection dialog, append ?api_key=YOUR_KEY
to the server URL (the connection dialog cannot send custom headers; this is
the main remaining use of the deprecated query parameter).
Authentication
Section titled “ Authentication ”ApiKeyHeader
Section titled “ApiKeyHeader ”GeoLens API key. Preferred API-key transport.
Security scheme type: apiKey
Header parameter name: X-Api-Key
ApiKeyQuery
Section titled “ApiKeyQuery ”Legacy API-key query parameter; prefer X-Api-Key.
Security scheme type: apiKey
Query parameter name: api_key