OGC API & Standards Endpoints

GeoLens implements several OGC and STAC standards alongside its REST API. This page covers the standards-based endpoints. Reach for the auto-generated reference for per-route schemas, request/response bodies, and the full conformance-class list.

Replace https://geolens.example.com with your GeoLens instance’s URL in every example below. Authentication follows the same rules as the rest of the API. See API Authentication for X-Api-Key, JWT, and OAuth options.

OGC API - Common

Provides the OGC API root, conformance declaration, and OpenAPI definition. Every OGC API client begins here.

Endpoints:

• GET /api/: landing document with links to conformance, collections, and OpenAPI.
• GET /api/conformance: list of conformance class URIs (Records, Features, CQL2, etc.).
• GET /api/openapi.json: full OpenAPI definition.

Curl:

curl https://geolens.example.com/api/
curl https://geolens.example.com/api/conformance

For the full schema of every endpoint, see the Endpoints by Tag section in the auto-generated reference.

OGC API - Records

The catalog itself is exposed as an OGC API Records collection at collections/datasets. Use this to list, filter, and discover datasets programmatically.

Endpoints:

• GET /api/collections/datasets/items: list catalog records (paginated, CQL2-filterable).

Curl:

curl https://geolens.example.com/api/collections/datasets/items

CQL2 filter (one example):

curl 'https://geolens.example.com/api/collections/datasets/items?filter=title%20LIKE%20%27%25hydrology%25%27&filter-lang=cql2-text'

The properties you can filter on are listed at /api/collections/datasets/queryables. The CQL2 grammar itself is advertised in /api/conformance (look for the cql2-text, cql2-json, and basic-cql2 conformance classes).

QGIS MetaSearch (built-in plugin):

1. Web > MetaSearch > MetaSearch (built-in, no install)
2. Services tab > New
3. Name: GeoLens
   URL:  https://geolens.example.com/api/
   Catalog Type: OGC API - Records
4. Save -> Search tab to query records.

GDAL ogr2ogr / ogrinfo (OAPIF driver):

ogrinfo OAPIF:https://geolens.example.com/api/

OGC API - Features

Per-dataset feature access for vector layers. Useful for exporting subsets to GeoPackage, Shapefile, or any GDAL-supported format.

Endpoints:

• GET /api/collections/{dataset_id}/items: feature items for a single dataset (bbox and datetime filterable). A CQL2 filter is supported only on the catalog collections/datasets/items collection; passing filter here returns HTTP 400.

Curl:

curl https://geolens.example.com/api/collections/{dataset_id}/items

QGIS Add Layer > OGC API Features:

1. Layer > Add Layer > Add WFS / OGC API Features Layer...
2. New connection: Name: GeoLens
   URL: https://geolens.example.com/api/?api_key=<your-api-key>
3. Connect -> pick collection -> Add.

ArcGIS Pro (New OGC API Server connection):

1. Insert ribbon > Connections > Server > New OGC API Server
2. Server URL: https://geolens.example.com/api/?api_key=<your-api-key>
3. OK — the connection appears in the Catalog pane under Servers.
4. Expand the connection and drag a collection onto the map.

ArcGIS Pro speaks OGC API Features natively (Pro 2.8 or newer). As with the QGIS and ogr2ogr examples, the ?api_key= query parameter rides along on every request the connection makes; omit it entirely for anonymous access to public datasets.

GDAL export to GeoPackage:

ogr2ogr -f GPKG out.gpkg \
  "OAPIF:https://geolens.example.com/api/?api_key=<your-api-key>" \
  {dataset_id}

The ?api_key= query parameter is the recommended way to authenticate ogr2ogr, since the OAPIF driver does not currently let you set HTTP headers.

STAC 1.0

GeoLens exposes raster collections (and their items) under a STAC 1.0 catalog rooted at /api/stac/. Use any STAC client to search and ingest assets.

Endpoints:

• GET /api/stac/: STAC root catalog.
• GET /api/stac/collections: list of STAC collections.
• POST /api/stac/search: full STAC search (bbox, datetime, collections, intersects, ids).

Curl:

curl https://geolens.example.com/api/stac/

pystac-client:

from pystac_client import Client

client = Client.open("https://geolens.example.com/api/stac/")
search = client.search(
    collections=["my-raster-collection"],
    bbox=[-122.5, 37.5, -122.0, 38.0],
    datetime="2024-01-01/2024-12-31",
)
for item in search.items():
    print(item.id, item.assets["data"].href)

Tile endpoints

GeoLens serves vector and raster tiles via signed access tokens. Tile tokens are not generic API keys. They are HMAC-signed, scoped to a single dataset, and time-limited. They exist so that embedded maps can serve tiles without exposing a permanent credential to the browser.

Vector tile (MVT) URL shape:

https://geolens.example.com/api/tiles/{table_path}/{z}/{x}/{y}.pbf?sig={sig}&exp={exp}&scope={scope}

{table_path} is the schema-qualified table name (e.g. data.my_table), and sig, exp, and scope are the HMAC-signed parameters returned alongside it by POST /api/tiles/tokens/.

Raster tile (Titiler-based) URL shape:

Titiler-rendered raster tiles follow Titiler’s standard /tiles/... URL pattern under /api/. Confirm the exact path in your instance’s auto-generated reference under the Tiles tag.

Obtaining a tile token. Tile tokens are issued by an authenticated request against:

• POST /api/tiles/tokens/: mint a new token for a dataset.
• GET /api/tiles/token/{dataset_id}/: fetch an existing token.

These endpoints accept the same authentication as the rest of the API (X-Api-Key, JWT, OAuth-issued JWT). Tile tokens themselves are not substitutes for those credentials. They are derived, scoped, and expire.

QGIS Add XYZ Tiles:

1. Browser panel > XYZ Tiles > Right-click -> New Connection...
2. Name: GeoLens - <dataset>
   URL:  https://geolens.example.com/api/tiles/{table_path}/{z}/{x}/{y}.pbf?sig=<sig>&exp=<exp>&scope=<scope>
3. Click OK, then drag the connection onto the canvas.

Replace {table_path} and the sig, exp, and scope values with the signed parameters returned by POST /api/tiles/tokens/. Tokens issued in QGIS workflows should be treated as session credentials. Mint a fresh set when the previous one expires.

MapLibre GL JS (vector tile source):

The MVT layer name inside each tile is the same schema-qualified {table_path} as in the URL — use it as the source-layer:

map.addSource('geolens-roads', {
  type: 'vector',
  tiles: [
    'https://geolens.example.com/api/tiles/data.roads/{z}/{x}/{y}.pbf?sig=<sig>&exp=<exp>&scope=<scope>',
  ],
});

map.addLayer({
  id: 'roads-line',
  type: 'line',
  source: 'geolens-roads',
  'source-layer': 'data.roads',
  paint: { 'line-color': '#3b6fd4', 'line-width': 1.5 },
});

Because tile tokens expire, a long-lived custom MapLibre app should mint a fresh token via POST /api/tiles/tokens/ and rebuild the source URL when one lapses. For a zero-code alternative, GeoLens’s built-in share embeds handle tokens for you — see Map Builder.