gmaps-boundary 0.1.0__py3-none-any.whl

gmaps_boundary/__init__.py

@@ -0,0 +1,45 @@
+"""Fetch the boundary polygon Google Maps draws for a place.
+
+Public names:
+    fetch_boundary, find_place: one-off helpers.
+    BoundaryClient, AsyncBoundaryClient: reusable clients.
+    Boundary, Place: the returned types.
+    MAX_ZOOM: the finest tile zoom that carries boundaries.
+    preview.save_preview: draw a boundary to a PNG (needs the preview extra).
+    GmapsBoundaryError and its subclasses: PlaceNotFoundError, NoBoundaryError,
+        TooManyTilesError, ResponseFormatError, RequestFailedError.
+"""
+
+from importlib.metadata import version
+
+from ._boundary import Boundary
+from ._places import Place
+from ._tiles import MAX_ZOOM
+from .client import AsyncBoundaryClient, BoundaryClient, fetch_boundary, find_place
+from .errors import (
+    GmapsBoundaryError,
+    NoBoundaryError,
+    PlaceNotFoundError,
+    RequestFailedError,
+    ResponseFormatError,
+    TooManyTilesError,
+)
+
+__version__ = version("gmaps-boundary")
+
+__all__ = [
+    "MAX_ZOOM",
+    "AsyncBoundaryClient",
+    "Boundary",
+    "BoundaryClient",
+    "GmapsBoundaryError",
+    "NoBoundaryError",
+    "Place",
+    "PlaceNotFoundError",
+    "RequestFailedError",
+    "ResponseFormatError",
+    "TooManyTilesError",
+    "__version__",
+    "fetch_boundary",
+    "find_place",
+]

gmaps_boundary/_boundary.py

