geolens

# GeoLens

[English](README.md) | [Español](README.es.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [简体中文](README.zh.md)

**Turn scattered GIS files into a searchable catalog and shareable maps—on your own infrastructure.**

GeoLens brings files, database tables, service snapshots, and remote assets into one spatial catalog you control. Search metadata, preview data, and keep every dataset’s origin visible. Build maps in the browser, publish links or embeds, and keep using QGIS and open standards alongside your team’s existing tools.

<p align="center">
  <a href="https://demo.getgeolens.com"><img src="https://img.shields.io/badge/%E2%96%B6%20Try%20the%20live%20demo-demo.getgeolens.com-2563eb?style=for-the-badge" alt="Try the live demo" /></a>
  <br />
  <sub>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.</sub>
</p>

<p align="center">
  <a href="https://demo.getgeolens.com/maps"><img src=".github/assets/geolens-manhattan-3d-hero.jpg" alt="GeoLens map builder with Manhattan building footprints extruded into a 3D skyline, colored by construction era, with the subway and the drag-orderable layer stack beside the map" width="900" /></a>
  <br />
  <em>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 <code>scripts/seed-showcase.py</code></em>
</p>

## What you can do

- **Find datasets:** search one catalog across file uploads, database tables, and imported service snapshots.
- **Build and share maps:** compose multi-layer maps in the browser, then publish a link or embed them where people work.
- **Use your existing tools:** connect QGIS, ArcGIS, MapLibre, and scripts through OGC/STAC APIs and direct tile URLs.

[![CI](https://github.com/geolens-io/geolens/actions/workflows/ci.yml/badge.svg)](https://github.com/geolens-io/geolens/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python: backend 3.13+ / SDK 3.10+](https://img.shields.io/badge/python-3.13%2B_backend_%7C_3.10%2B_SDK-blue.svg)](https://www.python.org/)
[![PostgreSQL 18 + PostGIS 3.6](https://img.shields.io/badge/PostGIS_3.6-PostgreSQL_18-336791.svg)](https://postgis.net/)
[![OGC API](https://img.shields.io/badge/OGC_API-Features_%7C_Records-green.svg)](https://ogcapi.ogc.org/)

```bash
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:

```bash
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.

## Privacy, outbound connections, and data sources

GeoLens has no telemetry and phones home to nothing, except default basemap tiles from tiles.openfreemap.org until an administrator configures another provider. 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 or S3 data sources, and off-site backups.

Upload files, create datasets in the browser, or register tables already in GeoLens’s own PostGIS database without copying them. WFS, ArcGIS FeatureServer, and OGC API Features imports create one-shot copies; remote STAC assets remain live references. GeoLens records each dataset’s origin, indexes catalog metadata with pg_trgm for fuzzy search, and can add pgvector semantic ranking after you configure an embedding provider and enable semantic search.

> [!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](CHANGELOG.md), and breaking
> ones keep the old form working for at least one more minor release. Hit a
> rough edge? [Open an issue](https://github.com/geolens-io/geolens/issues).

## Documentation

Full user, admin, and API documentation lives at **[docs.getgeolens.com](https://docs.getgeolens.com)**. The [Reference](#reference) table below links each guide.

## Published artifacts

GeoLens is published through the standard package registries:

```bash
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:

```bash
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`):

```bash
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](https://docs.getgeolens.com/guides/user/search/) walks through it). Once that's on, search datasets by meaning instead of exact keyword matches:

```bash
# 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:

```bash
# 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](https://docs.getgeolens.com/guides/user/search/) 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](https://github.com/geolens-io/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](https://geolens-io.github.io/geolens-examples/).

## Features

Each example above has a full guide in the [docs](https://docs.getgeolens.com/guides/). What GeoLens reads, writes, and exposes:

### Data ingestion and export

- **Five source modes:** Uploaded and Created data ar