Add multi-origin batch calls to the block, point, and catchment methods.

Author: Nathaniel Henry

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.5.0
+
+- Multi-origin calls. `block_summary`, `block_pois`, `point_summary`,
+  `point_pois`, and `poi_catchment` now accept many origins in one request:
+  pass a list of GEOIDs (or `dest_id`s), or a list of `(lat, lon)` points, and
+  the whole set is queried in a single call — one request against the
+  300/minute rate limit instead of one per origin. Results come back as a flat
+  frame tagged by origin (`geoid`, or `origin_lat` / `origin_lon`, or
+  `dest_id`); per-origin `errors` and any `truncated` origins ride on
+  `df.attrs`. A batch is charged only for what the account can pay for, so a
+  huge query stops at the balance rather than overspending.
+
 ## 1.4.0
 
 - `Client.place_boundary(geoid)` — the boundary polygon of a census place, as a

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "closecity"
-version = "1.4.0"
+version = "1.5.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"

src/closecity/__init__.py

@@ -23,7 +23,7 @@
 from .spatial import to_geopandas
 from .tabular import to_pandas
 
-__version__ = "1.4.0"
+__version__ = "1.5.0"
 
 __all__ = [
     "Client",

src/closecity/client.py

@@ -49,6 +49,23 @@ def _as_list(value: Any) -> Any:
     return [value]
 
 
+def _point_origins(points: Any) -> list[dict[str, float]]:
+    """Normalise a batch of point origins to ``[{"lon": .., "lat": ..}, ...]``.
+
+    Each item is either a ``(lat, lon)`` pair — matching the ``(lat, lon)``
+    argument order of the single-point calls — or a ``{"lat": .., "lon": ..}``
+    mapping.
+    """
+    out: list[dict[str, float]] = []
+    for point in points:
+        if isinstance(point, dict):
+            out.append({"lon": point["lon"], "lat": point["lat"]})
+        else:
+            lat, lon = point
+            out.append({"lon": lon, "lat": lat})
+    return out
+
+
 def _int(value: str | None) -> int | None:
     return int(value) if value is not None else None
 
@@ -329,39 +346,78 @@ def places(self, q: str, *, limit: int | None = None, output: str | None = None)
     # -- origin block / point (metered) -------------------------------------
 
     def block_summary(
-        self, geoid: str, *, mode = None, type = None,
+        self, geoid, *, mode = None, type = None,
         if_none_match: str | None = None, output: str | None = None,
     ):
         """Fastest travel time to each destination category from a census block,
         by mode. `geoid` is a 15-digit block GEOID; `mode`/`type` are optional
         filters (scalar or list). Supports `if_none_match` (ETag/304). A DataFrame
-        (the origin GEOID broadcast to a `geoid` column), or a raw `Reply`."""
+        (the origin GEOID broadcast to a `geoid` column), or a raw `Reply`.
+
+        Pass a **list of GEOIDs** to query many blocks in one call (one request,
+        one rate-limit tick): the frame is the flat, `geoid`-tagged union of every
+        origin's rows, and per-origin `errors` / `truncated` / `truncated_reason`
+        ride on `df.attrs`. `if_none_match` applies to the single-block form only.
+        """
+        if isinstance(geoid, (list, tuple)):
+            reply = self._request("POST", "/v1/blocks/summary", json = _clean(
+                {"origins": list(geoid), "mode": _as_list(mode),
+                 "type": _as_list(type)}))
+            return self._deliver(reply, geometry = False, key = "results",
+                                 output = output)
         return self._deliver(
             self._get(f"/v1/blocks/{geoid}/summary",
                       {"mode": mode, "type": type}, if_none_match = if_none_match),
             geometry = False, key = "results", output = output,
         )
 
     def block_pois(
-        self, geoid: str, *, mode = None, type = None, dest_id = None,
+        self, geoid, *, mode = None, type = None, dest_id = None,
         max_minutes = None, limit = None, output: str | None = None,
     ):
         """Every nearby POI and its travel time from a block, one row per (POI,
         mode). A GeoDataFrame of points (a plain DataFrame under
-        `output="tabular"`, a `Paginator` under `output="raw"`)."""
+        `output="tabular"`, a `Paginator` under `output="raw"`).
+
+        Pass a **list of GEOIDs** to query many blocks in one call (one request,
+        one rate-limit tick): rows are the flat, `geoid`-tagged union of every
+        origin's POIs, with per-origin `errors` / `truncated` / `truncated_reason`
+        on `df.attrs`. The batch form is not paginated (`limit` is ignored)."""
+        if isinstance(geoid, (list, tuple)):
+            reply = self._request("POST", "/v1/blocks/pois", json = _clean(
+                {"origins": list(geoid), "mode": _as_list(mode),
+                 "type": _as_list(type), "dest_id": _as_list(dest_id),
+                 "max_minutes": max_minutes}))
+            return self._deliver(reply, geometry = True, output = output)
         return self._deliver(Paginator(
             self, "GET", f"/v1/blocks/{geoid}/pois",
             _clean({"mode": mode, "type": type, "dest_id": dest_id,
                     "max_minutes": max_minutes, "limit": limit}),
         ), geometry = True, output = output)
 
     def point_summary(
-        self, lat: float, lon: float, *, mode = None, type = None,
+        self, lat, lon = None, *, mode = None, type = None,
         if_none_match: str | None = None, output: str | None = None,
     ):
         """Like `block_summary`, but from the census block containing a lat/lon.
         The resolved block GEOID is echoed as `resolved_block` and broadcast to a
-        `geoid` column. A DataFrame, or a raw `Reply`."""
+        `geoid` column. A DataFrame, or a raw `Reply`.
+
+        Pass a **list of points** as the first argument — each a `(lat, lon)` pair
+        or a `{"lat": .., "lon": ..}` mapping — to query many points in one call.
+        Each row is tagged with its `origin_lat` / `origin_lon`; resolved blocks,
+        `errors`, and `truncated` ride on `df.attrs`."""
+        if isinstance(lat, (list, tuple)):
+            if lon is not None:
+                raise ValueError(
+                    "For multiple points pass a list of (lat, lon) pairs as the "
+                    "first argument and leave lon unset."
+                )
+            reply = self._request("POST", "/v1/point/summary", json = _clean(
+                {"origins": _point_origins(lat), "mode": _as_list(mode),
+                 "type": _as_list(type)}))
+            return self._deliver(reply, geometry = False, key = "results",
+                                 output = output)
         return self._deliver(
             self._get("/v1/point/summary",
                       {"lat": lat, "lon": lon, "mode": mode, "type": type},
@@ -370,12 +426,28 @@ def point_summary(
         )
 
     def point_pois(
-        self, lat: float, lon: float, *, mode = None, type = None, dest_id = None,
+        self, lat, lon = None, *, mode = None, type = None, dest_id = None,
         max_minutes = None, limit = None, output: str | None = None,
     ):
         """Like `block_pois`, but from the block containing a lat/lon. A
         GeoDataFrame of points (a plain DataFrame under `output="tabular"`, a
-        `Paginator` under `output="raw"`)."""
+        `Paginator` under `output="raw"`).
+
+        Pass a **list of points** as the first argument — each a `(lat, lon)` pair
+        or a `{"lat": .., "lon": ..}` mapping — to query many points in one call.
+        Each row is tagged with its `origin_lat` / `origin_lon`. The batch form is
+        not paginated (`limit` is ignored)."""
+        if isinstance(lat, (list, tuple)):
+            if lon is not None:
+                raise ValueError(
+                    "For multiple points pass a list of (lat, lon) pairs as the "
+                    "first argument and leave lon unset."
+                )
+            reply = self._request("POST", "/v1/point/pois", json = _clean(
+                {"origins": _point_origins(lat), "mode": _as_list(mode),
+                 "type": _as_list(type), "dest_id": _as_list(dest_id),
+                 "max_minutes": max_minutes}))
+            return self._deliver(reply, geometry = True, output = output)
         return self._deliver(Paginator(
             self, "GET", "/v1/point/pois",
             _clean({"lat": lat, "lon": lon, "mode": mode, "type": type,
@@ -408,12 +480,22 @@ def poi(self, dest_id: int, *, if_none_match: str | None = None,
         )
 
     def poi_catchment(
-        self, dest_id: int, *, mode = None, block = None, max_minutes = None,
+        self, dest_id, *, mode = None, block = None, max_minutes = None,
         limit = None, output: str | None = None,
     ):
         """Every census block that can reach a POI, one row per (block, mode).
         A GeoDataFrame of block polygons (a plain DataFrame under
-        `output="tabular"`, a `Paginator` under `output="raw"`)."""
+        `output="tabular"`, a `Paginator` under `output="raw"`).
+
+        Pass a **list of dest_ids** to query many POIs in one call (one request,
+        one rate-limit tick): rows are the flat, `dest_id`-tagged union of every
+        POI's catchment, with per-POI `errors` / `truncated` on `df.attrs`. The
+        batch form is not paginated (`limit` is ignored)."""
+        if isinstance(dest_id, (list, tuple)):
+            reply = self._request("POST", "/v1/pois/catchment", json = _clean(
+                {"dest_ids": list(dest_id), "mode": _as_list(mode),
+                 "block": _as_list(block), "max_minutes": max_minutes}))
+            return self._deliver(reply, geometry = True, output = output)
         return self._deliver(Paginator(
             self, "GET", f"/v1/pois/{dest_id}/catchment",
             _clean({"mode": mode, "block": block, "max_minutes": max_minutes,

tests/test_client.py

@@ -160,6 +160,120 @@ def handler(request):
     assert bodies[1]["cursor"] == "C2"  # cursor threaded through the body
 
 
+# -- multi-origin (batch) ----------------------------------------------------
+
+def test_block_summary_list_posts_to_batch():
+    seen = {}
+
+    def handler(request):
+        seen["method"] = request.method
+        seen["path"] = request.url.path
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json = {
+            "results": [{"geoid": "g1", "dest_type_id": 30, "mode": "walk",
+                         "travel_time": 6.5}],
+            "blocks": [{"geoid": "g1", "population": 10, "land_area_m2": 1.0}],
+            "errors": [], "truncated": [], "truncated_reason": None,
+        })
+
+    reply = make_client(handler).block_summary(["g1", "g2"], mode = "walk", type = 30)
+    assert seen["method"] == "POST"
+    assert seen["path"] == "/v1/blocks/summary"
+    assert seen["body"]["origins"] == ["g1", "g2"]
+    # Scalar mode/type get wrapped to arrays for the POST body.
+    assert seen["body"]["mode"] == ["walk"] and seen["body"]["type"] == [30]
+    assert reply.data["results"][0]["geoid"] == "g1"
+
+
+def test_block_summary_scalar_still_gets():
+    seen = {}
+
+    def handler(request):
+        seen["method"] = request.method
+        seen["path"] = request.url.path
+        return httpx.Response(200, json = {"block": {"geoid": "g", "population": None,
+                              "land_area_m2": None}, "results": []})
+
+    make_client(handler).block_summary("410390020001010")
+    assert seen["method"] == "GET"
+    assert seen["path"] == "/v1/blocks/410390020001010/summary"
+
+
+def test_block_pois_list_posts_to_batch():
+    seen = {}
+
+    def handler(request):
+        seen["method"] = request.method
+        seen["path"] = request.url.path
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json = {"results": [], "errors": [],
+                              "truncated": [], "truncated_reason": None})
+
+    make_client(handler).block_pois(["g1", "g2"], type = 30, max_minutes = 10)
+    assert seen["method"] == "POST"
+    assert seen["path"] == "/v1/blocks/pois"
+    assert seen["body"]["origins"] == ["g1", "g2"]
+    assert seen["body"]["type"] == [30] and seen["body"]["max_minutes"] == 10
+
+
+def test_point_summary_list_posts_origins_lonlat():
+    seen = {}
+
+    def handler(request):
+        seen["path"] = request.url.path
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json = {"results": [], "origins": [],
+                              "errors": [], "truncated": [], "truncated_reason": None})
+
+    # A (lat, lon) pair and a {lat, lon} mapping both normalise to {lon, lat}.
+    make_client(handler).point_summary([(44.0, -123.0), {"lat": 45.0, "lon": -122.0}])
+    assert seen["path"] == "/v1/point/summary"
+    assert seen["body"]["origins"] == [
+        {"lon": -123.0, "lat": 44.0}, {"lon": -122.0, "lat": 45.0}]
+
+
+def test_point_pois_list_with_lon_raises():
+    with pytest.raises(ValueError, match = "list of \\(lat, lon\\) pairs"):
+        make_client(lambda r: httpx.Response(200)).point_pois([(44.0, -123.0)], -1.0)
+
+
+def test_poi_catchment_list_posts_dest_ids():
+    seen = {}
+
+    def handler(request):
+        seen["path"] = request.url.path
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json = {"results": [], "errors": [],
+                              "truncated": [], "truncated_reason": None})
+
+    make_client(handler).poi_catchment([4181, 4182], mode = "walk")
+    assert seen["path"] == "/v1/pois/catchment"
+    assert seen["body"]["dest_ids"] == [4181, 4182]
+    assert seen["body"]["mode"] == ["walk"]
+
+
+def test_batch_tabular_frame_carries_origin_and_attrs():
+    def handler(request):
+        return httpx.Response(200, json = {
+            "results": [{"geoid": "g1", "dest_type_id": 30, "mode": "walk",
+                         "travel_time": 6.5},
+                        {"geoid": "g2", "dest_type_id": 30, "mode": "walk",
+                         "travel_time": 9.0}],
+            "blocks": [], "errors": [{"geoid": "gX", "type": "block-not-found",
+                                      "detail": "no"}],
+            "truncated": ["g9"], "truncated_reason": "row-budget",
+        })
+
+    client = Client("ck_live_abc", base_url = "https://api.close.city",
+                    output = "tabular", transport = httpx.MockTransport(handler))
+    df = client.block_summary(["g1", "g2", "gX", "g9"])
+    assert list(df["geoid"]) == ["g1", "g2"]
+    # Per-origin errors / truncation ride on df.attrs.
+    assert df.attrs["truncated"] == ["g9"]
+    assert df.attrs["truncated_reason"] == "row-budget"
+    assert df.attrs["errors"][0]["type"] == "block-not-found"
+
+
 # -- conditional requests ----------------------------------------------------
 
 def test_if_none_match_304_is_free_and_not_modified():