GeoLens
Overview
PostGIS-native geospatial data catalog with OGC API Features and Records support
GeoLens API 1.19.0
Section titled “ GeoLens API 1.19.0 ”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
GET /api/conformance is the machine-readable list and the one a client
should read. This is the same set in prose:
- OGC API Common 1.0 – Core, Landing Page, JSON
- OGC API Features Part 1 – Core, GeoJSON
- OGC API Features Part 3 – Queryables, Filter, Features Filter
- CQL2 1.0 – CQL2-Text, CQL2-JSON, Basic CQL2, advanced comparison operators, basic spatial functions
- OGC API Records Part 1 – Record Core, core query parameters, sorting, JSON
The OAS 3.0 classes of Common and Features Part 1 are NOT claimed: this server publishes its API document as OpenAPI 3.1.
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, and it authenticates reads
only. A key sent in the URL is recorded by server access logs and any proxy
in between, so it authenticates GET, HEAD and OPTIONS and nothing else.
On any other method the key is ignored and the request is answered as if no
credential had been sent. Prefer the X-Api-Key header, which carries reads
and writes alike; 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, accepted on GET/HEAD/OPTIONS only; ignored on any other method. Prefer X-Api-Key.
Security scheme type: apiKey
Query parameter name: api_key