Add place_pois(), a close_map() interactive-map helper, and the places state column (1.3.0)

Author: Nathaniel Henry

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.3.0
+
+- `Client.place_pois(geoid, ...)` — every point of interest within a census
+  place (city or town), by place GEOID. The place analog of `pois_search`; pass
+  `type` to get, e.g., all supermarkets in a city.
+- `close_map(gdf, ...)` — a one-line interactive map (CARTO Positron basemap,
+  hoverable points, or filled blocks that highlight the features meeting a
+  criterion) for the GeoDataFrames the client returns. Built on plotly (the
+  `closecity[maps]` extra); GDAL-free.
+- `places()` results now carry a `state` column (two-letter USPS abbreviation),
+  so same-named places are distinguishable.
+
 ## 1.2.0
 
 - `Client()` reads the `CLOSECITY_KEY` environment variable when no `api_key` is

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "closecity"
-version = "1.2.0"
+version = "1.3.0"
 description = "Python client for the Close API (api.close.city). Travel times to points of interest for every US census block."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -32,10 +32,12 @@ API = "https://api.close.city"
 dev = ["pytest>=8", "ruff>=0.6"]
 # Only needed to auto-download census-block boundaries (blocks map by default).
 tiger = ["pygris"]
+# Interactive maps via close_map() (GDAL-free).
+maps = ["plotly>=5"]
 # Building the Sphinx documentation site. myst-nb runs the tutorial notebooks;
 # matplotlib draws the maps; pygris downloads block boundaries during execution.
 docs = ["sphinx>=7", "furo", "sphinx-copybutton", "myst-nb", "jupytext",
-        "matplotlib", "pygris"]
+        "matplotlib", "pygris", "plotly>=5"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

src/closecity/__init__.py

@@ -19,15 +19,17 @@
     ServiceUnavailableError,
     TokensExhaustedError,
 )
+from .map import close_map
 from .spatial import to_geopandas
 from .tabular import to_pandas
 
-__version__ = "1.1.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "Client",
     "Paginator",
     "Reply",
+    "close_map",
     "to_geopandas",
     "to_pandas",
     "CloseError",

src/closecity/client.py

@@ -457,6 +457,20 @@ def place_blocks(
                     "include_population": include_population, "limit": limit}),
         ), geometry = True, output = output)
 
