osmfeatures 0.1.0__py3-none-any.whl

osmfeatures/__init__.py

@@ -0,0 +1,102 @@
+"""osmfeatures - Python SDK for the MapLark OSM Features API."""
+
+from __future__ import annotations
+
+from .async_client import AsyncOSMFeaturesClient
+from .chunking import around_to_bbox, bbox_area_deg2, merge_features, parse_bbox, shapely_to_bbox, split_bbox_tiles
+from .client import OSMFeaturesClient
+from .convenience import (
+    get_amenities,
+    get_barriers,
+    get_boundaries,
+    get_building_polygons,
+    get_buildings,
+    get_cafes,
+    get_cycleways,
+    get_elements_by_name,
+    get_green_spaces,
+    get_healthcare,
+    get_landuse,
+    get_parking,
+    get_parks,
+    get_place,
+    get_public_transport_stops,
+    get_restaurants,
+    get_roads,
+    get_schools,
+    get_shops,
+    get_trees,
+    get_water,
+)
+from .models import (
+    BinaryQueryResult,
+    CostEstimate,
+    OSMFeature,
+    OSMFeatureCollection,
+    OSMFeaturesAPIError,
+    OSMFeaturesAuthError,
+    OSMFeaturesError,
+    OSMFeaturesForbiddenError,
+    OSMFeaturesRateLimitError,
+    ResponseMeta,
+)
+from .output import to_dataframe, to_geodataframe
+from .retry import RetryConfig
+
+__all__ = [
+    # Clients
+    "OSMFeaturesClient",
+    "AsyncOSMFeaturesClient",
+    # Config
+    "RetryConfig",
+    # Models
+    "OSMFeature",
+    "OSMFeatureCollection",
+    "BinaryQueryResult",
+    "ResponseMeta",
+    "CostEstimate",
+    # Exceptions
+    "OSMFeaturesError",
+    "OSMFeaturesAuthError",
+    "OSMFeaturesForbiddenError",
+    "OSMFeaturesRateLimitError",
+    "OSMFeaturesAPIError",
+    # Output
+    "to_dataframe",
+    "to_geodataframe",
+    # Chunking utilities
+    "split_bbox_tiles",
+    "merge_features",
+    "parse_bbox",
+    "bbox_area_deg2",
+    "around_to_bbox",
+    "shapely_to_bbox",
+    # Convenience helpers - built environment
+    "get_buildings",
+    "get_building_polygons",
+    "get_barriers",
+    "get_trees",
+    # Convenience helpers - mobility
+    "get_roads",
+    "get_cycleways",
+    "get_public_transport_stops",
+    "get_parking",
+    # Convenience helpers - POI
+    "get_amenities",
+    "get_restaurants",
+    "get_cafes",
+    "get_shops",
+    "get_healthcare",
+    "get_schools",
+    # Convenience helpers - green space
+    "get_parks",
+    "get_green_spaces",
+    "get_water",
+    # Convenience helpers - admin / place
+    "get_landuse",
+    "get_boundaries",
+    "get_place",
+    "get_elements_by_name",
+]
+
+__version__ = "0.1.0"

osmfeatures/_http.py

