lodapi 0.0.1__py3-none-any.whl

lodapi/__init__.py

@@ -0,0 +1,61 @@
+"""lodapi — ergonomic Python SDK for the Lodapi REST API.
+
+    from lodapi import Client
+    c = Client(api_key="lod_...")          # api_key optional → free tier
+    page = c.buildings(bbox=(7.0, 50.9, 7.1, 51.0), limit=500)
+
+v0 / unstable: the public surface may change before 0.1. See the README.
+"""
+
+from __future__ import annotations
+
+from ._http import QuotaInfo
+from .client import Client, __version__
+from .exceptions import (
+    ApiError,
+    AuthError,
+    LodapiError,
+    NotFoundError,
+    RateLimitError,
+)
+from .models import (
+    BuildingDetail,
+    BuildingRoofResponse,
+    BuildingsBboxResponse,
+    Dataset,
+    DatasetListResponse,
+    ElevationResponse,
+    TerrainDataset,
+    TerrainDatasetListResponse,
+    TerrainMeshDataset,
+    TerrainMeshDatasetListResponse,
+    TerrainProfileResponse,
+    Tileset,
+    TilesetListResponse,
+)
+
+__all__ = [
+    "Client",
+    "QuotaInfo",
+    "__version__",
+    # exceptions
+    "LodapiError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ApiError",
+    # models
+    "BuildingsBboxResponse",
+    "BuildingDetail",
+    "BuildingRoofResponse",
+    "DatasetListResponse",
+    "Dataset",
+    "ElevationResponse",
+    "TerrainProfileResponse",
+    "TerrainDatasetListResponse",
+    "TerrainDataset",
+    "TerrainMeshDatasetListResponse",
+    "TerrainMeshDataset",
+    "TilesetListResponse",
+    "Tileset",
+]

lodapi/_geo.py

