Exports & Integrations

Ce contenu n’est pas encore disponible dans votre langue.

Exports exist so that nothing you put into GeoLens is stuck there. Every format below is an open one that other tools already read, and the same data is also live over OGC API and STAC without any export step. If you want the full picture of how to move everything out, see Taking your data with you.

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, CSV, or GeoParquet. 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 five export formats, the on-the-fly transformations, the OGC API + STAC integrations, the raster download route, and machine-client examples for QGIS, GDAL, Python, and DuckDB.

Export formats

GeoLens exports vector datasets in the following five 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 | | GeoParquet | parquet | .parquet file | Columnar analytics; readable by DuckDB, GeoPandas, and QGIS |

gpkg is the default: calling /export with no format returns a GeoPackage. Passing a slug outside this table returns an error.

An export is a URL, not a job. GET /api/datasets/{id}/export?format=<slug> answers 200 with the file bytes; there is nothing to submit and no status to poll, so a client can be a single URL inside read_parquet() or ogr2ogr. The route also answers HEAD and byte-range requests, so tools that open a file remotely (GDAL /vsicurl/, DuckDB’s httpfs) can read just the part they need (geolens#1585).

GeoParquet output is a spec-valid GeoParquet 1.1 file and is always emitted in EPSG:4326 (OGC:CRS84) — combining format=parquet with any other target_crs returns a 400. The other four formats reproject freely.

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 an OGC/STAC 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.

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).
Attribute filter: supply a SQL-style boolean expression in ?where=... to restrict the export to features matching it. This supports comparison operators, AND/OR/NOT, IN, IS NULL, LIKE/ILIKE, and BETWEEN over the dataset’s columns only — no function calls and no spatial predicates (use bbox for spatial restriction).
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. ?crs= is not a parameter on this route; it is ignored rather than refused, so you get a 200 with no reprojection applied.

These can be combined: ?format=gpkg&bbox=...&where=...&target_crs=... exports a GeoPackage of only the features within the bbox that match the attribute 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 live OGC API endpoints. Anything you can do through a UI export, you can also reach through a standards-based URL. Any client that speaks these standards (QGIS, ogr2ogr, owslib, pystac-client) reads 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
OGC API Features Part 1 v1.0: Core, GeoJSON
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

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.
GET or 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.
GET or POST /api/stac/search: full STAC search (bbox, datetime, collections, ids, intersects, limit). GET takes the same fields as query parameters.

Every raster item carries a raster_tiles asset whose href is an XYZ tile template rather than a file; see STAC 1.0 for the asset set and Tile endpoints for how the template authenticates.

Machine clients

Once you know the OGC API or STAC URL, plugging it into a tool is a copy-paste exercise. Below are the most common client recipes. Runnable versions live in the examples repo.

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/
   - Version: OGC API - Features
3. Private instance: Authentication > Configurations > +, method
   "API Header", header X-Api-Key = <your-api-key>; select it on the
   connection.
4. Connect -> pick a collection -> Add.

The collection list shows every dataset visible to your API key, and each collection adds as a vector layer. The API Header configuration keeps the key in QGIS’s encrypted auth database instead of the project file; do not put ?api_key= in the connection URL. Keep the trailing slash on /api/. The longer walkthrough, with screenshots and a ready-made project, is qgis/README.md.

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 (raster):

QGIS’s XYZ Tiles connection is raster-only. Use the .png template from the collection’s tiles link:

1. Browser panel > XYZ Tiles > Right-click -> New Connection...
2. Name: GeoLens - <dataset>
   URL:  https://geolens.example.com/raster-tiles/{dataset_id}/tiles/{z}/{x}/{y}.png?v=<n>
3. Private dataset: select the API Header authentication configuration.
4. Click OK, then drag the connection onto the canvas.

Vector tiles (MVT):

1. Layer > Add Layer > Add Vector Tile Layer...
2. New > New Generic Connection...
   - Name: GeoLens - <dataset>
   - URL:  https://geolens.example.com/api/tiles/{table_path}/{z}/{x}/{y}.pbf
3. Private dataset: select the API Header authentication configuration,
   or append ?sig=<sig>&exp=<exp>&scope=<scope> from
   GET /api/tiles/token/{dataset_id}/.
4. Click OK, then add the connection.

{table_path} is data. plus the dataset’s table_name. A pasted tile token expires within 16 minutes; treat it as a session credential and use the authentication configuration for anything longer. See Tile endpoints for how tokens are minted and scoped.

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, so use the query param)
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-01T00:00:00Z/2024-12-31T23:59:59Z",
)

for item in search.items():
    print(item.id, item.assets["raster_tiles"].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],
)

Note that CQL2 filter strings are not accepted on per-dataset feature collections — GeoLens returns HTTP 400. CQL2 applies to the catalog (Records) collection only. For attribute filtering on a dataset’s features, use the export endpoint’s ?where= parameter described above.

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 (spatial subset via bbox)
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"},
)
features = response.json()["features"]

# Attribute filtering uses the export endpoint's ?where= parameter
export = requests.get(
    f"{API}/datasets/<dataset-id>/export",
    headers={"X-Api-Key": KEY},
    params={"format": "geojson", "where": "population > 10000"},
)

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

DuckDB

DuckDB’s spatial and httpfs extensions read a GeoParquet export straight off the URL. Once the server has built the export (the first request builds it), a query that names only a few columns fetches only the byte ranges it needs, and DESCRIBE reads just the footer:

INSTALL spatial; LOAD spatial;
INSTALL httpfs;  LOAD httpfs;

DESCRIBE SELECT *
FROM read_parquet('https://geolens.example.com/api/datasets/<dataset-id>/export?format=parquet');

The geometry column arrives already typed GEOMETRY('OGC:CRS84'), so no ST_GeomFromWKB is needed. For a private dataset, one HTTP secret covers read_parquet and ST_Read:

CREATE SECRET geolens (
    TYPE http,
    SCOPE 'https://geolens.example.com',
    EXTRA_HTTP_HEADERS MAP{'X-Api-Key': '<your-api-key>'}
);

One trap: name the source CRS OGC:CRS84, not EPSG:4326, when you reproject. Both label lon/lat data, but they disagree about axis order, and ST_Transform(geom, 'EPSG:4326', ...) on lon/lat input returns a well-formed answer for the wrong hemisphere. A complete, CI-checked script is duckdb/query.py in the examples repo.

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.
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 for private datasets are HMAC-signed per dataset and short-lived. Treat them as session credentials: mint a new one with GET /api/tiles/token/{dataset_id}/ when an old one expires. Tile tokens are not API keys; they can’t be used to fetch features or metadata.

Exports & Integrations

Export formats

Raster downloads

Live standards URLs (not export formats)

Bbox + attribute filters at export time

OGC API access

Conformance classes

Top-level endpoints

STAC API

Machine clients

QGIS

GDAL / ogr2ogr

Python: pystac-client

Python: owslib

Python: raw `requests`

DuckDB

Tips and gotchas

See also

Exports & Integrations

Export formats

Raster downloads

Live standards URLs (not export formats)

Bbox + attribute filters at export time

OGC API access

Conformance classes

Top-level endpoints

STAC API

Machine clients

QGIS

GDAL / ogr2ogr

Python: pystac-client

Python: owslib

Python: raw requests

DuckDB

Tips and gotchas

See also

Python: raw `requests`