GeoLens

English | Español | Français | Deutsch

Your team's self-hosted spatial data hub: searchable, mappable, and shareable in one place.

GeoLens is an open-source spatial data hub for GIS and data teams: one place to find and work with data on infrastructure you control, with no telemetry. GeoLens itself phones home to nothing, except the default basemap tiles, which load from tiles.openfreemap.org until an admin configures a different one. (Other features you opt into can make outbound calls: AI assist to your chosen OpenAI-compatible endpoint or Anthropic key, OAuth/OIDC sign-in, SMTP, remote/S3 data sources, and off-site backups.) Upload files, create datasets in the browser, register tables already in GeoLens's own PostGIS database without copying them, import one-shot copies from WFS, ArcGIS FeatureServer, or OGC API Features, or reference remote STAC assets live. GeoLens records each dataset's origin, indexes catalog metadata with pg_trgm for fuzzy search out of the box (pgvector adds semantic ranking once you configure an embedding provider and enable semantic search), and serves OGC/STAC APIs that QGIS, ArcGIS, and MapLibre clients connect to natively. Compose, style, and share multi-layer maps right in the browser. Built on FastAPI and React. Deployed with one command.

_{No install required. Browse the sample catalog and maps without an account, or sign in with Google, GitHub, or Microsoft to try the map builder. Demo data may be wiped at any time.}

git clone https://github.com/geolens-io/geolens.git && cd geolens
bash scripts/install.sh   # read it first: it writes .env, generates secrets, runs docker compose up -d
# Open http://localhost:8080, then log in with the credentials you chose

Or the one-line form, which runs the same script and pulls the prebuilt images:

curl -fsSL https://getgeolens.com/install.sh | sh

Images are published for linux/amd64 and linux/arm64. A fresh install runs six containers at about 1.3 GB resident.

The map builder: every Manhattan building extruded to its true roof height and colored by the era it was built, the subway threading beneath, built from open data with scripts/seed-showcase.py

[!NOTE] API stability. The standards surfaces (OGC API Features/Records, STAC, and the tile endpoints) track their specifications and are safe to build against. GeoLens's own REST API can still change between minor releases: contract changes are listed in the CHANGELOG, and breaking ones keep the old form working for at least one more minor release. Hit a rough edge? Open an issue.

Documentation

Full user, admin, and API documentation lives at docs.getgeolens.com. The Reference table below links each guide.

Published artifacts

GeoLens is published through the standard package registries:

pip install geolens          # Python SDK
pip install geolens-cli      # CLI; installs the `geolens` command
pip install geolens-mcp      # MCP server for coding agents (read-only)
npm install @geolens/sdk     # TypeScript/JavaScript SDK

Prebuilt public API and frontend images are published to GitHub Container Registry:

docker pull ghcr.io/geolens-io/geolens-api:latest
docker pull ghcr.io/geolens-io/geolens-frontend:latest

The latest tag tracks the newest published stable release.

Why GeoLens?

Spatial data ends up scattered: shapefiles on shared drives, tables in database schemas, rasters in cloud buckets, metadata in spreadsheets. Finding the right dataset means asking Slack or grepping file servers. Sharing it means exporting, emailing, and hoping the CRS matches.

GeoLens replaces that workflow:

• One data hub: upload files, create datasets, register tables already in GeoLens's database, import feature-service snapshots, or reference remote STAC assets — then search and preview them together
• Source state, not guesswork: see how each dataset entered the catalog, when it was last refreshed or checked, how its last refresh compares with its declared cadence (fresh, due, overdue, or unknown), and whether a remote Service or STAC origin is still reachable
• Works with your tools: OGC API Features/Records with server-side CQL2 filtering, STAC API 1.0, direct tile URLs for QGIS, ArcGIS, and MapLibre
• No lock-in: your catalog and the copies GeoLens manages stay on infrastructure you control and leave through open formats. Vector datasets export to GeoPackage, GeoJSON, Shapefile, CSV, GeoParquet, FlatGeobuf, or PMTiles; rasters download as Cloud-Optimized GeoTIFF; and any OGC API client reads the catalog directly
• Semantic and spatial search: pg_trgm fuzzy matching out of the box; add an embedding provider and enable semantic search to rank datasets by meaning (pgvector)
• Built-in map builder: compose multi-layer maps, style them, and share via public link or embeddable iframe
• AI-assisted (optional): chat with your maps, auto-generate descriptions, search by natural language. Bring an OpenAI-compatible endpoint or Anthropic key, or skip it entirely

See it in action

The examples below use a JWT bearer token. Mint one against the local stack (the login endpoint accepts an OAuth2 password form, so use -d with form fields, not JSON). Substitute your admin username and the password from .env (grep '^GEOLENS_ADMIN_PASSWORD=' .env):

TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login/ \
  -d 'username=admin&password=<your-admin-password>' | jq -r '.access_token')

Semantic search takes a one-time admin setup: an embedding provider and the AI + Semantic Search toggles in the admin AI settings, plus an embedding backfill for data ingested before setup (the search guide walks through it). Once that's on, search datasets by meaning instead of exact keyword matches:

# Semantic search ranks by meaning: "hydrology" surfaces the lake and river
# network datasets whose titles never mention the word
curl "http://localhost:8080/api/search/datasets/?q=hydrology&limit=3" \
  -H "Authorization: Bearer $TOKEN" | jq '.features[].properties.title'

One search-endpoint behavior to know when consuming it programmatically: the first page augments the dataset results with up to five matching collections, so numberReturned can exceed limit on page 0 only. That is deliberate, not a bug — limit still bounds the number of datasets per page.

Every dataset is also a standard OGC API Features endpoint:

# Grab a public collection id from the catalog. Search anonymously (no token) so
# the id is one anyone can read, matching the unauthenticated items request below.
CID=$(curl -s "http://localhost:8080/api/search/datasets/?q=countries&limit=1" \
  | jq -r '.features[0].id')

# GeoJSON features with a bbox filter, works in QGIS, ArcGIS, any OGC client
curl "http://localhost:8080/api/collections/$CID/items?bbox=-10,35,30,60&limit=5"

PostGIS and pgvector share one database, so with semantic search enabled you can rank datasets by meaning inside a spatial window in a single query. See the search guide for how semantic and spatial search work together.

Connect directly from QGIS: Layer > Add WFS / OGC API Features and point at http://localhost:8080/api/.

The same endpoints from the tools you already use: geolens-examples holds single-file MapLibre, Leaflet, OpenLayers and ArcGIS JS pages, QGIS and DuckDB walkthroughs, both GeoLens SDKs, a semantic catalog search, a STAC browser, a saved-map embed, a Python/GeoPandas analysis, a catalog-as-code manifest for the CLI, and an MCP setup. The read-only ones run against the live demo, and CI replays them there on every push and once a week, so what you copy is code that worked this week. Browse the gallery.

Features

Each example above has a full guide in the docs. What GeoLens reads, writes, and exposes:

Data ingestion and export