@@ -0,0 +1,30 @@
+"""Optional GeoDataFrame conversion (``pip install lodapi[geo]``).
+
+Kept in its own module with a lazy import so the core SDK imports fine
+without geopandas/shapely installed. ``to_geodataframe`` raises a clear,
+actionable error when the extra is missing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+_INSTALL_HINT = (
+    "GeoDataFrame support requires the optional 'geo' extra. "
+    "Install it with:  pip install lodapi[geo]"
+)
+
+
+def features_to_geodataframe(features: Sequence[dict[str, Any]]) -> Any:
+    """Convert a list of GeoJSON features to a ``geopandas.GeoDataFrame``.
+
+    Raises ``ImportError`` with an install hint when geopandas is absent.
+    """
+    try:
+        import geopandas as gpd  # noqa: PLC0415 — lazy by design
+    except ImportError as exc:  # pragma: no cover - exercised via monkeypatch
+        raise ImportError(_INSTALL_HINT) from exc
+
+    # GeoDataFrame.from_features handles the GeoJSON Feature shape directly.
+    # Buildings are WGS84 (EPSG:4326).
+    return gpd.GeoDataFrame.from_features(list(features), crs="EPSG:4326")

lodapi/_http.py

@@ -0,0 +1,227 @@
+"""Thin sync HTTP transport over httpx.
+
+Owns the cross-cutting concerns shared by every resource:
+
+- ``X-API-Key`` header injection (only when a key is configured; the Lodapi
+  free tier is anonymous, see ADR-0014).
+- RFC 7807 ``application/problem+json`` error parsing → typed exceptions.
+- Soft-quota header capture (``X-Lodapi-Quota-Used`` / ``-Limit``) into a
+  ``QuotaInfo`` exposed on the client as ``last_quota`` — never an error.
+- Retries on transient 5xx and network/timeout errors with exponential
+  backoff. **Never** retries 4xx (those are deterministic).
+
+v0 is sync only. The structure (a single ``_request`` chokepoint) is kept so
+an async sibling (``_AsyncHttpClient`` over ``httpx.AsyncClient``) can be
+added later without touching the resources.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import ApiError, LodapiError
+
+DEFAULT_BASE_URL = "https://api.lodapi.de"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2  # => up to 3 total attempts on transient failures
+_RETRY_BACKOFF_BASE = 0.5  # seconds; doubled each retry
+
+_QUOTA_USED_HEADER = "X-Lodapi-Quota-Used"
+_QUOTA_LIMIT_HEADER = "X-Lodapi-Quota-Limit"
+
+
+@dataclass(frozen=True)
+class QuotaInfo:
+    """Soft-quota visibility from the last response's headers (ADR-0014).
+
+    ``used`` / ``limit`` are ``None`` when the header was absent (anonymous
+    calls, or a key without a configured monthly quota). Quota is *soft* —
+    exceeding it is never an error in the MVP.
+    """
+
+    used: Optional[int] = None
+    limit: Optional[int] = None
+
+    @property
+    def remaining(self) -> Optional[int]:
+        if self.used is None or self.limit is None:
+            return None
+        return max(0, self.limit - self.used)
+
+
+def _parse_quota(headers: httpx.Headers) -> QuotaInfo:
+    def _int(name: str) -> Optional[int]:
+        raw = headers.get(name)
+        if raw is None:
+            return None
+        try:
+            return int(raw)
+        except (TypeError, ValueError):
+            return None
+
+    return QuotaInfo(used=_int(_QUOTA_USED_HEADER), limit=_int(_QUOTA_LIMIT_HEADER))
+
+
+class HttpClient:
+    """Synchronous HTTP client wrapping a long-lived ``httpx.Client``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        user_agent: str,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        headers = {
+            "User-Agent": user_agent,
+            "Accept": "application/json",
+        }
+        if api_key:
+            headers["X-API-Key"] = api_key
+        self._max_retries = max(0, max_retries)
+        self.last_quota: QuotaInfo = QuotaInfo()
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+            follow_redirects=True,
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- core --------------------------------------------------------------
+
+    def _send(self, request: httpx.Request) -> httpx.Response:
+        """Send with retry on transient 5xx / network errors. Never on 4xx."""
+        attempt = 0
+        while True:
+            try:
+                response = self._client.send(request, stream=True)
+            except (httpx.TransportError, httpx.TimeoutException) as exc:
+                if attempt >= self._max_retries:
+                    raise LodapiError(
+                        f"Network error after {attempt + 1} attempt(s): {exc}"
+                    ) from exc
+                time.sleep(_RETRY_BACKOFF_BASE * (2 ** attempt))
+                attempt += 1
+                continue
+
+            # Retry transient server errors only.
+            if response.status_code >= 500 and attempt < self._max_retries:
+                response.close()
+                time.sleep(_RETRY_BACKOFF_BASE * (2 ** attempt))
+                attempt += 1
+                continue
+            return response
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code < 400:
+            return
+        # Read the (possibly problem+json) body for diagnostics.
+        try:
+            response.read()
+            body: Any = response.json()
+        except Exception:  # noqa: BLE001 — body may be empty / non-JSON
+            body = response.text or None
+        raise LodapiError.from_problem(response.status_code, body)
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Perform a request and return the decoded JSON body."""
+        request = self._client.build_request(method, path, params=_clean(params))
+        response = self._send(request)
+        try:
+            self.last_quota = _parse_quota(response.headers)
+            self._raise_for_status(response)
+            response.read()
+            try:
+                return response.json()
+            except Exception as exc:  # noqa: BLE001
+                raise ApiError(
+                    f"Expected JSON from {path} but could not decode body."
+                ) from exc
+        finally:
+            response.close()
+
+    def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        out: Any | None = None,
+    ) -> bytes | int:
+        """Perform a request and return raw bytes, or stream to ``out``.
+
+        - ``out=None`` → returns the full ``bytes`` body.
+        - ``out`` is a path / file-like → streams the body there and returns
+          the number of bytes written.
+
+        If the server answers with JSON (the GLB endpoint may, e.g. on an
+        empty bbox), that JSON is treated as an error/diagnostic and raised as
+        ``ApiError`` so callers don't silently write a JSON blob to ``city.glb``.
+        """
+        request = self._client.build_request(method, path, params=_clean(params))
+        response = self._send(request)
+        try:
+            self.last_quota = _parse_quota(response.headers)
+            self._raise_for_status(response)
+
+            content_type = response.headers.get("content-type", "")
+            if content_type.startswith("application/json"):
+                response.read()
+                try:
+                    body = response.json()
+                except Exception:  # noqa: BLE001
+                    body = response.text
+                raise ApiError(
+                    "Server returned JSON instead of a binary GLB "
+                    "(likely an empty bbox or a diagnostic message).",
+                    status=response.status_code,
+                    raw=body,
+                )
+
+            if out is None:
+                response.read()
+                return response.content
+
+            written = 0
+            if hasattr(out, "write"):
+                for chunk in response.iter_bytes():
+                    written += out.write(chunk)
+            else:
+                with open(out, "wb") as fh:
+                    for chunk in response.iter_bytes():
+                        written += fh.write(chunk)
+            return written
+        finally:
+            response.close()
+
+
+def _clean(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Drop ``None`` values so we don't send empty query params."""
+    if not params:
+        return params
+    return {k: v for k, v in params.items() if v is not None}

lodapi/client.py

@@ -0,0 +1,108 @@
+"""The top-level :class:`Client` — the SDK entry point.
+
+    from lodapi import Client
+
+    c = Client(api_key="lod_...")          # api_key optional (None => free tier)
+    page = c.buildings(bbox=(7.0, 50.9, 7.1, 51.0), limit=500)
+    for feat in c.buildings.iter(bbox=(7.0, 50.9, 7.1, 51.0)):
+        ...
+    h = c.terrain.elevation(lat=50.94, lon=7.05)
+    ds = c.datasets()
+    c.last_quota                            # soft-quota visibility (or None-ish)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Optional
+
+import httpx
+
+from ._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    HttpClient,
+    QuotaInfo,
+)
+from .models import DatasetListResponse
+from .resources.buildings import BuildingsResource
+from .resources.terrain import TerrainResource
+from .resources.tilesets import TilesetsResource
+
+try:
+    __version__ = version("lodapi")
+except PackageNotFoundError:  # pragma: no cover - editable/uninstalled
+    __version__ = "0.0.1"
+
+
+class Client:
+    """Synchronous client for the Lodapi REST API.
+
+    Parameters
+    ----------
+    api_key:
+        Optional ``lod_*`` API key. ``None`` (the default) uses the anonymous
+        free tier. A malformed/unknown/revoked key raises ``AuthError`` on the
+        first call.
+    base_url:
+        API base URL. Defaults to ``https://api.lodapi.de``.
+    timeout:
+        Per-request timeout in seconds (default 30).
+    max_retries:
+        Retries on transient 5xx / network errors (default 2 → up to 3 tries).
+        4xx are never retried.
+    transport:
+        Optional ``httpx.BaseTransport`` (e.g. for tests / custom routing).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent=f"lodapi-python/{__version__}",
+            transport=transport,
+        )
+        self.buildings = BuildingsResource(self._http)
+        self.terrain = TerrainResource(self._http)
+        self.tilesets = TilesetsResource(self._http)
+
+    # -- top-level endpoints ----------------------------------------------
+
+    def datasets(self) -> DatasetListResponse:
+        """GET /v1/datasets — available LoD2 datasets (one per BL snapshot)."""
+        data = self._http.request_json("GET", "/v1/datasets")
+        return DatasetListResponse.model_validate(data)
+
+    # -- quota visibility --------------------------------------------------
+
+    @property
+    def last_quota(self) -> QuotaInfo:
+        """Soft-quota figures (``used`` / ``limit``) from the last response.
+
+        Populated from ``X-Lodapi-Quota-*`` headers (ADR-0014). Both fields are
+        ``None`` for anonymous calls or keys without a configured quota.
+        Exceeding quota is **not** an error in the MVP.
+        """
+        return self._http.last_quota
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