@@ -0,0 +1,61 @@
+"""The public ``Boundary`` type."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from shapely import MultiPolygon, Polygon
+from shapely.geometry import mapping
+
+from ._places import Place
+from ._tiles import TILE_EXTENT
+
+_EQUATOR_LENGTH_M = 40_075_016.686
+
+PolygonalGeometry = Polygon | MultiPolygon
+
+
+@dataclass(frozen=True)
+class Boundary:
+    """The boundary Google Maps draws for a place.
+
+    ``geometry`` is a shapely geometry in WGS 84, with x as longitude and y as latitude.
+    ``zoom`` is the tile zoom the boundary was read at. A higher zoom has more vertices.
+    """
+
+    place: Place
+    zoom: int
+    geometry: PolygonalGeometry
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        """``(west, south, east, north)`` in degrees."""
+        west, south, east, north = self.geometry.bounds
+        return west, south, east, north
+
+    @property
+    def resolution_m(self) -> float:
+        """The size of one coordinate step at this zoom and latitude, in metres."""
+        metres_per_tile = _EQUATOR_LENGTH_M * math.cos(math.radians(self.place.latitude))
+        return metres_per_tile / ((1 << self.zoom) * TILE_EXTENT)
+
+    @property
+    def __geo_interface__(self) -> dict[str, Any]:
+        return self.to_geojson()
+
+    def to_geojson(self) -> dict[str, Any]:
+        """Return a GeoJSON Feature. Its properties describe the place."""
+        return {
+            "type": "Feature",
+            "properties": {
+                "name": self.place.name,
+                "address": self.place.address,
+                "feature_id": self.place.feature_id,
+                "label_latitude": self.place.latitude,
+                "label_longitude": self.place.longitude,
+                "zoom": self.zoom,
+            },
+            "geometry": mapping(self.geometry),
+        }

gmaps_boundary/_places.py

@@ -0,0 +1,130 @@
+"""Places: the public ``Place`` type, place URL parsing and search response parsing."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from urllib.parse import urlencode
+
+from .errors import PlaceNotFoundError, ResponseFormatError
+
+_SEARCH_URL = "https://www.google.com/search"
+_FEATURE_ID_PATTERN = re.compile(r"0x([0-9a-f]{1,16}):0x([0-9a-f]{1,16})")
+_URL_FEATURE_ID_PATTERN = re.compile(r"!1s(0x[0-9a-f]{1,16}:0x[0-9a-f]{1,16})")
+_URL_LABEL_POINT_PATTERN = re.compile(r"!3d(-?[0-9.]+)!4d(-?[0-9.]+)")
+_URL_NAME_PATTERN = re.compile(r"/maps/place/([^/@]+)")
+_JSON_GUARD = ")]}'"
+
+# Positions inside one search hit. Google sends positional JSON arrays.
+_HIT_RECORD_INDEX = 14
+_RECORD_POINT_INDEX = 9
+_RECORD_FEATURE_ID_INDEX = 10
+_RECORD_NAME_INDEX = 11
+_RECORD_ADDRESS_INDEX = 18
+_POINT_LATITUDE_INDEX = 2
+_POINT_LONGITUDE_INDEX = 3
+
+
+@dataclass(frozen=True)
+class Place:
+    """A Google Maps place.
+
+    ``feature_id`` is the ``0x..:0x..`` pair found in Google Maps place URLs.
+    The label point is where Google Maps puts the place name on the map.
+    """
+
+    feature_id: str
+    latitude: float
+    longitude: float
+    name: str | None = None
+    address: str | None = None
+
+    def __post_init__(self) -> None:
+        if _FEATURE_ID_PATTERN.fullmatch(self.feature_id) is None:
+            raise ValueError(f"feature_id: expected '0x<hex>:0x<hex>', got {self.feature_id!r}")
+        if not -90.0 <= self.latitude <= 90.0:
+            raise ValueError(f"latitude: expected -90 to 90, got {self.latitude}")
+        if not -180.0 <= self.longitude <= 180.0:
+            raise ValueError(f"longitude: expected -180 to 180, got {self.longitude}")
+
+    @classmethod
+    def from_url(cls, url: str) -> Place:
+        """Read a place from a full Google Maps place URL.
+
+        The URL must carry ``!1s0x..:0x..`` and ``!3d<lat>!4d<lng>``. That is the URL
+        the browser shows after a place opens. Short ``maps.app.goo.gl`` links do not.
+        """
+        feature_id = _URL_FEATURE_ID_PATTERN.search(url)
+        if feature_id is None:
+            raise ValueError("url: no '!1s0x..:0x..' feature id found; pass the full place URL")
+        label_point = _URL_LABEL_POINT_PATTERN.search(url)
+        if label_point is None:
+            raise ValueError(
+                "url: no '!3d<lat>!4d<lng>' label point found; pass the full place URL"
+            )
+        name = _URL_NAME_PATTERN.search(url)
+        return cls(
+            feature_id=feature_id.group(1),
+            latitude=float(label_point.group(1)),
+            longitude=float(label_point.group(2)),
+            name=name.group(1).replace("+", " ") if name else None,
+        )
+
+    @property
+    def cell_id(self) -> int:
+        """The first half of the feature id, as the decimal the tile request needs."""
+        return int(self.feature_id.split(":")[0], 16)
+
+    @property
+    def feature_number(self) -> int:
+        """The second half of the feature id, as the decimal the tile request needs."""
+        return int(self.feature_id.split(":")[1], 16)
+
+
+def search_url(query: str, language: str, region: str) -> str:
+    return f"{_SEARCH_URL}?{urlencode({'tbm': 'map', 'hl': language, 'gl': region, 'q': query})}"
+
+
+def _element(sequence: object, index: int) -> object:
+    """Return ``sequence[index]``, or None when the array is too short or not an array."""
+    if isinstance(sequence, list) and len(sequence) > index:
+        return sequence[index]
+    return None
+
+
+def _optional_text(record: object, index: int) -> str | None:
+    text = _element(record, index)
+    return text if isinstance(text, str) else None
+
+
+def parse_search_response(body: bytes, query: str) -> Place:
+    """Return the first place of a Google Maps search response."""
+    text = body.decode("utf-8", errors="replace")
+    if not text.startswith(_JSON_GUARD):
+        raise ResponseFormatError("search: response does not start with the JSON guard prefix")
+    try:
+        payload = json.loads(text[len(_JSON_GUARD) :])
+    except json.JSONDecodeError as error:
+        raise ResponseFormatError(f"search: response is not JSON: {error}") from error
+    hits = _element(_element(payload, 0), 1)
+    if not isinstance(hits, list):
+        raise ResponseFormatError("search: response has no hit list")
+    for hit in hits:
+        record = _element(hit, _HIT_RECORD_INDEX)
+        feature_id = _element(record, _RECORD_FEATURE_ID_INDEX)
+        if not isinstance(feature_id, str):
+            continue
+        point = _element(record, _RECORD_POINT_INDEX)
+        latitude = _element(point, _POINT_LATITUDE_INDEX)
+        longitude = _element(point, _POINT_LONGITUDE_INDEX)
+        if not isinstance(latitude, float) or not isinstance(longitude, float):
+            raise ResponseFormatError(f"search: place {feature_id} has no label point")
+        return Place(
+            feature_id=feature_id,
+            latitude=latitude,
+            longitude=longitude,
+            name=_optional_text(record, _RECORD_NAME_INDEX),
+            address=_optional_text(record, _RECORD_ADDRESS_INDEX),
+        )
+    raise PlaceNotFoundError(f"no single place matches {query!r}; try a more specific name")