@@ -0,0 +1,136 @@
+"""Shared HTTP helpers used by both the sync and async clients."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .models import (
+    OSMFeaturesAPIError,
+    OSMFeaturesAuthError,
+    OSMFeaturesForbiddenError,
+    OSMFeaturesRateLimitError,
+)
+
+DEFAULT_BASE_URL = "https://api.maplark.com"
+GEOJSON_ACCEPT = "application/geo+json"
+
+ElementType = Literal["node", "way", "relation"]
+ShapeType = Literal["line", "polygon", "all"]
+
+
+def is_geojson_accept(accept: str | None) -> bool:
+    """True when Accept is omitted or asks for GeoJSON (default encoding)."""
+    if not accept or not accept.strip():
+        return True
+    media = accept.split(",", 1)[0].split(";", 1)[0].strip().lower()
+    return media in ("*/*", "*", GEOJSON_ACCEPT)
+
+
+def build_params(kwargs: dict[str, Any]) -> list[tuple[str, Any]]:
+    """Convert SDK kwargs to a list of (key, value) pairs for requests.
+
+    Handles repeatable parameters (tags, or_tags, not_tags) - if a
+    list/tuple is provided it becomes multiple query-string values.
+    The ``type`` parameter is encoded as a single comma-separated value
+    because the backend expects ``type=node,way`` instead of repeated keys.
+    """
+    repeatable = {"tags", "or_tags", "not_tags"}
+    params: list[tuple[str, Any]] = []
+    for key, value in kwargs.items():
+        if key == "type" and isinstance(value, (list, tuple)):
+            params.append((key, ",".join(str(v) for v in value)))
+        elif key in repeatable and isinstance(value, (list, tuple)):
+            for v in value:
+                params.append((key, v))
+        elif isinstance(value, bool):
+            params.append((key, "true" if value else "false"))
+        else:
+            params.append((key, value))
+    return params
+
+
+def raise_for_response(resp: Any) -> None:
+    status = resp.status_code
+    if status == 401:
+        raise OSMFeaturesAuthError(f"Authentication failed (HTTP 401): {resp.text[:200]}")
+    if status == 403:
+        raise OSMFeaturesForbiddenError(f"Access denied (HTTP 403): {resp.text[:200]}")
+    if status == 429:
+        body: dict[str, Any] = {}
+        try:
+            body = resp.json()
+        except Exception:
+            pass
+        retry_after_raw = resp.headers.get("Retry-After") or resp.headers.get("retry-after")
+        retry_after: float | None = None
+        if retry_after_raw is not None:
+            try:
+                retry_after = float(retry_after_raw)
+            except (TypeError, ValueError):
+                pass
+        raise OSMFeaturesRateLimitError(
+            body.get("detail", body.get("message", f"Rate limit exceeded (HTTP 429): {resp.text[:200]}")),
+            error_code=body.get("error", ""),
+            tier=body.get("tier", ""),
+            estimated_units=body.get("estimated_units"),
+            max_units_per_request=body.get("max_units_per_request"),
+            retry_after=retry_after,
+        )
+    if not (200 <= status < 300):
+        raise OSMFeaturesAPIError(
+            f"API error (HTTP {status}): {resp.text[:200]}",
+            status_code=status,
+        )
+
+
+def is_429_retryable(resp: Any) -> bool:
+    """Return True if the 429 should be retried (transient per-second limit).
+
+    The backend emits ``error == "too_many_requests"`` for all 429s and
+    distinguishes the two cases via a ``subtype`` field:
+    - ``"rate_limit_second"`` — transient, safe to retry with back-off.
+    - ``"rate_limit_monthly"`` — hard monthly cap, do not retry.
+
+    If ``subtype`` is absent (e.g. unknown proxy / future backend version),
+    fall back to retrying so the SDK does not silently swallow genuine
+    transient limits.
+    """
+    try:
+        body = resp.json()
+        subtype = body.get("subtype", "")
+        if subtype == "rate_limit_monthly":
+            return False
+        if subtype == "rate_limit_second":
+            return True
+        # Legacy codes emitted by older backend versions — kept for
+        # compatibility during a rolling deploy.
+        error = body.get("error", "")
+        if error == "rate_limit_monthly":
+            return False
+        # Default: retry unknown 429s (fail open for transient limits).
+        return True
+    except Exception:
+        return True
+
+
+def build_rate_limit_error(resp: Any) -> OSMFeaturesRateLimitError:
+    body: dict[str, Any] = {}
+    try:
+        body = resp.json()
+    except Exception:
+        pass
+    retry_after_raw = resp.headers.get("Retry-After") or resp.headers.get("retry-after")
+    retry_after: float | None = None
+    if retry_after_raw is not None:
+        try:
+            retry_after = float(retry_after_raw)
+        except (TypeError, ValueError):
+            pass
+    return OSMFeaturesRateLimitError(
+        body.get("detail", body.get("message", "Rate limit exceeded")),
+        error_code=body.get("error", ""),
+        tier=body.get("tier", ""),
+        estimated_units=body.get("estimated_units"),
+        max_units_per_request=body.get("max_units_per_request"),
+        retry_after=retry_after,
+    )

osmfeatures/_pagination.py

@@ -0,0 +1,112 @@
+"""Auto-pagination helpers for /v2/osm_features."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Callable
+
+from osmfeatures.models import OSMFeatureCollection
+
+
+_MAX_PAGES = 500  # hard safety cap - prevents infinite loops
+
+
+def paginate_all(
+    fetch_fn: Callable[[dict[str, Any]], OSMFeatureCollection],
+    params: dict[str, Any],
+    *,
+    limit_per_page: int = 1000,
+) -> Iterator[list[dict[str, Any]]]:
+    """Yield pages of raw feature dicts until ``X-Has-More`` is false.
+
+    Parameters
+    ----------
+    fetch_fn:
+        Synchronous callable that accepts a params dict and returns an
+        :class:`OSMFeatureCollection` (pagination via ``.meta`` from headers).
+    params:
+        Base query parameters. Any ``limit`` and ``cursor`` keys are managed
+        internally and will be overwritten.
+    limit_per_page:
+        Upstream ``limit`` per HTTP request (page size).
+
+    Yields
+    ------
+    list[dict]
+        The ``features`` list from each page response.
+    """
+    base = {k: v for k, v in params.items() if k not in ("limit", "cursor")}
+    base["limit"] = limit_per_page
+    cursor: str | None = None
+
+    for page in range(_MAX_PAGES):
+        page_params = dict(base)
+        if cursor is not None:
+            page_params["cursor"] = cursor
+        collection = fetch_fn(page_params)
+        features: list[dict[str, Any]] = list(collection.get("features", []))
+        yield features
+
+        if not collection.meta.has_more:
+            return
+
+        if not features:
+            raise RuntimeError(
+                f"API returned has_more=true but an empty features page at cursor {cursor!r} "
+                f"on page {page}."
+            )
+
+        next_cursor = collection.meta.next_cursor
+        if not isinstance(next_cursor, str) or not next_cursor or next_cursor == cursor:
+            raise RuntimeError(
+                f"API returned has_more=true but next_cursor ({next_cursor!r}) "
+                f"did not advance beyond current cursor ({cursor!r}) on page {page}."
+            )
+        cursor = next_cursor
+
+    raise RuntimeError(
+        f"paginate_all exceeded {_MAX_PAGES} pages without has_more=false - "
+        "possible infinite pagination loop."
+    )
+
+
+async def paginate_all_async(
+    fetch_fn: Callable[[dict[str, Any]], Any],
+    params: dict[str, Any],
+    *,
+    limit_per_page: int = 1000,
+) -> AsyncIterator[list[dict[str, Any]]]:
+    """Async counterpart to :func:`paginate_all` (yields pages)."""
+    base = {k: v for k, v in params.items() if k not in ("limit", "cursor")}
+    base["limit"] = limit_per_page
+    cursor: str | None = None
+
+    for page in range(_MAX_PAGES):
+        page_params = dict(base)
+        if cursor is not None:
+            page_params["cursor"] = cursor
+        collection = await fetch_fn(page_params)
+        features: list[dict[str, Any]] = list(collection.get("features", []))
+        yield features
+
+        if not collection.meta.has_more:
+            return
+
+        if not features:
+            raise RuntimeError(
+                f"API returned has_more=true but an empty features page at cursor {cursor!r} "
+                f"on page {page}."
+            )
+
+        next_cursor = collection.meta.next_cursor
+        if not isinstance(next_cursor, str) or not next_cursor or next_cursor == cursor:
+            raise RuntimeError(
+                f"API returned has_more=true but next_cursor ({next_cursor!r}) "
+                f"did not advance beyond current cursor ({cursor!r}) on page {page}."
+            )
+        cursor = next_cursor
+
+    raise RuntimeError(
+        f"paginate_all_async exceeded {_MAX_PAGES} pages without has_more=false - "
+        "possible infinite pagination loop."
+    )