lodapi/exceptions.py

@@ -0,0 +1,102 @@
+"""Exception hierarchy for the Lodapi SDK.
+
+All API errors follow the RFC 7807 ``application/problem+json`` contract
+(base ``https://lodapi.de/errors``). When the server returns a problem
+document we parse its fields (``type``, ``title``, ``status``, ``detail``,
+``instance``) onto the raised exception so callers can introspect them.
+
+    try:
+        c.buildings(bbox=(...))
+    except AuthError as exc:
+        print(exc.status, exc.detail)   # 401, "Malformed API key ..."
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class LodapiError(Exception):
+    """Base class for every error raised by the SDK.
+
+    Attributes mirror the RFC 7807 problem document. They may be ``None`` if
+    the server response was not a problem+json body (e.g. a transport error or
+    an unexpected non-JSON payload).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        type: str | None = None,
+        title: str | None = None,
+        detail: str | None = None,
+        instance: str | None = None,
+        raw: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.title = title
+        self.detail = detail
+        self.instance = instance
+        # The raw decoded body (dict) or text, for debugging / forward-compat.
+        self.raw = raw
+
+    @classmethod
+    def from_problem(
+        cls,
+        status_code: int,
+        body: Any,
+        *,
+        fallback_message: str | None = None,
+    ) -> "LodapiError":
+        """Build the most specific subclass from an HTTP status + parsed body.
+
+        ``body`` is the decoded JSON (ideally an RFC 7807 dict) or, when the
+        response wasn't JSON, the raw text / ``None``.
+        """
+        problem: dict[str, Any] = body if isinstance(body, dict) else {}
+        detail = problem.get("detail")
+        title = problem.get("title")
+        message = detail or title or fallback_message or f"HTTP {status_code}"
+
+        exc_cls = _STATUS_MAP.get(status_code, ApiError)
+        return exc_cls(
+            message,
+            status=problem.get("status", status_code),
+            type=problem.get("type"),
+            title=title,
+            detail=detail,
+            instance=problem.get("instance"),
+            raw=body,
+        )
+
+
+class AuthError(LodapiError):
+    """401 — malformed, unknown, or revoked API key."""
+
+
+class NotFoundError(LodapiError):
+    """404 — resource (building / tileset / …) not found."""
+
+
+class RateLimitError(LodapiError):
+    """429 — too many requests.
+
+    The Concierge-Billing MVP treats quota as *soft* (no 429 today, see
+    ADR-0014), but the SDK maps 429 here in case hard limits land later.
+    """
+
+
+class ApiError(LodapiError):
+    """Any other non-2xx API response (4xx/5xx not covered above)."""
+
+
+# Status-code → exception subclass. Anything unmapped falls back to ApiError.
+_STATUS_MAP: dict[int, type[LodapiError]] = {
+    401: AuthError,
+    404: NotFoundError,
+    429: RateLimitError,
+}

lodapi/models.py