gmaps_boundary/_protobuf.py

@@ -0,0 +1,76 @@
+"""Schema-free protobuf wire decoding, enough to read Google vector tiles."""
+
+from __future__ import annotations
+
+from .errors import ResponseFormatError
+
+FieldValue = int | bytes
+
+_VARINT = 0
+_FIXED64 = 1
+_LENGTH_DELIMITED = 2
+_FIXED32 = 5
+_MAX_VARINT_BYTES = 10
+
+
+def read_varint(buffer: bytes, position: int) -> tuple[int, int]:
+    """Return the varint at ``position`` and the position after it."""
+    value = 0
+    for byte_index in range(_MAX_VARINT_BYTES):
+        if position >= len(buffer):
+            raise ResponseFormatError("protobuf: varint runs past the end of its message")
+        byte = buffer[position]
+        position += 1
+        value |= (byte & 0x7F) << (7 * byte_index)
+        if not byte & 0x80:
+            return value, position
+    raise ResponseFormatError("protobuf: varint is longer than 10 bytes")
+
+
+def read_fields(message: bytes) -> list[tuple[int, FieldValue]]:
+    """Decode one message into ``(field number, value)`` pairs, in wire order."""
+    fields: list[tuple[int, FieldValue]] = []
+    position = 0
+    while position < len(message):
+        key, position = read_varint(message, position)
+        number, wire_type = key >> 3, key & 7
+        if wire_type == _VARINT:
+            value, position = read_varint(message, position)
+            fields.append((number, value))
+            continue
+        if wire_type == _LENGTH_DELIMITED:
+            size, position = read_varint(message, position)
+        elif wire_type == _FIXED64:
+            size = 8
+        elif wire_type == _FIXED32:
+            size = 4
+        else:
+            raise ResponseFormatError(f"protobuf: field {number} has unknown wire type {wire_type}")
+        if position + size > len(message):
+            raise ResponseFormatError(f"protobuf: field {number} runs past the end of its message")
+        fields.append((number, message[position : position + size]))
+        position += size
+    return fields
+
+
+def read_packed_varints(packed: bytes) -> list[int]:
+    numbers: list[int] = []
+    position = 0
+    while position < len(packed):
+        number, position = read_varint(packed, position)
+        numbers.append(number)
+    return numbers
+
+
+def unzigzag(number: int) -> int:
+    return (number >> 1) ^ -(number & 1)
+
+
+def first_bytes_field(fields: list[tuple[int, FieldValue]], number: int) -> bytes | None:
+    """Return the first length-delimited value of field ``number``, or None when absent."""
+    for field_number, value in fields:
+        if field_number == number:
+            if not isinstance(value, bytes):
+                raise ResponseFormatError(f"protobuf: field {number} is not length-delimited")
+            return value
+    return None

gmaps_boundary/_steps.py