osmfeatures/async_client.py

@@ -0,0 +1,297 @@
+"""Asynchronous MapLark OSM Features API client (httpx-based)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .chunking import merge_features, shapely_to_bbox, split_bbox_tiles
+from ._http import (
+    DEFAULT_BASE_URL,
+    GEOJSON_ACCEPT,
+    ElementType,
+    ShapeType,
+    build_params,
+    build_rate_limit_error,
+    is_429_retryable,
+    is_geojson_accept,
+    raise_for_response,
+)
+from .models import (
+    BinaryQueryResult,
+    CostEstimate,
+    OSMFeature,
+    OSMFeatureCollection,
+    ResponseMeta,
+)
+from ._pagination import paginate_all_async
+from .retry import RetryConfig, retry_async
+
+
+class AsyncOSMFeaturesClient:
+    """Asynchronous client for the MapLark OSM Features API.
+
+    Use as an async context manager::
+
+        async with AsyncOSMFeaturesClient(api_key="...") as client:
+            fc = await client.query_async(bbox="18.06,59.32,18.09,59.34", tags=["building"])
+
+    Parameters
+    ----------
+    api_key:
+        Your MapLark API key.
+    base_url:
+        API base URL.  Defaults to ``https://api.maplark.com``.
+    retry_config:
+        Retry / backoff settings.  Defaults to 3 retries with exponential
+        backoff and jitter.
+    timeout:
+        HTTP request timeout in seconds.  Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        retry_config: RetryConfig | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._retry = retry_config or RetryConfig()
+        self._headers = {"Authorization": f"Bearer {api_key}"}
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+        return self._client
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _request(
+        self, params: dict[str, Any], *, accept: str | None = None
+    ) -> httpx.Response:
+        param_list = build_params(params)
+        client = await self._get_client()
+
+        async def _do() -> httpx.Response:
+            return await client.get(
+                f"{self._base_url}/v2/osm_features",
+                params=param_list,
+                headers={"Accept": accept or GEOJSON_ACCEPT},
+            )
+
+        resp = await retry_async(
+            _do,
+            self._retry,
+            get_status=lambda r: r.status_code,
+            get_headers=lambda r: dict(r.headers),
+            is_rate_limit_error=is_429_retryable,
+            build_rate_limit_error=build_rate_limit_error,
+        )
+        raise_for_response(resp)
+        return resp
+
+    async def _raw_query(
+        self, params: dict[str, Any], *, accept: str | None = None
+    ) -> OSMFeatureCollection:
+        resp = await self._request(params, accept=accept)
+        return OSMFeatureCollection.from_http(resp.json(), resp.headers)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def query_async(
+        self,
+        *,
+        bbox: str | None = None,
+        around: str | None = None,
+        type: ElementType | list[ElementType] | None = None,  # noqa: A002
+        shape: ShapeType | None = None,
+        osm_ids: str | None = None,
+        tags: list[str] | str | None = None,
+        or_tags: list[str] | str | None = None,
+        not_tags: list[str] | str | None = None,
+        limit: int = 1000,
+        cursor: str | None = None,
+        zoom: float | None = None,
+        min_length_m: float | None = None,
+        max_length_m: float | None = None,
+        min_area_m2: float | None = None,
+        max_area_m2: float | None = None,
+        disable_budget_warning: bool = False,
+        geometry: Any = None,
+        centroid: bool = False,
+        accept: str | None = None,
+    ) -> OSMFeatureCollection | BinaryQueryResult:
+        """Fetch a single page of OSM elements asynchronously.
+
+        Same parameters as :meth:`OSMFeaturesClient.query`. Non-GeoJSON
+        ``accept`` values return :class:`BinaryQueryResult`.
+        """
+        if geometry is not None:
+            bbox = shapely_to_bbox(geometry)
+
+        params: dict[str, Any] = {}
+        if bbox is not None:
+            params["bbox"] = bbox
+        if around is not None:
+            params["around"] = around
+        if type is not None:
+            params["type"] = type
+        if shape is not None:
+            params["shape"] = shape
+        if osm_ids is not None:
+            params["osm_ids"] = osm_ids
+        if tags is not None:
+            params["tags"] = tags
+        if or_tags is not None:
+            params["or_tags"] = or_tags
+        if not_tags is not None:
+            params["not_tags"] = not_tags
+        params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        if zoom is not None:
+            params["zoom"] = zoom
+        if min_length_m is not None:
+            params["min_length_m"] = min_length_m
+        if max_length_m is not None:
+            params["max_length_m"] = max_length_m
+        if min_area_m2 is not None:
+            params["min_area_m2"] = min_area_m2
+        if max_area_m2 is not None:
+            params["max_area_m2"] = max_area_m2
+        if disable_budget_warning:
+            params["disable_budget_warning"] = disable_budget_warning
+        if centroid:
+            params["centroid"] = True
+
+        if is_geojson_accept(accept):
+            return await self._raw_query(params, accept=accept)
+        resp = await self._request(params, accept=accept)
+        return BinaryQueryResult.from_http(resp.content, resp.headers)
+
+    async def query_all_async(
+        self,
+        *,
+        limit_per_page: int = 1000,
+        bbox_tiles: int = 2,
+        max_features: int | None = 55_000,
+        **params: Any,
+    ) -> OSMFeatureCollection:
+        """Fetch *all* pages of OSM elements asynchronously, auto-paginating.
+
+        When ``bbox`` is present, splits it into *bbox_tiles* sub-bboxes
+        (power of 2; default 2), paginates each tile sequentially, then
+        merges and deduplicates by feature ``id``. Use ``bbox_tiles=1`` to
+        disable tiling.
+
+        ``max_features`` defaults to 55_000; pass ``None`` for no upper limit.
+        Do not pass ``limit`` or ``cursor`` (use ``limit_per_page`` / managed
+        pagination). Non-GeoJSON ``accept`` is not supported.
+        """
+        if "limit" in params:
+            raise ValueError(
+                "query_all_async does not take limit; use limit_per_page (page size) "
+                "and max_features (total cap)"
+            )
+        if not is_geojson_accept(params.pop("accept", None)):
+            raise TypeError(
+                "query_all_async() only supports GeoJSON; use query_async(accept=...) "
+                "for binary/table encodings"
+            )
+        if "cursor" in params:
+            raise ValueError("query_all_async manages cursors; do not pass cursor")
+
+        if "geometry" in params:
+            geom = params.pop("geometry")
+            params["bbox"] = shapely_to_bbox(geom)
+
+        bbox = params.get("bbox")
+        tile_bboxes = (
+            split_bbox_tiles(bbox, bbox_tiles) if isinstance(bbox, str) else [None]
+        )
+
+        feature_lists: list[list[dict[str, Any]]] = []
+        count = 0
+        truncated = False
+        for tile_bbox in tile_bboxes:
+            if max_features is not None and count >= max_features:
+                truncated = True
+                break
+            tile_params = dict(params)
+            if tile_bbox is not None:
+                tile_params["bbox"] = tile_bbox
+            tile_features: list[dict[str, Any]] = []
+            async for page_features in paginate_all_async(
+                self._raw_query, tile_params, limit_per_page=limit_per_page
+            ):
+                if max_features is not None:
+                    room = max_features - count
+                    if room <= 0:
+                        truncated = True
+                        break
+                    if len(page_features) > room:
+                        tile_features.extend(page_features[:room])
+                        count += room
+                        truncated = True
+                        break
+                tile_features.extend(page_features)
+                count += len(page_features)
+            feature_lists.append(tile_features)
+
+        deduped = merge_features(feature_lists)
+        if max_features is not None and len(deduped) > max_features:
+            deduped = deduped[:max_features]
+            truncated = True
+        return OSMFeatureCollection(
+            features=[OSMFeature.from_dict(f) for f in deduped],
+            meta=ResponseMeta(returned=len(deduped), has_more=truncated),
+        )
+
+    async def estimate_cost_async(self, **params: Any) -> CostEstimate:
+        """Call ``/v2/osm_features/cost`` to preflight the credit cost."""
+        if "geometry" in params:
+            geom = params.pop("geometry")
+            params["bbox"] = shapely_to_bbox(geom)
+
+        param_list = build_params(params)
+        client = await self._get_client()
+
+        async def _do() -> httpx.Response:
+            return await client.get(
+                f"{self._base_url}/v2/osm_features/cost",
+                params=param_list,
+            )
+
+        resp = await retry_async(
+            _do,
+            self._retry,
+            get_status=lambda r: r.status_code,
+            get_headers=lambda r: dict(r.headers),
+            is_rate_limit_error=is_429_retryable,
+            build_rate_limit_error=build_rate_limit_error,
+        )
+        raise_for_response(resp)
+        return CostEstimate.from_dict(resp.json())
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "AsyncOSMFeaturesClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()