@@ -0,0 +1,234 @@
+"""Pydantic v2 response models for the Lodapi SDK.
+
+These are *hand-written*, derived from the OpenAPI snapshot at
+``04_engineering/api/openapi/openapi.json`` (components.schemas + the 200
+responses of the public endpoints). For v0 with ~11 endpoints this is leaner
+and more maintainable than a full codegen (openapi-python-client) step.
+
+Regeneration / future codegen path
+-----------------------------------
+When the surface grows or churns, the path is:
+
+  1. Refresh the snapshot:  the API emits it at ``GET /openapi.json``; the
+     repo copy lives at ``04_engineering/api/openapi/openapi.json``.
+  2. Either keep editing this file by hand against the new schemas, OR adopt
+     codegen, e.g.::
+
+         uvx openapi-python-client generate \\
+             --path 04_engineering/api/openapi/openapi.json
+
+     and re-point the resources/* at the generated models. The resource
+     facade (``client.py`` + ``resources/``) is intentionally decoupled from
+     the model layer so swapping the model source is mechanical.
+
+Design notes
+------------
+- ``model_config = ConfigDict(extra="allow")`` everywhere: the API is young
+  and may add fields; we never want a new server field to raise on parse.
+- GeoJSON Feature lists are typed as ``list[dict]`` (matching the API's own
+  choice — see TerrainProfileResponse docstring in the OpenAPI) because the
+  feature schema is polymorphic and strict typing would cost more than it pays.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+# --------------------------------------------------------------------------
+# /v1/buildings
+# --------------------------------------------------------------------------
+
+class BuildingsBboxAttribution(_Model):
+    bundesland: str
+    license: Optional[str] = None
+    attribution_text: Optional[str] = None
+
+
+class BuildingsBboxLodapiMeta(_Model):
+    next: Optional[str] = None
+    attribution: list[BuildingsBboxAttribution] = Field(default_factory=list)
+
+
+class BuildingsBboxResponse(_Model):
+    """GET /v1/buildings — federated GeoJSON FeatureCollection for a WGS84 bbox."""
+
+    type: str = "FeatureCollection"
+    bbox: list[float]
+    count: int
+    limit: int
+    features: list[dict[str, Any]]
+    lodapi: BuildingsBboxLodapiMeta
+
+    @property
+    def next_cursor(self) -> Optional[str]:
+        """Opaque cursor for the next page, or ``None`` when exhausted."""
+        return self.lodapi.next
+
+    def to_geodataframe(self) -> Any:
+        """Convert this page's features to a ``geopandas.GeoDataFrame``.
+
+        Requires the optional ``geo`` extra (``pip install lodapi[geo]``);
+        raises ``ImportError`` with an install hint otherwise. Note this
+        converts only the *current page* — collect features across pages via
+        ``client.buildings.iter()`` if you need everything.
+        """
+        from ._geo import features_to_geodataframe
+
+        return features_to_geodataframe(self.features)
+
+
+# --------------------------------------------------------------------------
+# /v1/buildings/{gmlid}  and  /v1/buildings/{gmlid}/roof
+# --------------------------------------------------------------------------
+
+class BuildingDetail(_Model):
+    gmlid: str
+    bundesland_code: str
+    building_id: int
+    geometry: Optional[dict[str, Any]] = None
+    lod: str = "LoD2"
+
+
+class BuildingRoofResponse(_Model):
+    """GET /v1/buildings/{gmlid}/roof — GeoJSON FeatureCollection of RoofSurfaces."""
+
+    type: str = "FeatureCollection"
+    features: list[dict[str, Any]]
+    count: int
+
+    def to_geodataframe(self) -> Any:
+        """Convert the RoofSurface features to a ``geopandas.GeoDataFrame``.
+
+        Requires the optional ``geo`` extra (``pip install lodapi[geo]``).
+        """
+        from ._geo import features_to_geodataframe
+
+        return features_to_geodataframe(self.features)
+
+
+# --------------------------------------------------------------------------
+# /v1/datasets
+# --------------------------------------------------------------------------
+
+class Dataset(_Model):
+    id: str
+    bundesland_code: str
+    name: str
+    license_id: str
+    snapshot_date: Optional[date] = None
+    building_count: Optional[int] = None
+    validation_pass_pct: Optional[float] = None
+    source_url: Optional[str] = None
+    last_sync: Optional[datetime] = None
+
+
+class DatasetListResponse(_Model):
+    datasets: list[Dataset]
+    count: int
+
+
+# --------------------------------------------------------------------------
+# /v1/terrain/datasets
+# --------------------------------------------------------------------------
+
+class TerrainDataset(_Model):
+    bl: str
+    snapshot: Optional[str] = None
+    source: Optional[str] = None
+    license: Optional[str] = None
+    attribution: Optional[str] = None
+    crs: Optional[str] = None
+    vertical_datum: Optional[str] = None
+    format: Optional[str] = None
+    tile_count: Optional[int] = None
+    coverage_pct: Optional[float] = None
+
+
+class TerrainDatasetListResponse(_Model):
+    datasets: list[TerrainDataset]
+    count: int
+
+
+# --------------------------------------------------------------------------
+# /v1/terrain-mesh/datasets
+# --------------------------------------------------------------------------
+
+class TerrainMeshDataset(_Model):
+    bundesland_code: str
+    snapshot_date: str
+    tileset_url: str
+    license: str
+    built_at: str
+    attribution: Optional[str] = None
+    tile_count: Optional[int] = None
+    tiling_scheme: Optional[str] = None
+    rtin_tolerance_m: Optional[float] = None
+
+
+class TerrainMeshDatasetListResponse(_Model):
+    datasets: list[TerrainMeshDataset]
+
+
+# --------------------------------------------------------------------------
+# /v1/terrain/elevation
+# --------------------------------------------------------------------------
+
+class ElevationResponse(_Model):
+    elevation_m: float
+    datum: str
+    source_bl: str
+    snapshot: str
+    license: str
+    attribution: str
+    tile_id: str
+
+
+# --------------------------------------------------------------------------
+# /v1/terrain/profile
+# --------------------------------------------------------------------------
+
+class TerrainProfileProperties(_Model):
+    datum: str
+    coords_count: int
+    samples: int
+    total_length_m: float
+    partial: bool
+    failed_tile_ids: list[str] = Field(default_factory=list)
+
+
+class TerrainProfileResponse(_Model):
+    type: str = "FeatureCollection"
+    properties: TerrainProfileProperties
+    features: list[dict[str, Any]]
+
+
+# --------------------------------------------------------------------------
+# /v1/tilesets  and  /v1/tilesets/{tileset_id}
+# --------------------------------------------------------------------------
+
+class Tileset(_Model):
+    tileset_id: str
+    region_code: str
+    bundesland_code: str
+    s3_key: str
+    generated_at: datetime
+    snapshot_date: Optional[date] = None
+    building_count: Optional[int] = None
+    tile_count: Optional[int] = None
+    total_bytes: Optional[int] = None
+    tileset_url: Optional[str] = None
+    bounding_volume: Optional[dict[str, Any]] = None
+
+
+class TilesetListResponse(_Model):
+    tilesets: list[Tileset]
+    count: int
+    bbox: list[float]

lodapi/resources/__init__.py

@@ -0,0 +1,29 @@
+"""Resource facades for the Lodapi SDK."""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+BBox = Union[Sequence[float], str]
+
+
+def serialize_bbox(bbox: BBox) -> str:
+    """Serialize a bbox to the API's ``minLon,minLat,maxLon,maxLat`` string.
+
+    Accepts either a 4-tuple/list of floats ``(minx, miny, maxx, maxy)`` or an
+    already-formatted string (passed through untouched).
+    """
+    if isinstance(bbox, str):
+        return bbox
+    values = list(bbox)
+    if len(values) != 4:
+        raise ValueError(
+            f"bbox must be (minLon, minLat, maxLon, maxLat) — got {len(values)} values."
+        )
+    return ",".join(_fmt(v) for v in values)
+
+
+def _fmt(value: float) -> str:
+    """Format a coordinate without trailing-zero noise (7.0 -> '7.0')."""
+    # repr keeps full float precision; good enough and round-trips cleanly.
+    return repr(float(value))

lodapi/resources/buildings.py

@@ -0,0 +1,160 @@
+"""``client.buildings`` — the buildings resource facade.
+
+The instance is *callable* (one page) and also exposes ``.iter()`` (transparent
+cursor pagination), ``.get()``, ``.roof()`` and ``.glb()``.
+
+    c.buildings(bbox=(7.0, 50.9, 7.1, 51.0), limit=500)   # one BuildingsBboxResponse
+    for feature in c.buildings.iter(bbox=(...)):           # all features, paged
+        ...
+    c.buildings.get("DEBBAL...")                           # BuildingDetail
+    c.buildings.roof("DEBBAL...")                          # BuildingRoofResponse
+    c.buildings.glb(bbox=(...), out="city.glb")            # stream GLB to disk
+
+NB: there is **no** ``bl`` parameter — federation across the 16 Bundesländer
+is server-side and automatic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator, Optional
+from urllib.parse import quote
+
+from .._http import HttpClient
+from ..models import BuildingDetail, BuildingRoofResponse, BuildingsBboxResponse
+from . import BBox, serialize_bbox
+
+# Neutral SDK defaults for the GLB endpoint, tuned for general glTF consumption
+# (Blender / three.js / model-viewer / Cesium) rather than any one app:
+#   - target_frame="utm": metric, scale-true coordinates (not MapLibre-specific).
+#   - origin="center":     model centred on the origin.
+#   - rotate_x=-90:        Z-up (geospatial) → Y-up. glTF is Y-up per spec, so
+#                          this makes the GLB stand upright out-of-the-box.
+#   - rotate_z=0:          no extra spin around the vertical axis.
+# These differ from the raw API defaults (utm / center / 0 / 0 — i.e. the API
+# does NOT rotate) — see README "GLB defaults".
+_GLB_SDK_DEFAULTS: dict[str, Any] = {
+    "target_frame": "utm",
+    "origin": "center",
+    "rotate_x": -90,
+    "rotate_z": 0,
+}
+
+
+class BuildingsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    # -- one page (callable) ----------------------------------------------
+
+    def __call__(
+        self,
+        *,
+        bbox: BBox,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> BuildingsBboxResponse:
+        """Fetch a single page of buildings for a WGS84 bbox.
+
+        Use ``response.next_cursor`` to fetch the next page manually, or
+        prefer :meth:`iter` for transparent pagination.
+        """
+        data = self._http.request_json(
+            "GET",
+            "/v1/buildings",
+            params={"bbox": serialize_bbox(bbox), "limit": limit, "cursor": cursor},
+        )
+        return BuildingsBboxResponse.model_validate(data)
+
+    # -- pagination iterators ---------------------------------------------
+
+    def pages(
+        self,
+        *,
+        bbox: BBox,
+        limit: Optional[int] = None,
+    ) -> Iterator[BuildingsBboxResponse]:
+        """Yield each page (``BuildingsBboxResponse``), following the cursor."""
+        cursor: Optional[str] = None
+        while True:
+            page = self(bbox=bbox, limit=limit, cursor=cursor)
+            yield page
+            cursor = page.next_cursor
+            if not cursor:
+                return
+
+    def iter(
+        self,
+        *,
+        bbox: BBox,
+        limit: Optional[int] = None,
+    ) -> Iterator[dict[str, Any]]:
+        """Yield individual GeoJSON building features across all pages."""
+        for page in self.pages(bbox=bbox, limit=limit):
+            yield from page.features
+
+    # -- single building ---------------------------------------------------
+
+    def get(self, gmlid: str) -> BuildingDetail:
+        """GET /v1/buildings/{gmlid} — single-building detail."""
+        data = self._http.request_json(
+            "GET", f"/v1/buildings/{quote(gmlid, safe='')}"
+        )
+        return BuildingDetail.model_validate(data)
+
+    def roof(self, gmlid: str) -> BuildingRoofResponse:
+        """GET /v1/buildings/{gmlid}/roof — RoofSurfaces FeatureCollection."""
+        data = self._http.request_json(
+            "GET", f"/v1/buildings/{quote(gmlid, safe='')}/roof"
+        )
+        return BuildingRoofResponse.model_validate(data)
+
+    # -- GLB export --------------------------------------------------------
+
+    def glb(
+        self,
+        *,
+        bbox: BBox,
+        out: Any | None = None,
+        z_base: Optional[str] = None,
+        compression: Optional[str] = None,
+        colorize_roofs: Optional[bool] = None,
+        merge_buildings: Optional[bool] = None,
+        target_frame: Optional[str] = None,
+        origin: Optional[str] = None,
+        rotate_x: Optional[float] = None,
+        rotate_z: Optional[float] = None,
+        include_ground: Optional[bool] = None,
+        weld_tolerance_m: Optional[float] = None,
+    ) -> bytes | int:
+        """GET /v1/buildings/3d.glb — binary glTF for a bbox.
+
+        - ``out=None`` → returns the GLB as ``bytes``.
+        - ``out`` is a path or file-like → streams to it, returns bytes written.
+
+        Frame/origin/rotation default to a neutral glTF-consumption set
+        (``utm`` / ``center`` / ``rotate_x=-90`` / ``rotate_z=0``) so the model
+        is metric, centred and upright (Y-up) in common 3D tools. Pass explicit
+        values to override — e.g. ``rotate_x=0`` for raw geospatial Z-up, or
+        ``target_frame="mercator", origin="corner", rotate_x=-90, rotate_z=-90``
+        to reproduce the scenerii-App view.
+        """
+        params: dict[str, Any] = {
+            "bbox": serialize_bbox(bbox),
+            "z_base": z_base,
+            "compression": compression,
+            "colorize_roofs": colorize_roofs,
+            "merge_buildings": merge_buildings,
+            "target_frame": target_frame,
+            "origin": origin,
+            "rotate_x": rotate_x,
+            "rotate_z": rotate_z,
+            "include_ground": include_ground,
+            "weld_tolerance_m": weld_tolerance_m,
+        }
+        # Apply SDK defaults only where the caller didn't specify.
+        for key, default in _GLB_SDK_DEFAULTS.items():
+            if params.get(key) is None:
+                params[key] = default
+        return self._http.request_bytes(
+            "GET", "/v1/buildings/3d.glb", params=params, out=out
+        )

lodapi/resources/terrain.py

@@ -0,0 +1,75 @@
+"""``client.terrain`` — terrain elevation / profile / dataset discovery.
+
+    c.terrain.elevation(lat=50.94, lon=7.05)
+    c.terrain.profile(coords=[(7.0, 50.9), (7.1, 51.0)], samples=100)
+    c.terrain.datasets()        # DGM tiff datasets
+    c.terrain.mesh_datasets()   # quantized-mesh tilesets
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+from .._http import HttpClient
+from ..models import (
+    ElevationResponse,
+    TerrainDatasetListResponse,
+    TerrainMeshDatasetListResponse,
+    TerrainProfileResponse,
+)
+
+
+def _serialize_coords(coords: Sequence[tuple[float, float]]) -> str:
+    """Serialize waypoints to the API's ``lon1,lat1;lon2,lat2[;...]`` form.
+
+    NB: the API expects **lon,lat** order (not lat,lon) and semicolon
+    separators between points — at least 2 points required.
+    """
+    pts = list(coords)
+    if len(pts) < 2:
+        raise ValueError("profile coords need at least 2 (lon, lat) waypoints.")
+    return ";".join(f"{repr(float(lon))},{repr(float(lat))}" for lon, lat in pts)
+
+
+class TerrainResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def elevation(
+        self, *, lat: float, lon: float, srs: Optional[str] = None
+    ) -> ElevationResponse:
+        """GET /v1/terrain/elevation — DGM elevation at a WGS84 point."""
+        data = self._http.request_json(
+            "GET",
+            "/v1/terrain/elevation",
+            params={"lat": lat, "lon": lon, "srs": srs},
+        )
+        return ElevationResponse.model_validate(data)
+
+    def profile(
+        self,
+        *,
+        coords: Sequence[tuple[float, float]],
+        samples: Optional[int] = None,
+    ) -> TerrainProfileResponse:
+        """GET /v1/terrain/profile — elevation profile along a polyline.
+
+        ``coords`` is a sequence of ``(lon, lat)`` waypoints (WGS84), at least
+        two. ``samples`` is the total number of sample points (2–512).
+        """
+        data = self._http.request_json(
+            "GET",
+            "/v1/terrain/profile",
+            params={"coords": _serialize_coords(coords), "samples": samples},
+        )
+        return TerrainProfileResponse.model_validate(data)
+
+    def datasets(self) -> TerrainDatasetListResponse:
+        """GET /v1/terrain/datasets — available DGM (raster) datasets per BL."""
+        data = self._http.request_json("GET", "/v1/terrain/datasets")
+        return TerrainDatasetListResponse.model_validate(data)
+
+    def mesh_datasets(self) -> TerrainMeshDatasetListResponse:
+        """GET /v1/terrain-mesh/datasets — available quantized-mesh tilesets."""
+        data = self._http.request_json("GET", "/v1/terrain-mesh/datasets")
+        return TerrainMeshDatasetListResponse.model_validate(data)

lodapi/resources/tilesets.py

@@ -0,0 +1,44 @@
+"""``client.tilesets`` — 3D-Tiles tileset discovery.
+
+    c.tilesets(bbox=(...))                 # TilesetListResponse
+    c.tilesets.get("be-2024")              # Tileset
+    c.tilesets.tileset_json("be-2024")     # raw 3D-Tiles tileset.json (dict)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._http import HttpClient
+from ..models import Tileset, TilesetListResponse
+from . import BBox, serialize_bbox
+
+
+class TilesetsResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def __call__(self, *, bbox: BBox) -> TilesetListResponse:
+        """GET /v1/tilesets?bbox=… — tilesets intersecting a WGS84 bbox."""
+        data = self._http.request_json(
+            "GET", "/v1/tilesets", params={"bbox": serialize_bbox(bbox)}
+        )
+        return TilesetListResponse.model_validate(data)
+
+    def get(self, tileset_id: str) -> Tileset:
+        """GET /v1/tilesets/{tileset_id} — single tileset metadata."""
+        data = self._http.request_json(
+            "GET", f"/v1/tilesets/{quote(tileset_id, safe='')}"
+        )
+        return Tileset.model_validate(data)
+
+    def tileset_json(self, tileset_id: str) -> dict[str, Any]:
+        """GET /v1/tilesets/{tileset_id}/tileset.json — the 3D-Tiles root.
+
+        Returned as a raw ``dict`` (the 3D-Tiles tileset schema is large and
+        owned by the OGC spec, not by Lodapi — no SDK model for it).
+        """
+        return self._http.request_json(
+            "GET", f"/v1/tilesets/{quote(tileset_id, safe='')}/tileset.json"
+        )

lodapi-0.0.1.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: lodapi
+Version: 0.0.1
+Summary: Ergonomic Python SDK for the Lodapi REST API (LoD2 buildings, terrain, 3D tiles).
+Project-URL: Homepage, https://lodapi.de
+Project-URL: Documentation, https://lodapi.de/docs
+Author-email: scenerii GmbH <konsti@scenerii.com>
+License: Apache-2.0
+Keywords: 3d-tiles,citygml,geospatial,gis,lod2,lodapi,terrain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.14; extra == 'geo'
+Requires-Dist: shapely>=2.0; extra == 'geo'
+Description-Content-Type: text/markdown
+
+# lodapi — Python SDK
+
+Ergonomic Python client for the [Lodapi](https://lodapi.de) REST API: federated
+LoD2 buildings across all 16 German Bundesländer, DGM terrain elevation, and 3D
+Tiles tileset discovery.
+
+> **v0 / unstable.** This is `0.0.1`. The public surface may change before
+> `0.1`. Pin an exact version if you depend on it.
+
+## Install
+
+```bash
+pip install lodapi
+pip install lodapi[geo]     # adds geopandas/shapely → .to_geodataframe()
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from lodapi import Client
+
+# api_key is optional — without one you use the anonymous free tier.
+c = Client(api_key="lod_...")
+
+# One page of buildings for a WGS84 bbox (minLon, minLat, maxLon, maxLat):
+page = c.buildings(bbox=(7.0, 50.9, 7.1, 51.0), limit=500)
+print(page.count, page.next_cursor)
+
+# Transparent cursor pagination — iterate every feature across all pages:
+for feature in c.buildings.iter(bbox=(7.0, 50.9, 7.1, 51.0)):
+    ...
+
+# Or page-by-page:
+for p in c.buildings.pages(bbox=(7.0, 50.9, 7.1, 51.0)):
+    ...
+
+# Single building + its roof surfaces:
+b = c.buildings.get("DEBBAL0100000001")
+roof = c.buildings.roof("DEBBAL0100000001")
+
+# Stream a binary GLB of the bbox to disk (or get bytes back with out=None):
+c.buildings.glb(bbox=(13.40, 52.51, 13.41, 52.52), out="city.glb")
+
+# Terrain:
+h = c.terrain.elevation(lat=50.94, lon=7.05)         # ElevationResponse
+prof = c.terrain.profile(coords=[(7.0, 50.9), (7.1, 51.0)], samples=100)
+c.terrain.datasets()                                  # DGM raster datasets
+c.terrain.mesh_datasets()                             # quantized-mesh tilesets
+
+# Datasets + 3D Tiles:
+c.datasets()                                          # LoD2 datasets per BL
+c.tilesets(bbox=(6.93, 50.92, 7.02, 50.96))           # tilesets in a bbox
+c.tilesets.get("nw-koeln")                            # one tileset
+c.tilesets.tileset_json("nw-koeln")                   # raw 3D-Tiles root (dict)
+
+c.close()   # or use `with Client(...) as c: ...`
+```
+
+There is **no `bl` parameter** — federation across the 16 Bundesländer is
+server-side and automatic. A bbox tuple `(minLon, minLat, maxLon, maxLat)` is
+serialized to the API's `"minLon,minLat,maxLon,maxLat"` string for you; you may
+also pass an already-formatted string.
+
+## Auth
+
+Pass `api_key="lod_..."` to the constructor; it is sent as the `X-API-Key`
+header. The free tier is **anonymous** — omit the key entirely and calls still
+work. A malformed/unknown/revoked key raises `AuthError` on the first call.
+
+Keys have the shape `lod_` + 32 lowercase chars (see ADR-0014).
+
+### Soft quota
+
+Per the Concierge-Billing MVP (ADR-0014), quota is **soft** — exceeding it is
+not an error. The server may return `X-Lodapi-Quota-Used` / `-Limit` headers;
+the SDK surfaces them after each call:
+
+```python
+c.buildings(bbox=(...))
+print(c.last_quota.used, c.last_quota.limit, c.last_quota.remaining)
+```
+
+Both fields are `None` for anonymous calls or keys without a configured quota.
+
+## GLB defaults
+
+`c.buildings.glb(...)` applies a neutral, glTF-consumption-friendly default set
+for frame/origin/rotation. These differ from the raw REST-API defaults: the API
+itself does **not** rotate, while the SDK rotates Z-up → Y-up so the model
+stands upright out-of-the-box in Blender / three.js / model-viewer / Cesium
+(glTF is Y-up per spec).
+
+| param          | raw API default | SDK default | why the SDK differs                       |
+|----------------|-----------------|-------------|-------------------------------------------|
+| `target_frame` | `utm`           | `utm`       | metric, scale-true (not MapLibre-bound)   |
+| `origin`       | `center`        | `center`    | model centred on the origin               |
+| `rotate_x`     | `0`             | `-90`       | Z-up → Y-up for glTF-spec conformance     |
+| `rotate_z`     | `0`             | `0`         | no extra spin around the vertical axis    |
+
+All other GLB params (`z_base`, `compression`, `colorize_roofs`,
+`merge_buildings`, `include_ground`, `weld_tolerance_m`) pass through to the
+API's own defaults when omitted. Every default is overridable per call:
+
+```python
+# Reproduce the scenerii-App view (MapLibre-aligned):
+c.buildings.glb(
+    bbox=(13.40, 52.51, 13.41, 52.52),
+    target_frame="mercator", origin="corner", rotate_x=-90, rotate_z=-90,
+)
+
+# Get raw geospatial Z-up (no rotation, matches the raw API):
+c.buildings.glb(bbox=(13.40, 52.51, 13.41, 52.52), rotate_x=0)
+```
+
+## Errors
+
+All API errors follow RFC 7807 `application/problem+json` (base
+`https://lodapi.de/errors`). The SDK parses the document onto a typed exception:
+
+```python
+from lodapi import LodapiError, AuthError, NotFoundError, RateLimitError, ApiError
+
+try:
+    c.buildings.get("NOPE")
+except NotFoundError as exc:
+    print(exc.status, exc.title, exc.detail, exc.instance)
+```
+
+- `AuthError` — 401
+- `NotFoundError` — 404
+- `RateLimitError` — 429 (reserved; quota is soft today)
+- `ApiError` — any other non-2xx
+- `LodapiError` — base class + transport/network errors
+
+Transient 5xx and network errors are retried (default 2 retries, exponential
+backoff). 4xx are never retried.
+
+## GeoDataFrame support (`geo` extra)
+
+With `pip install lodapi[geo]`, building/roof FeatureCollections convert to a
+`geopandas.GeoDataFrame` (CRS `EPSG:4326`):
+
+```python
+page = c.buildings(bbox=(7.0, 50.9, 7.1, 51.0))
+gdf = page.to_geodataframe()      # this page's features
+roof = c.buildings.roof("DEBBAL0100000001")
+roof.to_geodataframe()
+```
+
+Without the extra, `to_geodataframe()` raises `ImportError` with an install
+hint; the rest of the SDK works fine.
+
+## Configuration
+
+```python
+Client(
+    api_key=None,                      # optional lod_* key
+    base_url="https://api.lodapi.de",  # override for staging/local
+    timeout=30.0,                      # per-request seconds
+    max_retries=2,                     # transient 5xx/network only
+)
+```
+
+## Regenerating the response models
+
+The response models in `src/lodapi/models.py` are **hand-written**, derived from
+the OpenAPI snapshot at `04_engineering/api/openapi/openapi.json` (the live API
+serves it at `GET /openapi.json`). For ~11 endpoints this is leaner than full
+codegen.
+
+When the API surface grows or churns:
+
+1. Refresh the snapshot (`GET /openapi.json` → the repo copy).
+2. Either edit `models.py` by hand against the new `components.schemas`, **or**
+   adopt codegen:
+
+   ```bash
+   uvx openapi-python-client generate \
+       --path 04_engineering/api/openapi/openapi.json
+   ```
+
+   and re-point `resources/*` at the generated models. The resource facade is
+   intentionally decoupled from the model layer, so swapping the model source
+   is mechanical.
+
+## Development
+
+```bash
+uv run --extra dev pytest        # from code/sdk-python/
+```
+
+Tests mock all HTTP with `respx` — no live calls against prod.
+
+## License
+
+Apache-2.0. © scenerii GmbH.

lodapi-0.0.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+lodapi/__init__.py,sha256=DKST9AwuRqtPTMK3pOeYseH-o_W1bJkeWwEGgEAFf7U,1391
+lodapi/_geo.py,sha256=Y2Fy3j4XzKGNUbfGf5LdtrPcMctI9HYwZP5383IllCc,1093
+lodapi/_http.py,sha256=I4Jt6xRupxw7SYcSSWp2WXZKH3QDoLdTq9QBVDLFmc8,7795
+lodapi/client.py,sha256=LOvoX5UXkzA5MKEkN_sqnrEfZHAwbAE8LBBGm9bfmmk,3468
+lodapi/exceptions.py,sha256=gouWsJ3LXA0sFmh3OgaIyJqwXMaHwsFjnBGbT8rMGVg,3066
+lodapi/models.py,sha256=Qmn8TnEMdjERWKJDEzdWd1_0Vqha9hlPRYUJ8mtAvqM,7316
+lodapi/resources/__init__.py,sha256=CKAP6h9kBKrRUBRQHG_J2zYSwmGZozP-9sNxokYPr8w,898
+lodapi/resources/buildings.py,sha256=ZbXflP3HAgqBGdJhUPvaTQ-0c7tpv7MIiaih6h-RcjQ,6148
+lodapi/resources/terrain.py,sha256=Y7NTEogD-qnGVobDa2lYq_uVcutC9ks7Mt76wxCZUag,2763
+lodapi/resources/tilesets.py,sha256=tjLXdV4G4HmeNUkzI2lwj95-zMF2Vt8I2UzPhUSfCDw,1596
+lodapi-0.0.1.dist-info/METADATA,sha256=LlImyjSuZcMd76t6WFcDhxRwnz0BRLXDrRJ0ip_Li4s,7984
+lodapi-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+lodapi-0.0.1.dist-info/RECORD,,

lodapi-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any