+    def place_pois(
+        self, geoid: str, *, type = None, q = None, limit = None,
+        output: str | None = None,
+    ):
+        """Every point of interest within a census place (city or town), by
+        place GEOID. The place analog of `pois_search`; pass `type` to get,
+        e.g., all supermarkets in a city. Spatial only — no travel times. A
+        GeoDataFrame of points (a plain DataFrame under `output="tabular"`, a
+        `Paginator` under `output="raw"`)."""
+        return self._deliver(Paginator(
+            self, "GET", f"/v1/places/{geoid}/pois",
+            _clean({"type": type, "q": q, "limit": limit}),
+        ), geometry = True, output = output)
+
     # -- isochrone ----------------------------------------------------------
 
     def isochrone(

src/closecity/map.py

@@ -0,0 +1,86 @@
+"""A one-line interactive map for the GeoDataFrames the client returns.
+
+Built on plotly over a CARTO Positron basemap: points become bright hoverable
+markers, block polygons are filled and can highlight the features meeting a
+criterion. plotly is GDAL-free (unlike leaflet/mapgl in R), and geopandas emits
+the GeoJSON directly, so no extra system dependency.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def close_map(
+    gdf,
+    *,
+    color: str = "#e8590c",
+    highlight: Any = None,
+    label: str = "name",
+    size: int = 9,
+    zoom: float = 10,
+    opacity: float = 0.65,
+):
+    """Draw a :class:`geopandas.GeoDataFrame` from a client method as an
+    interactive map on a CARTO Positron basemap.
+
+    Points (POIs, places) render as bright hoverable markers; polygons (census
+    blocks) are filled, optionally greying the features that do not meet
+    ``highlight`` so the ones that matter stand out.
+
+    ``highlight`` is either a boolean sequence (length ``len(gdf)``) or the name
+    of a boolean/0-1 column. ``label`` names the hover column. Returns a plotly
+    ``Figure``.
+    """
+    try:
+        import plotly.graph_objects as go
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "close_map needs plotly: pip install 'closecity[maps]' or plotly"
+        ) from exc
+
+    g = gdf.to_crs(4326)
+    hl = None
+    if highlight is not None:
+        col = g[highlight] if isinstance(highlight, str) else highlight
+        hl = [bool(v) for v in col]
+
+    minx, miny, maxx, maxy = g.total_bounds
+    center = {"lon": (minx + maxx) / 2, "lat": (miny + maxy) / 2}
+    hover = g[label].astype(str).tolist() if label in g.columns else None
+    geom_type = g.geom_type.iloc[0] if len(g) else "Point"
+
+    if "Point" in geom_type:
+        marker_color = color if hl is None else [
+            color if h else "#888888" for h in hl
+        ]
+        fig = go.Figure(go.Scattermapbox(
+            lat = g.geometry.y.tolist(), lon = g.geometry.x.tolist(),
+            mode = "markers",
+            marker = dict(size = size, color = marker_color),
+            text = hover, hoverinfo = "text" if hover else "none",
+        ))
+    else:
+        import json
+
+        g = g.reset_index(drop = True)
+        g["_id"] = [str(i) for i in range(len(g))]
+        z = [1] * len(g) if hl is None else [int(h) for h in hl]
+        geojson = json.loads(g[["_id", "geometry"]].to_json())
+        colorscale = (
+            [[0, color], [1, color]] if hl is None
+            else [[0, "#888888"], [1, color]]
+        )
+        fig = go.Figure(go.Choroplethmapbox(
+            geojson = geojson, locations = g["_id"].tolist(), z = z,
+            featureidkey = "properties._id", colorscale = colorscale,
+            showscale = False,
+            marker = dict(opacity = opacity, line = dict(width = 0)),
+            text = hover, hoverinfo = "text" if hover else "none",
+        ))
+
+    fig.update_layout(
+        mapbox = dict(style = "carto-positron", zoom = zoom, center = center),
+        margin = dict(l = 0, r = 0, t = 0, b = 0),
+    )
+    return fig

tests/test_map.py

@@ -0,0 +1,39 @@
+"""close_map builds a plotly Figure from a GeoDataFrame; no network. Skipped
+when the optional plotting deps are absent."""
+
+import pytest
+
+gpd = pytest.importorskip("geopandas")
+pytest.importorskip("plotly")
+from shapely.geometry import Point, Polygon  # noqa: E402
+
+from closecity import close_map  # noqa: E402
+
+
+def _points():
+    return gpd.GeoDataFrame(
+        {"name": ["A", "B"]},
+        geometry = [Point(-71.41, 41.82), Point(-71.42, 41.83)],
+        crs = 4326,
+    )
+
+
+def _polys():
+    def sq(x, y):
+        return Polygon([(x, y), (x + 0.01, y), (x + 0.01, y + 0.01),
+                        (x, y + 0.01), (x, y)])
+    return gpd.GeoDataFrame(
+        {"name": ["g1", "g2"], "near": [True, False]},
+        geometry = [sq(-71.42, 41.82), sq(-71.40, 41.82)], crs = 4326,
+    )
+
+
+def test_close_map_points():
+    import plotly.graph_objects as go
+    assert isinstance(close_map(_points(), color = "#e8590c"), go.Figure)
+
+
+def test_close_map_polygons_with_highlight():
+    import plotly.graph_objects as go
+    fig = close_map(_polys(), color = "#2f9e44", highlight = "near")
+    assert isinstance(fig, go.Figure)