Exports & Integrations

Consejo

Replace https://geolens.example.com with your GeoLens instance’s URL in every example below. The same exports surface drives both the UI’s Export menu and the /api/datasets/{id}/export endpoint, so anything you can do interactively, you can also do from the command line or script.

GeoLens exports any catalogued vector dataset to a portable file — so the data can move into another system. Vector datasets export to GeoPackage, GeoJSON, Shapefile, or CSV. Every export accepts optional bbox, attribute filter, and CRS reprojection at request time, so the file you save is exactly the subset you need.

Beyond file downloads, the catalog is also reachable through live standards URLs — OGC API Features and STAC — that you point a client at directly (these are standards endpoints, not export formats). Raster datasets are downloaded as a Cloud-Optimized GeoTIFF via a separate download route.

This page covers the four export formats, the on-the-fly transformations, the OGC API + STAC integrations, the raster download route, and machine-client examples for QGIS, GDAL, and Python.

Export formats

GeoLens exports vector datasets in the following four formats. The format is selected from the Export menu on any dataset detail page, or by passing ?format=<slug> to the /api/datasets/{id}/export endpoint.

Format	Slug	Output	Best for
GeoPackage	gpkg	.gpkg file	Vector with metadata preserved; the best general-purpose format (default)
GeoJSON	geojson	.geojson file	Web / portable; small to medium datasets
Shapefile	shp	.zip archive	Legacy GIS interop; required by some older tools
CSV	csv	.csv file	Tabular only; geometry preserved as WKT in a single column

gpkg is the default — calling /export with no format returns a GeoPackage. Passing any other slug returns an error.

Raster downloads

Raster datasets aren’t part of the vector export menu. Download a raster as a Cloud-Optimized GeoTIFF (COG) from its dataset detail page, which calls GET /api/datasets/{id}/download/cog.

Live standards URLs (not export formats)

OGC API Features and STAC are live URL endpoints, not file formats — you point a standards-compliant client at the URL and it reads against live data, so subsequent edits to the underlying dataset propagate through automatically. See the OGC API access and STAC API sections below for the URL patterns, and OGC API & Standards Endpoints for the authoritative per-route reference.

Bbox + attribute filters at export time

Any export can apply transformations at request time, before the file is written:

• Bbox — restrict the export to features (or raster pixels) within a bounding box. Supplied as ?bbox=west,south,east,north (EPSG:4326).
• CQL2 filter — supply a CQL2 expression in ?where=... to restrict to features matching the expression. The CQL2 grammar is the same one the search filter rail uses, and the same one documented in OGC API & Standards Endpoints.
• CRS reprojection — supply ?target_crs=EPSG:<code> (e.g., ?target_crs=EPSG:3857) to reproject geometry on output. Useful when the consuming tool expects a specific projection.
• Column subset — supply ?columns=col1,col2,col3 to include only named columns. Useful for reducing file size when the consumer doesn’t need every attribute.

These can be combined: ?format=gpkg&bbox=...&where=...&target_crs=... exports a GeoPackage of only the features within the bbox that match the CQL2 filter, reprojected.

The UI’s export dialog exposes the same options as form fields — bbox draggable on a small map, filter expression in a text input, target CRS as a searchable dropdown.

OGC API access

GeoLens exposes the catalog as a set of OGC API standards-compliant endpoints. Anything you can do through a UI export, you can also reach through a standards-based URL — and any standards-compliant client (QGIS, ogr2ogr, owslib, pystac-client) speaks them natively.

Conformance classes

GeoLens implements the following OGC API and STAC conformance classes:

OGC API

• OGC API Common Part 1 v1.0 — Core, Landing Page, JSON, OAS 3.0
• OGC API Features Part 1 v1.0 — Core, GeoJSON, OAS 3.0
• OGC API Features Part 3 v1.0 — Filter, Features Filter
• CQL2 v1.0 — Text, JSON, Basic CQL2
• OGC API Records Part 1 v1.0 — Record Core, Query Parameters, Sorting, JSON

STAC API v1.0

• STAC API Core
• STAC Collections
• STAC Item Search
• STAC OGC API Features integration

For per-route schemas, the full conformance-class URI list, and curl examples on every endpoint, see OGC API & Standards Endpoints — that page is the authoritative API-side reference. This page lists the access patterns at a higher level so you can pick the right entry point.

Top-level endpoints

• GET /api/ — OGC API Common landing document; entry point for any OGC client.
• GET /api/conformance — list of conformance class URIs.
• GET /api/collections/datasets/items — OGC API Records collection; the catalog itself, listable and CQL2-filterable.
• GET /api/collections/{dataset_id}/items — OGC API Features collection; per-dataset feature access.
• GET /api/stac/ — STAC root; for raster collections.
• POST /api/stac/search — STAC Item Search.

The OGC API Records endpoint mirrors the catalog search you use in the UI; the OGC API Features endpoints mirror the per-dataset data tab in machine-readable form.

STAC API

For raster collections, GeoLens also exposes a STAC 1.0 catalog at /api/stac/. STAC clients can search items, list collections, and fetch asset URLs:

• GET /api/stac/ — STAC root catalog (browseable directly from a browser).
• GET /api/stac/collections — list all STAC collections.
• GET /api/stac/collections/{id} — single collection metadata.
• GET /api/stac/collections/{id}/items — list items in a collection.
• POST /api/stac/search — full STAC search (bbox, datetime, collections, intersects, query).

