Python SDK

The GeoLens Python SDK (geolens) is a typed client for the GeoLens API. It ships typed attrs models, an httpx sync/async client, and Bearer-token + API-key auth helpers. It is Apache-2.0 licensed and auto-generated from the OpenAPI contract, so every operation mirrors a real endpoint in the API reference.

Install

pip install geolens

The package targets a modern Python (3.10+) and pulls in httpx and attrs.

Authenticate

Create a GeolensClient pointed at your instance. The deployed API is served under /api — include that suffix in base_url:

from geolens import GeolensClient

client = GeolensClient(
    base_url="https://geolens.example.com/api",
    bearer_token="...",  # a JWT from POST /api/auth/login
)

You get a bearer token the same way the CLI and any raw client do — POST /api/auth/login returns a JWT. See Authentication for the full token-acquisition flow.

The SDK supports the same two header auth modes as the rest of GeoLens — Bearer or API key, but not both:

# API-key auth instead of a bearer token (sent as X-API-Key):
client = GeolensClient(
    base_url="https://geolens.example.com/api",
    api_key="...",
)

Reuse a token from the environment

For scripts and CI, read the token from the environment instead of hard-coding it — the same GEOLENS_TOKEN convention the CLI uses:

import os
from geolens import GeolensClient

client = GeolensClient(
    base_url=os.environ["GEOLENS_INSTANCE"],  # e.g. https://geolens.example.com/api
    bearer_token=os.environ["GEOLENS_TOKEN"],
)

Passing both bearer_token and api_key raises ValueError. With neither, the client is anonymous and can only reach public endpoints.

First call

Operations live under geolens.api.<tag> and each exposes sync, sync_detailed, asyncio, and asyncio_detailed. Pass the underlying client via client.client.

The health check is the simplest read — no parameters, no auth required:

from geolens import GeolensClient
from geolens.api.health import health_health_get

client = GeolensClient(base_url="https://geolens.example.com/api")

# sync() returns the parsed model (HealthResponse) or None.
health = health_health_get.sync(client=client.client)
print(health.status)              # e.g. "ok"
print(health.providers)           # HealthResponseProviders — per-service status

Need the status code and headers too? Use sync_detailed, which returns a Response[HealthResponse] wrapper:

resp = health_health_get.sync_detailed(client=client.client)
print(resp.status_code)           # HTTPStatus.OK
print(resp.parsed.status)         # the parsed HealthResponse

Every operation also has an asyncio variant for the httpx async client:

import asyncio
from geolens import GeolensClient
from geolens.api.health import health_health_get

async def main() -> None:
    client = GeolensClient(base_url="https://geolens.example.com/api")
    health = await health_health_get.asyncio(client=client.client)
    print(health.status)

asyncio.run(main())

Authenticated reads follow the same shape — for example, searching the catalog uses geolens.api.search.search_datasets_endpoint_search_datasets_get and returns a typed OGCFeatureCollectionResponse.

Next steps

• Authentication — how to obtain a bearer token or API key.
• API reference — the full operation surface; every geolens.api.* function maps to an endpoint here.
• CLI & Manifests — for terminal and CI workflows; the CLI wraps this SDK.
• TypeScript SDK — the same surface for Node.