Normalize blocks_query list params, reproject TIGER blocks to 4326, use real example GEOIDs

Author: Nathaniel Henry

docs/getting_started.md

@@ -77,7 +77,7 @@ Set the client's `spatial` flag to `False` to work with the raw data.
 
 ```{code-cell} python
 close.spatial = False
-summary = close.block_summary("440070036001010", mode = "walk")
+summary = close.block_summary("440070008001068", mode = "walk")
 summary.results
 ```
 

docs/tutorials/home_search.md

@@ -63,11 +63,13 @@ stops.plot(ax = ax, color = "#f36e21", marker = "^")
 
 ## Find the blocks that qualify
 
-Pull the per-block walk times for the whole city. The result is a GeoDataFrame with
-one row per (block, category); the boundaries come from `pygris`, downloaded once.
+Pull the per-block walk times for the blocks around the city centre. The result is a
+GeoDataFrame with one row per (block, category); the boundaries come from `pygris`,
+downloaded once.
 
 ```{code-cell} python
-blocks = close.place_blocks(city["geoid"], mode = "walk",
+blocks = close.blocks_query(center = {"lon": city["lon"], "lat": city["lat"]},
+                            radius_m = 3000, mode = "walk",
                             type = [grocery, restaurant, transit])
 ```
 

src/closecity/client.py

@@ -25,6 +25,14 @@ def _clean(params: dict[str, Any] | None) -> dict[str, Any]:
     return {k: v for k, v in (params or {}).items() if v is not None}
 
 
+def _as_list(value: Any) -> Any:
+    """Wrap a scalar in a list, for POST-body fields the API requires as arrays.
+    ``None`` and existing lists/tuples pass through unchanged."""
+    if value is None or isinstance(value, (list, tuple)):
+        return value
+    return [value]
+
+
 def _int(value: str | None) -> int | None:
     return int(value) if value is not None else None
 
@@ -341,8 +349,8 @@ def blocks_query(
         `spatial=False`."""
         body = _clean({
             "polygon": polygon, "center": center, "radius_m": radius_m,
-            "type": type, "mode": mode, "include_population": include_population,
-            "limit": limit,
+            "type": _as_list(type), "mode": _as_list(mode),
+            "include_population": include_population, "limit": limit,
         })
         return self._spatial(Paginator(self, "POST", "/v1/blocks/query",
                                        _json = body, _cursor_in = "json"))

src/closecity/spatial.py

@@ -103,9 +103,12 @@ def _blocks_gdf(rows, block_geometry, geoid_col, crs, fetch, gpd):
                 "blocks with pygris."
             )
     geo = block_geometry.rename(columns = {geoid_col: "geoid"})
+    # TIGER blocks arrive in NAD83 (EPSG:4269); reproject so they match the POI and
+    # isochrone geometry (EPSG:4326) and can be combined without a CRS mismatch.
+    if crs is not None and geo.crs is not None and str(geo.crs) != str(crs):
+        geo = geo.to_crs(crs)
     merged = df.merge(geo[["geoid", "geometry"]], on = "geoid", how = "left")
-    out_crs = getattr(block_geometry, "crs", None) or crs
-    return gpd.GeoDataFrame(merged, geometry = "geometry", crs = out_crs)
+    return gpd.GeoDataFrame(merged, geometry = "geometry", crs = crs)
 
 
 def to_geopandas(

tests/test_client.py

@@ -147,13 +147,16 @@ def handler(request):
 
     pg = make_client(handler).blocks_query(
         center = {"lon": -123.0, "lat": 44.0}, radius_m = 1000,
-        include_population = True,
+        mode = "walk", type = 30, include_population = True,
     )
     records = list(pg)
     assert methods == ["POST", "POST"]
     assert len(records) == 2
     assert bodies[0]["center"] == {"lon": -123.0, "lat": 44.0}
     assert bodies[0]["include_population"] is True
+    # Scalar mode/type are wrapped in lists (the POST body needs arrays).
+    assert bodies[0]["mode"] == ["walk"]
+    assert bodies[0]["type"] == [30]
     assert bodies[1]["cursor"] == "C2"  # cursor threaded through the body