STAC items carry asset URLs pointing at the underlying raster files. For authenticated instances, asset URLs accept the same authentication as the rest of the API.

Machine clients

Once you know the OGC API or STAC URL, plugging it into a tool is a copy-paste exercise. Below are the four most common client recipes.

QGIS

QGIS speaks OGC API Features and OGC API Records natively from version 3.30+. There’s no plugin install — both connection types are built in.

OGC API Features (vector data):

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 a collection → Add.

The collection list shows every dataset visible to your API key, and each collection adds as a vector layer.

OGC API Records (catalog search):

1. Web ▸ MetaSearch ▸ MetaSearch (built-in plugin, no install)
2. Services tab ▸ New
   - Name: GeoLens
   - URL: https://geolens.example.com/api/
   - Catalog Type: OGC API - Records
3. Save → Search tab ▸ search by keyword, bbox, or CQL2.

This gives QGIS users a “search GeoLens from inside QGIS” experience — useful for big catalogs where browsing the full list is impractical.

XYZ tiles:

1. Browser panel ▸ XYZ Tiles ▸ Right-click → New Connection…
2. Name: GeoLens — <dataset>
   URL:  https://geolens.example.com/api/tiles/{dataset_id}/{z}/{x}/{y}.pbf?token=<token>
3. OK → drag the connection onto the canvas.

Replace <token> with a tile token obtained from POST /api/tiles/tokens/. Tile tokens are short-lived; treat them as session credentials.

GDAL / ogr2ogr

GDAL’s OAPIF driver speaks OGC API Features over HTTP. Useful for scripted exports, format conversion, or pulling subsets without using the UI:

# List collections
ogrinfo OAPIF:https://geolens.example.com/api/

# Download a collection to GeoPackage
ogr2ogr -f GPKG out.gpkg \
  OAPIF:https://geolens.example.com/api/ \
  <collection-id>

# With API key (header doesn't work in OAPIF — must use query)
ogrinfo "OAPIF:https://geolens.example.com/api/?api_key=YOUR_KEY"

# Convert to Shapefile, restricting to bbox + attribute filter
ogr2ogr -f "ESRI Shapefile" out.shp \
  "OAPIF:https://geolens.example.com/api/?api_key=YOUR_KEY" \
  <collection-id> \
  -spat -122.5 37.5 -122.0 38.0 \
  -where "population > 10000"

The OAPIF driver’s ?api_key= query-string auth is the recommended way to authenticate ogr2ogr against a private GeoLens instance — the OAPIF driver doesn’t currently let you set HTTP headers, so the header-form API key won’t work here.

Python — pystac-client

For STAC catalogs, pystac-client is the canonical client:

from pystac_client import Client

client = Client.open("https://geolens.example.com/api/stac/")

# Find recent items in a collection
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)

For an authenticated instance, supply a Modifier to inject the API key header into every request:

from pystac_client import Client

def add_api_key(request):
    request.headers["X-Api-Key"] = "<your-api-key>"
    return request

client = Client.open(
    "https://geolens.example.com/api/stac/",
    request_modifier=add_api_key,
)

Python — owslib

For OGC API Features and OGC API Records (vector + catalog), owslib is the generic OGC client:

from owslib.ogcapi.features import Features

features = Features("https://geolens.example.com/api/")

# List collections
for c in features.feature_collections():
    print(c["id"], c["title"])

# Pull a collection's items
items = features.collection_items(
    "my-vector-collection",
    bbox=[-122.5, 37.5, -122.0, 38.0],
)

owslib’s API supports CQL2 filter strings via the same ?filter= parameter the OGC API Features endpoint accepts.

Python — raw requests

For workflows where pystac-client and owslib are too heavy, GeoLens’s endpoints are plain HTTP-and-JSON; requests is enough:

import requests

API = "https://geolens.example.com/api"
KEY = "<your-api-key>"

# Fetch a dataset's features as GeoJSON
response = requests.get(
    f"{API}/collections/my-vector-collection/items",
    headers={"X-Api-Key": KEY},
    params={
        "bbox": "-122.5,37.5,-122.0,38.0",
        "filter": "population > 10000",
        "filter-lang": "cql2-text",
    },
)
features = response.json()["features"]

For authentication options (JWT, header-form API key, query-string API key, OAuth-issued JWT), see API Authentication.

Tips and gotchas

• Shapefile column names. Shapefile truncates column names to 10 characters. GeoLens preserves the original column names in the catalog, but on Shapefile export, names are truncated and possibly renamed to resolve collisions. If you need full names, use GeoPackage or GeoJSON.
• CSV and geometry. CSV exports preserve geometry as WKT in a column named wkt_geometry by default. To omit geometry from a CSV export, use ?columns= to list only the columns you want.
• Reprojection accuracy. Reprojection in ?target_crs= uses PROJ-default transformations. For projects that require a specific datum-shift grid, reproject locally with GDAL after export instead of relying on ?target_crs=.
• Tile URL caveats. Tile URLs are HMAC-signed per dataset and short-lived. Treat them as session credentials — mint a new one with POST /api/tiles/tokens/ when an old one expires. Tile tokens are not API keys; they can’t be used to fetch features or metadata.

See also

• Dataset detail — exports originate from any dataset’s detail page
• OGC API & Standards Endpoints — full machine-client API reference (per-endpoint schemas, conformance URIs, every example reproduced)
• API Authentication — API keys and JWTs for ogr2ogr, pystac-client, and any non-UI client