@@ -0,0 +1,252 @@
+"""The request plan for one boundary, written without I/O.
+
+Each function here is a generator. It yields a batch of URLs, receives the
+response bodies in the same order, and returns its value when done. The sync and
+async clients run the same generators, so the logic exists once.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Generator, Iterable
+from dataclasses import dataclass
+from typing import TypeVar
+
+import shapely
+from shapely import MultiPolygon, Polygon, set_precision, unary_union
+from shapely.geometry.base import BaseGeometry
+from shapely.prepared import prep
+
+from ._boundary import Boundary, PolygonalGeometry
+from ._places import Place, parse_search_response, search_url
+from ._tiles import (
+    MAX_ZOOM,
+    TILE_EXTENT,
+    Tile,
+    decode_place_part,
+    global_units_to_lng_lat,
+    tile_containing,
+    tile_url,
+)
+from .errors import NoBoundaryError, TooManyTilesError
+
+ReturnValue = TypeVar("ReturnValue")
+Steps = Generator[list[str], list[bytes], ReturnValue]
+PlaceQuery = str | Place
+
+# The outline is first read at a coarse zoom, to size the job and to seed the fine pass.
+_COARSE_ZOOMS = (12, 8, 4, 0)
+_PROBE_ZOOM = 10
+# The tile estimate is rough, so automatic zoom aims below the cap.
+_AUTO_ZOOM_FILL_RATIO = 0.75
+
+
+@dataclass(frozen=True)
+class FetchOptions:
+    zoom: int | None
+    max_tiles: int
+    language: str
+    region: str
+    batch_size: int
+
+    def __post_init__(self) -> None:
+        if self.zoom is not None and not 0 <= self.zoom <= MAX_ZOOM:
+            raise ValueError(f"zoom: expected 0 to {MAX_ZOOM} or None, got {self.zoom}")
+        if self.max_tiles < 16:
+            raise ValueError(f"max_tiles: expected at least 16, got {self.max_tiles}")
+        if self.batch_size < 1:
+            raise ValueError(f"batch_size: expected at least 1, got {self.batch_size}")
+
+
+class _WalkTooLargeError(Exception):
+    """A tile walk passed the tile cap."""
+
+
+def place_steps(query: PlaceQuery, language: str, region: str) -> Steps[Place]:
+    """Resolve a place from a ``Place``, a Google Maps place URL or a search text."""
+    if isinstance(query, Place):
+        return query
+    if query.startswith(("http://", "https://")):
+        return Place.from_url(query)
+    if not query.strip():
+        raise ValueError(
+            "query: expected a place name or a Google Maps place URL, got an empty text"
+        )
+    (body,) = yield [search_url(query, language, region)]
+    return parse_search_response(body, query)
+
+
+def _polygons_only(geometry: BaseGeometry) -> PolygonalGeometry:
+    """Drop the stray points and lines a union can leave, and keep the polygons."""
+    if isinstance(geometry, (Polygon, MultiPolygon)):
+        return geometry
+    polygons = [part for part in getattr(geometry, "geoms", []) if isinstance(part, Polygon)]
+    return MultiPolygon(polygons)
+
+
+def _walk_steps(
+    place: Place, seeds: Iterable[Tile], tile_cap: int, options: FetchOptions
+) -> Steps[PolygonalGeometry]:
+    """Fetch tiles outward from ``seeds`` and merge the place parts, in zoom-level units."""
+    pending = deque(dict.fromkeys(seeds))
+    seen = set(pending)
+    parts: list[BaseGeometry] = []
+    while pending:
+        if len(seen) > tile_cap:
+            raise _WalkTooLargeError
+        batch = [pending.popleft() for _ in range(min(len(pending), options.batch_size))]
+        bodies = yield [
+            tile_url(tile, place.cell_id, place.feature_number, options.language, options.region)
+            for tile in batch
+        ]
+        for tile, body in zip(batch, bodies, strict=True):
+            part = decode_place_part(body, tile).geometry
+            if part.is_empty:
+                continue
+            parts.append(set_precision(part, 1.0))
+            for neighbour in tile.neighbours():
+                if neighbour not in seen:
+                    seen.add(neighbour)
+                    pending.append(neighbour)
+    # Zero tolerance drops only the collinear vertices the tile seams leave behind.
+    return _polygons_only(unary_union(parts).simplify(0))
+
+
+def _label_seeds(place: Place, zoom: int) -> list[Tile]:
+    """The tile under the label point and its ring. The label can sit just off the polygon."""
+    centre = tile_containing(place.latitude, place.longitude, zoom)
+    tiles_per_side = 1 << zoom
+    return [
+        Tile(zoom, centre.x + dx, centre.y + dy)
+        for dx in (-1, 0, 1)
+        for dy in (-1, 0, 1)
+        if 0 <= centre.x + dx < tiles_per_side and 0 <= centre.y + dy < tiles_per_side
+    ]
+
+
+def _outline_seeds(coarse: PolygonalGeometry, coarse_zoom: int, zoom: int) -> list[Tile]:
+    """Every tile at ``zoom`` that touches the coarse outline, with half a tile of margin."""
+    scale = 1 << (zoom - coarse_zoom)
+    reach = shapely.transform(coarse, lambda points: points * scale).buffer(TILE_EXTENT / 2)
+    prepared_reach = prep(reach)
+    west, north, east, south = (int(edge // TILE_EXTENT) for edge in reach.bounds)
+    last = (1 << zoom) - 1
+    return [
+        tile
+        for x in range(max(west, 0), min(east, last) + 1)
+        for y in range(max(north, 0), min(south, last) + 1)
+        if prepared_reach.intersects((tile := Tile(zoom, x, y)).square)
+    ]
+
+
+def _estimated_tiles(coarse: PolygonalGeometry, coarse_zoom: int, zoom: int) -> float:
+    """Roughly how many tiles a walk at ``zoom`` fetches: the inside plus a ring both sides."""
+    scale = 1 << (zoom - coarse_zoom)
+    inside_tiles = coarse.area / (TILE_EXTENT * TILE_EXTENT) * scale * scale
+    outline_tiles = coarse.length / TILE_EXTENT * scale
+    return inside_tiles + 2 * outline_tiles + 4
+
+
+def _require_boundary_steps(place: Place, options: FetchOptions) -> Steps[None]:
+    """Raise when Google draws no boundary for the place.
+
+    A tile on the far side of the world is outside any real place. For a place with a
+    boundary it carries a full mask. For a place without one it carries no mask.
+    """
+    near = tile_containing(place.latitude, place.longitude, _PROBE_ZOOM)
+    tiles_per_side = 1 << _PROBE_ZOOM
+    far = Tile(_PROBE_ZOOM, (near.x + tiles_per_side // 2) % tiles_per_side, near.y)
+    (body,) = yield [
+        tile_url(far, place.cell_id, place.feature_number, options.language, options.region)
+    ]
+    if not decode_place_part(body, far).has_mask:
+        label = place.name or place.feature_id
+        raise NoBoundaryError(
+            f"Google Maps draws no boundary for {label!r}. "
+            "Boundaries exist for areas such as localities, cities and postal codes."
+        )
+
+
+def _coarse_outline_steps(
+    place: Place, finest_zoom: int, options: FetchOptions
+) -> Steps[tuple[PolygonalGeometry, int]]:
+    """Read the outline at the first coarse zoom that fits the tile cap."""
+    for coarse_zoom in _COARSE_ZOOMS:
+        if coarse_zoom > finest_zoom:
+            continue
+        try:
+            coarse = yield from _walk_steps(
+                place, _label_seeds(place, coarse_zoom), options.max_tiles, options
+            )
+        except _WalkTooLargeError:
+            continue
+        return coarse, coarse_zoom
+    raise TooManyTilesError(
+        f"the place needs more than max_tiles={options.max_tiles} tiles even at zoom 0"
+    )
+
+
+def _finest_zoom_within_cap(
+    coarse: PolygonalGeometry, coarse_zoom: int, options: FetchOptions
+) -> int:
+    tile_budget = options.max_tiles * _AUTO_ZOOM_FILL_RATIO
+    for zoom in range(MAX_ZOOM, coarse_zoom, -1):
+        if _estimated_tiles(coarse, coarse_zoom, zoom) <= tile_budget:
+            return zoom
+    return coarse_zoom
+
+
+def boundary_steps(query: PlaceQuery, options: FetchOptions) -> Steps[Boundary]:
+    """The whole job: resolve the place, check it has a boundary, read the outline."""
+    place = yield from place_steps(query, options.language, options.region)
+    yield from _require_boundary_steps(place, options)
+    finest_zoom = MAX_ZOOM if options.zoom is None else options.zoom
+    coarse, coarse_zoom = yield from _coarse_outline_steps(place, finest_zoom, options)
+
+    if coarse.is_empty:
+        # The place is too small to show at the coarse zoom. Read it at the finest zoom directly.
+        try:
+            outline = yield from _walk_steps(
+                place, _label_seeds(place, finest_zoom), options.max_tiles, options
+            )
+        except _WalkTooLargeError as error:
+            raise TooManyTilesError(
+                f"the place needs more than max_tiles={options.max_tiles} tiles "
+                f"at zoom {finest_zoom}"
+            ) from error
+        zoom = finest_zoom
+    elif options.zoom is None:
+        zoom = _finest_zoom_within_cap(coarse, coarse_zoom, options)
+        outline = coarse
+        while zoom > coarse_zoom:
+            try:
+                outline = yield from _walk_steps(
+                    place, _outline_seeds(coarse, coarse_zoom, zoom), options.max_tiles, options
+                )
+                break
+            except _WalkTooLargeError:
+                zoom -= 1
+    else:
+        zoom = options.zoom
+        outline = coarse
+        if zoom > coarse_zoom:
+            estimate = _estimated_tiles(coarse, coarse_zoom, zoom)
+            too_many = TooManyTilesError(
+                f"zoom {zoom} needs about {estimate:.0f} tiles, more than max_tiles="
+                f"{options.max_tiles}. Lower zoom, raise max_tiles, or pass zoom=None."
+            )
+            if estimate > options.max_tiles:
+                raise too_many
+            try:
+                outline = yield from _walk_steps(
+                    place, _outline_seeds(coarse, coarse_zoom, zoom), options.max_tiles, options
+                )
+            except _WalkTooLargeError as error:
+                raise too_many from error
+
+    if outline.is_empty:
+        raise NoBoundaryError(
+            f"no boundary found near the label point of {place.name or place.feature_id!r}"
+        )
+    geometry = shapely.transform(outline, lambda points: global_units_to_lng_lat(points, zoom))
+    return Boundary(place=place, zoom=zoom, geometry=_polygons_only(geometry))