osmfeatures 0.7.2__tar.gz → 0.7.4__tar.gz

osmfeatures-0.7.4/.cursor/rules/maplark-mcp-dogfood.mdc

@@ -0,0 +1,12 @@
+---
+description: Prefer MapLark MCP for map and density demos in this repo
+alwaysApply: true
+---
+
+# MapLark MCP in osmfeatures-py
+
+When the user asks for a map, heatmap, density view, or live OSM visualization—and MapLark MCP is connected—use those MCP tools (`density`, `preview_map`, `places_search`, etc.), not the local CLI (`osmfeatures …`), shell scripts, or `PreviewServer` in this codebase.
+
+Use the SDK/CLI/local preview only when the user is clearly developing or debugging the client (tests, CLI flags, MCP server code).
+
+Geo flow for heatmaps: `density` → `preview_map` on the returned `collection_id`. Country or region: `geocode` first for bbox when the user named a place.

osmfeatures-0.7.4/AUTO_TILES.md

@@ -0,0 +1,50 @@
+# auto_split tiling
+
+Code: `iter_split_tiles` in `src/osmfeatures/_split.py`. Same walk for `query(auto_split=True)` and `places_search(auto_split=True)`.
+
+The API will not return one huge bbox. Two different things can go wrong, so we use two different probes.
+
+## Two problems, two probes
+
+**Too many matches (density).** Inner Stockholm can be a small rectangle with 200k buildings. One fetch is only allowed `max_limit` rows (from `GET /v1/account/tier`). If we fetch first, the server 400s `result_too_large` and we have learned nothing except “too many.”
+
+So we call `GET /v2/osm_features/count` first. That returns `{total: N}` with no geometries. If `N` is over the cap, we split the bbox into enough tiles that each *would* hold at most the cap, assuming matches are spread evenly. Then we count (and maybe fetch) each smaller tile. Empty tiles (`total == 0`) are skipped.
+
+**Too big a rectangle (area).** Greater Stockholm cafes can be a tiny `total` and still fail: the bbox is larger than one search/query is allowed to scan (free tier example: 0.04 square degrees). Count does not tell you that. Count is allowed a much bigger window (~400 deg²).
+
+So we do **not** split on a count-area error. That error looks like `count bbox area … limit 400`. The `400` is how big a **count** may be, not how big a fetch may be. Jumping to 400 deg² tiles would still 400 on every fetch.
+
+We split on a **fetch** area error instead: `bbox area 5.0 exceeds the tagged tier limit 0.04`. The `0.04` is the real tile size. We remember it and jump the rest of the bbox to that size in one shot, instead of trying every quarter.
+
+```
+density  → count.total vs max_limit     → split before fetch
+area     → fetch 400 “bbox area … Y”    → split to tiles of size Y
+not area → count 400 “count bbox area”  → give up (window too big to count)
+```
+
+## The algorithm
+
+Queue starts with the requested bbox (or `bbox_tiles` pieces if the caller already split). Cap: 32 tiles.
+
+For each tile:
+
+1. If we already know the fetch area cap `Y`, and this tile is larger than `Y`, split it to that size and skip count/fetch.
+2. Count the tile.
+   - `total == 0`: skip.
+   - `total` over the row cap: replace with a power-of-2 grid (`ceil(total / cap)`, rounded up to 2, 4, 8, …). Do this at most twice (the original tile, then one leftover dense child). Need more than 32 tiles, or a third split: `OSMFeaturesTooDenseError`.
+   - Count 400 `count bbox area`: re-raise. Do not split.
+   - Count 400 that names the **fetch** cap (`bbox area … limit Y`, no `count` prefix): remember `Y` and jump.
+3. Fetch the tile (`GET /v3/osm_features` or `POST /v1/places/search`).
+   - Fetch 400 `bbox area … Y`: remember `Y`, jump, do not probe every quarter.
+   - Fetch 400 `result_too_large` after a count that already fit: `OSMFeaturesTooDenseError`. Count was wrong; splitting again would thrash.
+   - Success: keep the page.
+
+Covering the bbox would need more than 32 tiles (usually an area jump): `OSMFeaturesTooManyTilesError`. That is “the window is too large,” not “too crowded.” Shrink the named place. Do not keep bisecting.
+
+Results from tiles are merged and deduped by feature `id` (tiles share edges).
+
+`limit=10` is a page size. It truncates; it does not lower the density cap. 20 matches with `limit=10` stay one tile.
+
+`bbox_tiles=4` without `auto_split` just fetches those 4 tiles. No count, no second jump.
+
+Hours on `places_search` (`as_of` / `open_now`) use a 10k parse/scan cap instead of `max_limit`. See `_places.py`.

{osmfeatures-0.7.2 → osmfeatures-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: osmfeatures
-Version: 0.7.2
+Version: 0.7.4
 Summary: Official client for the MapLark OpenStreetMap Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV)
 Project-URL: Homepage, https://maplark.com
 Project-URL: Repository, https://github.com/MapLark/osmfeatures-python
@@ -54,6 +54,7 @@ Official Python client for the [MapLark OSM Features API](https://maplark.com) w
   - [Query OSM features](#query-osm-features)
   - [Query a large bbox](#query-a-large-bbox)
   - [Count](#count)
+  - [Density](#density)
   - [Async client](#async-client)
   - [Convenience helpers](#convenience-helpers)
   - [Usage](#usage)
@@ -145,7 +146,7 @@ with OSMFeaturesClient(api_key="sk-...") as client:
 
 ### Query OSM features
 
-`query()` calls `GET /v3/osm_features` and returns the whole tile. Omit `limit` for the API default. Paid keys may raise `limit` up to their `max_limit` (enterprise 1000000). A larger match set is truncated (`X-Has-More: true`). Pass `split_until_fit=True` to quarter the bbox until each piece fits. That adds latency. Pass `bbox_tiles=2` (or 4, 8, ...) to split the bbox up front. `query()` does not take `cursor`.
+`query()` calls `GET /v3/osm_features` and returns the whole tile. Omit `limit` for the API default. Paid keys may raise `limit` up to their `max_limit`. A larger match set is truncated (`X-Has-More: true`). Pass `auto_split=True` to read the key's `max_limit` from `GET /v1/account/tier`, count first with a scalar `GET /v2/osm_features/count` (no `group_by`), and jump to a power-of-2 tile grid when the match set exceeds that cap (one extra jump if a leftover leaf is still dense). That adds latency. Pass `bbox_tiles=2` (or 4, 8, ...) to split the bbox up front. `query()` does not take `cursor`.
 
 ```python
 fc = client.query(
@@ -168,7 +169,7 @@ Common filters:
 - `way_shape="polygon" | "line" | "all"` (omit = both shapes; `all` also means both)
 - `clip_geometry=True | False` (omit for the API default; set `False` to keep full geometry outside bbox)
 - `bbox_tiles=2` (power of 2) to split a bbox that exceeds your tier area cap
-- `split_until_fit=True` to split a bbox that exceeds `limit` (or the key's `max_limit`)
+- `auto_split=True` to count first, then fetch (reads `max_limit` from `GET /v1/account/tier`, cached on the client; jumps to a power-of-2 grid when the match set exceeds that cap; one extra jump if a leftover leaf is still dense; a lower `limit` truncates; jumps when a 400 names a bbox-area cap). Caps at 32 tiles (`OSMFeaturesTooManyTilesError` if covering the bbox needs more, `OSMFeaturesTooDenseError` if a tile still overflows). `OSMFeaturesTimeoutError` is only a real wall-clock miss.
 - `accept="text/csv"` / `"application/flatgeobuf"` / `"application/vnd.apache.parquet"` (returns `BinaryQueryResult`)
 
 
@@ -180,8 +181,7 @@ Use this to query a larger bbox than what is allowed by splitting the bbox up in
 all_restaurants = client.query(
     bbox="18.063,59.322,18.082,59.332",
     tags="amenity=restaurant",
-    split_until_fit=True,
-    max_features=1_000_000,
+    auto_split=True,
     timeout=60,
 )
 ```
@@ -191,7 +191,7 @@ all_restaurants = client.query(
 #### Count
 Analyze feature counts with a histogram over a very large area - city and country sized bounding boxes allowed. For example, you can find out how many cafes, bars, and restaurants are in different cities or countries.
 
-`client.count` calls `GET /v2/osm_features/count`. Example amenity histogram:
+`client.count` calls `GET /v2/osm_features/count`. Omit `group_by` for a scalar total. Example amenity histogram:
 
 ```python
 client.count(
@@ -205,6 +205,24 @@ client.count(
 ```
 
 
+#### Density
+
+`client.density` calls `GET /v2/osm_features/density`. Occupied grid bins come back as a GeoJSON FeatureCollection of points with `properties.count`, plus `total` and `truncated`. These are not OSM features (no `osm_id` or tags). Omit `cell_deg` for 0.1. `type` omitted is nodes. `tags` or `or_tags` is required. `limit` is the max occupied cells (the key's `max_limit` when omitted).
+
+A Europe box (`-26,33,52,72`, about 3042 deg²) fits the density area cap (4000 deg²) and the 80° span. It is above `max_units_per_request` on every non-enterprise tier, so pass `disable_budget_warning=True` to run it. The same box still 400s on count (area cap 400 deg²). A unit-cap 400 on count can use that flag the same way. A bbox-area 400 cannot.
+
+```python
+client.density(
+    bbox="-26,33,52,72",
+    tags=["place"],
+    cell_deg=0.1,
+    disable_budget_warning=True,
+)
+```
+
+CLI: `osmfeatures density --bbox -26,33,52,72 --tags place --cell-deg 0.1 --disable-budget-warning`.
+
+
 ### Async client
 
 Async methods mirror the sync API (`query_async`, `query_all_async`):
@@ -264,7 +282,7 @@ Results come back as summaries (ids, names, OSM tags, lon/lat scalars, `distance
 - Places: `places_search`, `places_nearby`, `places_details`
 - Geocode: `geocode` (Nominatim interim)
 - Routes: `routes_isochrone`, `routes_path`, `routes_optimized_path`
-- Generic OSM: `query`, `stats` (count/histogram)
+- Generic OSM: `query`, `count` (histogram / total), `density` (grid bins; `preview_map` the id)
 - Local (no HTTP): `nearest_within`, `pairs_within`, `filter_open`, `point_in_polygon`, `points_in_polygon`
 - Draw / export: `preview_map`, `export_geojson`
 
@@ -328,6 +346,7 @@ Planner rules: you pick tags, bbox or location+radius, budgets, `openNow`/`asOf`
 | "Cafes on a tour of Gamla Stan" | `places_search`, `filter_open` + `routes_optimized_path` (`loop=true`) |
 | "Suggest a walk to a bar, a restaurant, and a cafe, no particular order" | `routes_optimized_path` with `loop=false` |
 | "Is the office a 20-minute walk from the apartment?" | `routes_isochrone` from A, `point_in_polygon` for B |
+| "Amenity heatmap for Sweden" | `geocode` (bbox), `density` (`amenity`; `disable_budget_warning` if the unit cap 400s), `preview_map` |
 | "Show this on a map" | `preview_map(collection_id)` after a search or route |
 
 The same operations exist on `OSMFeaturesClient` when you are not going through an LLM (see [Places and routes](#places-and-routes)).
@@ -343,7 +362,16 @@ Runnable Python chains live in `tests/example_apps/test_geo_agent.py`. Full HTTP
 
 ### Places search
 
-`places_search()` finds places in a bounding box **or** a `location` plus `radius` (not both). Optional `tags` (AND) and `or_tags` (OR) use the same OSM filters as `query()`. Omit `limit` to use the API default (100, max 10_000).
+`places_search()` finds places in a bounding box **or** a `location` plus `radius` (not both). Optional `tags` (AND) and `or_tags` (OR) use the same OSM filters as `query()`. Omit `limit` to use the API default (100). Paid keys may raise `limit` up to their `/v3` `max_limit`; `asOf` / `openNow` still cap hours parse at 10_000.
+
+`bbox_tiles` and `auto_split` **only apply to bbox search** (same names as `query()`). Pass `bbox_tiles=2` (or 4, 8, ...) to split a bbox up front. Pass `auto_split=True` to count first via `GET /v2/osm_features/count` with `way_shape=polygon`, then fetch. No hours: split on `total` vs the key's `max_limit`. With `asOf` / `openNow`: AND `opening_hours`. An `asOf` page `limit` (default 100) truncates; density-split vs the 10k parse cap only when `limit` is raised above 10k. `openNow` density-splits vs that 10k scan cap even with a small fill limit. A search that exceeds the tagged **fetch** area cap 400s; that 400 is split in one jump from the limit in the message, not by probing every quarter, up to 32 tiles. A `count bbox area` 400 is not split (the window is still too big to count). location+radius is a circle and cannot split. To tile a radius window, convert it first with `around_to_bbox` (a square that contains the circle; corner hits can fall outside the original radius):
+
+```python
+from osmfeatures import around_to_bbox
+
+bbox = around_to_bbox(lon=18.075, lat=59.316, radius_m=800)
+cafes = client.places_search(bbox=bbox, or_tags=["amenity=cafe"], auto_split=True)
+```
 
 ```python
 cafes = client.places_search(
@@ -357,7 +385,7 @@ print(len(cafes["features"]), "open cafes")
 print(cafes["metadata"]["evaluated_at"])
 ```
 
-Response is a GeoJSON FeatureCollection plus `metadata.evaluated_at` (UTC instant used for hours).
+Response is a GeoJSON FeatureCollection plus `metadata.evaluated_at` (UTC instant used for hours) and `metadata.units` (credits charged). After `bbox_tiles` / `auto_split`, `units` is the sum of the search tiles.
 
 ### Nearby (ranked from a point)
 
@@ -375,7 +403,7 @@ for item in nearby["items"]:
     print(item["distance_m"], item["feature"]["id"])
 ```
 
-Response: `{status, items: [{feature, distance_m}], estimated_units, evaluated_at}`.
+Response: `{status, items: [{feature, distance_m}], units, evaluated_at}`.
 
 ### Place details
 
@@ -388,7 +416,7 @@ print(details["feature"]["properties"]["tags"])
 print(details["timezone"], details["evaluated_at"])
 ```
 
-Response: `{status, feature, estimated_units, evaluated_at, timezone}`. Hours are annotated at request time in the place's IANA zone (from its coordinates).
+Response: `{status, feature, units, evaluated_at, timezone}`. Hours are annotated at request time in the place's IANA zone (from its coordinates).
 
 ### Opening hours
 
@@ -499,6 +527,7 @@ The repository includes runnable example-app tests in `tests/example_apps/` show
 - `test_bike_path_dijkstra_liljeholmen_to_djurgarden.py`: tiled corridor bike routing from Liljeholmen to Djurgarden.
 - `test_geometry_filters.py`: zoom + area/length filters for large buildings and long roads.
 - `test_geo_agent.py`: Python places/routes chains (bar crawl, bike parks, isochrone filter/compare/coverage, client-side open-at-clock).
+- `test_auto_split.py`: ``auto_split`` for a city-scale cafe bbox (area cap) and dense inner-Stockholm buildings (``max_limit``).
 
 Run all example apps:
 

{osmfeatures-0.7.2 → osmfeatures-0.7.4}/README.md

@@ -11,6 +11,7 @@ Official Python client for the [MapLark OSM Features API](https://maplark.com) w
   - [Query OSM features](#query-osm-features)
   - [Query a large bbox](#query-a-large-bbox)
   - [Count](#count)
+  - [Density](#density)
   - [Async client](#async-client)
   - [Convenience helpers](#convenience-helpers)
   - [Usage](#usage)
@@ -102,7 +103,7 @@ with OSMFeaturesClient(api_key="sk-...") as client:
 
 ### Query OSM features
 
-`query()` calls `GET /v3/osm_features` and returns the whole tile. Omit `limit` for the API default. Paid keys may raise `limit` up to their `max_limit` (enterprise 1000000). A larger match set is truncated (`X-Has-More: true`). Pass `split_until_fit=True` to quarter the bbox until each piece fits. That adds latency. Pass `bbox_tiles=2` (or 4, 8, ...) to split the bbox up front. `query()` does not take `cursor`.
+`query()` calls `GET /v3/osm_features` and returns the whole tile. Omit `limit` for the API default. Paid keys may raise `limit` up to their `max_limit`. A larger match set is truncated (`X-Has-More: true`). Pass `auto_split=True` to read the key's `max_limit` from `GET /v1/account/tier`, count first with a scalar `GET /v2/osm_features/count` (no `group_by`), and jump to a power-of-2 tile grid when the match set exceeds that cap (one extra jump if a leftover leaf is still dense). That adds latency. Pass `bbox_tiles=2` (or 4, 8, ...) to split the bbox up front. `query()` does not take `cursor`.
 
 ```python
 fc = client.query(
@@ -125,7 +126,7 @@ Common filters:
 - `way_shape="polygon" | "line" | "all"` (omit = both shapes; `all` also means both)
 - `clip_geometry=True | False` (omit for the API default; set `False` to keep full geometry outside bbox)
 - `bbox_tiles=2` (power of 2) to split a bbox that exceeds your tier area cap
-- `split_until_fit=True` to split a bbox that exceeds `limit` (or the key's `max_limit`)
+- `auto_split=True` to count first, then fetch (reads `max_limit` from `GET /v1/account/tier`, cached on the client; jumps to a power-of-2 grid when the match set exceeds that cap; one extra jump if a leftover leaf is still dense; a lower `limit` truncates; jumps when a 400 names a bbox-area cap). Caps at 32 tiles (`OSMFeaturesTooManyTilesError` if covering the bbox needs more, `OSMFeaturesTooDenseError` if a tile still overflows). `OSMFeaturesTimeoutError` is only a real wall-clock miss.
 - `accept="text/csv"` / `"application/flatgeobuf"` / `"application/vnd.apache.parquet"` (returns `BinaryQueryResult`)
 
 
@@ -137,8 +138,7 @@ Use this to query a larger bbox than what is allowed by splitting the bbox up in
 all_restaurants = client.query(
     bbox="18.063,59.322,18.082,59.332",
     tags="amenity=restaurant",
-    split_until_fit=True,
-    max_features=1_000_000,
+    auto_split=True,
     timeout=60,
 )
 ```
@@ -148,7 +148,7 @@ all_restaurants = client.query(
 #### Count
 Analyze feature counts with a histogram over a very large area - city and country sized bounding boxes allowed. For example, you can find out how many cafes, bars, and restaurants are in different cities or countries.
 
-`client.count` calls `GET /v2/osm_features/count`. Example amenity histogram:
+`client.count` calls `GET /v2/osm_features/count`. Omit `group_by` for a scalar total. Example amenity histogram:
 
 ```python
 client.count(
@@ -162,6 +162,24 @@ client.count(
 ```
 
 
+#### Density
+
+`client.density` calls `GET /v2/osm_features/density`. Occupied grid bins come back as a GeoJSON FeatureCollection of points with `properties.count`, plus `total` and `truncated`. These are not OSM features (no `osm_id` or tags). Omit `cell_deg` for 0.1. `type` omitted is nodes. `tags` or `or_tags` is required. `limit` is the max occupied cells (the key's `max_limit` when omitted).
+
+A Europe box (`-26,33,52,72`, about 3042 deg²) fits the density area cap (4000 deg²) and the 80° span. It is above `max_units_per_request` on every non-enterprise tier, so pass `disable_budget_warning=True` to run it. The same box still 400s on count (area cap 400 deg²). A unit-cap 400 on count can use that flag the same way. A bbox-area 400 cannot.
+
+```python
+client.density(
+    bbox="-26,33,52,72",
+    tags=["place"],
+    cell_deg=0.1,
+    disable_budget_warning=True,
+)
+```
+
+CLI: `osmfeatures density --bbox -26,33,52,72 --tags place --cell-deg 0.1 --disable-budget-warning`.
+
+
 ### Async client
 
 Async methods mirror the sync API (`query_async`, `query_all_async`):
@@ -221,7 +239,7 @@ Results come back as summaries (ids, names, OSM tags, lon/lat scalars, `distance
 - Places: `places_search`, `places_nearby`, `places_details`
 - Geocode: `geocode` (Nominatim interim)
 - Routes: `routes_isochrone`, `routes_path`, `routes_optimized_path`
-- Generic OSM: `query`, `stats` (count/histogram)
+- Generic OSM: `query`, `count` (histogram / total), `density` (grid bins; `preview_map` the id)
 - Local (no HTTP): `nearest_within`, `pairs_within`, `filter_open`, `point_in_polygon`, `points_in_polygon`
 - Draw / export: `preview_map`, `export_geojson`
 
@@ -285,6 +303,7 @@ Planner rules: you pick tags, bbox or location+radius, budgets, `openNow`/`asOf`
 | "Cafes on a tour of Gamla Stan" | `places_search`, `filter_open` + `routes_optimized_path` (`loop=true`) |
 | "Suggest a walk to a bar, a restaurant, and a cafe, no particular order" | `routes_optimized_path` with `loop=false` |
 | "Is the office a 20-minute walk from the apartment?" | `routes_isochrone` from A, `point_in_polygon` for B |
+| "Amenity heatmap for Sweden" | `geocode` (bbox), `density` (`amenity`; `disable_budget_warning` if the unit cap 400s), `preview_map` |
 | "Show this on a map" | `preview_map(collection_id)` after a search or route |
 
 The same operations exist on `OSMFeaturesClient` when you are not going through an LLM (see [Places and routes](#places-and-routes)).
@@ -300,7 +319,16 @@ Runnable Python chains live in `tests/example_apps/test_geo_agent.py`. Full HTTP
 
 ### Places search
 
-`places_search()` finds places in a bounding box **or** a `location` plus `radius` (not both). Optional `tags` (AND) and `or_tags` (OR) use the same OSM filters as `query()`. Omit `limit` to use the API default (100, max 10_000).
+`places_search()` finds places in a bounding box **or** a `location` plus `radius` (not both). Optional `tags` (AND) and `or_tags` (OR) use the same OSM filters as `query()`. Omit `limit` to use the API default (100). Paid keys may raise `limit` up to their `/v3` `max_limit`; `asOf` / `openNow` still cap hours parse at 10_000.
+
+`bbox_tiles` and `auto_split` **only apply to bbox search** (same names as `query()`). Pass `bbox_tiles=2` (or 4, 8, ...) to split a bbox up front. Pass `auto_split=True` to count first via `GET /v2/osm_features/count` with `way_shape=polygon`, then fetch. No hours: split on `total` vs the key's `max_limit`. With `asOf` / `openNow`: AND `opening_hours`. An `asOf` page `limit` (default 100) truncates; density-split vs the 10k parse cap only when `limit` is raised above 10k. `openNow` density-splits vs that 10k scan cap even with a small fill limit. A search that exceeds the tagged **fetch** area cap 400s; that 400 is split in one jump from the limit in the message, not by probing every quarter, up to 32 tiles. A `count bbox area` 400 is not split (the window is still too big to count). location+radius is a circle and cannot split. To tile a radius window, convert it first with `around_to_bbox` (a square that contains the circle; corner hits can fall outside the original radius):
+
+```python
+from osmfeatures import around_to_bbox
+
+bbox = around_to_bbox(lon=18.075, lat=59.316, radius_m=800)
+cafes = client.places_search(bbox=bbox, or_tags=["amenity=cafe"], auto_split=True)
+```
 
 ```python
 cafes = client.places_search(
@@ -314,7 +342,7 @@ print(len(cafes["features"]), "open cafes")
 print(cafes["metadata"]["evaluated_at"])
 ```
 
-Response is a GeoJSON FeatureCollection plus `metadata.evaluated_at` (UTC instant used for hours).
+Response is a GeoJSON FeatureCollection plus `metadata.evaluated_at` (UTC instant used for hours) and `metadata.units` (credits charged). After `bbox_tiles` / `auto_split`, `units` is the sum of the search tiles.
 
 ### Nearby (ranked from a point)
 
@@ -332,7 +360,7 @@ for item in nearby["items"]:
     print(item["distance_m"], item["feature"]["id"])
 ```
 
-Response: `{status, items: [{feature, distance_m}], estimated_units, evaluated_at}`.
+Response: `{status, items: [{feature, distance_m}], units, evaluated_at}`.
 
 ### Place details
 
@@ -345,7 +373,7 @@ print(details["feature"]["properties"]["tags"])
 print(details["timezone"], details["evaluated_at"])
 ```
 
-Response: `{status, feature, estimated_units, evaluated_at, timezone}`. Hours are annotated at request time in the place's IANA zone (from its coordinates).
+Response: `{status, feature, units, evaluated_at, timezone}`. Hours are annotated at request time in the place's IANA zone (from its coordinates).
 
 ### Opening hours
 
@@ -456,6 +484,7 @@ The repository includes runnable example-app tests in `tests/example_apps/` show
 - `test_bike_path_dijkstra_liljeholmen_to_djurgarden.py`: tiled corridor bike routing from Liljeholmen to Djurgarden.
 - `test_geometry_filters.py`: zoom + area/length filters for large buildings and long roads.
 - `test_geo_agent.py`: Python places/routes chains (bar crawl, bike parks, isochrone filter/compare/coverage, client-side open-at-clock).
+- `test_auto_split.py`: ``auto_split`` for a city-scale cafe bbox (area cap) and dense inner-Stockholm buildings (``max_limit``).
 
 Run all example apps:
 

{osmfeatures-0.7.2 → osmfeatures-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "osmfeatures"
-version = "0.7.2"
+version = "0.7.4"
 description = "Official client for the MapLark OpenStreetMap Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV)"
 readme = "README.md"
 license = { text = "MIT" }

{osmfeatures-0.7.2 → osmfeatures-0.7.4}/src/osmfeatures/__init__.py

@@ -41,6 +41,7 @@ from .convenience import (
 )
 from .models import (
     BinaryQueryResult,
+    DensityFeatureCollection,
     OSMFeature,
     OSMFeatureCollection,
     OSMFeaturesAPIError,
@@ -49,6 +50,8 @@ from .models import (
     OSMFeaturesForbiddenError,
     OSMFeaturesRateLimitError,
     OSMFeaturesTimeoutError,
+    OSMFeaturesTooDenseError,
+    OSMFeaturesTooManyTilesError,
     ResponseMeta,
 )
 from .output import to_dataframe, to_geodataframe
@@ -63,6 +66,7 @@ __all__ = [
     # Models
     "OSMFeature",
     "OSMFeatureCollection",
+    "DensityFeatureCollection",
     "BinaryQueryResult",
     "ResponseMeta",
     # Exceptions
@@ -72,6 +76,8 @@ __all__ = [
     "OSMFeaturesRateLimitError",
     "OSMFeaturesAPIError",
     "OSMFeaturesTimeoutError",
+    "OSMFeaturesTooDenseError",
+    "OSMFeaturesTooManyTilesError",
     # Output
     "to_dataframe",
     "to_geodataframe",

{osmfeatures-0.7.2 → osmfeatures-0.7.4}/src/osmfeatures/_http.py

@@ -14,6 +14,7 @@ from .models import (
 )
 
 DEFAULT_BASE_URL = "https://api.maplark.com"
+ACCOUNT_TIER_PATH = "/v1/account/tier"
 GEOJSON_ACCEPT = "application/geo+json"
 DEFAULT_TIMEOUT = 60.0
 _LOG_BODY_MAX = 4000
@@ -126,7 +127,7 @@ def raise_for_response(resp: Any) -> None:
             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"),
+            units=body.get("units"),
             max_units_per_request=body.get("max_units_per_request"),
             retry_after=retry_after,
         )
@@ -184,7 +185,7 @@ def build_rate_limit_error(resp: Any) -> 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"),
+        units=body.get("units"),
         max_units_per_request=body.get("max_units_per_request"),
         retry_after=retry_after,
     )

osmfeatures-0.7.4/src/osmfeatures/_places.py

@@ -0,0 +1,192 @@
+"""Shared ``POST /v1/places/search`` tiling: bbox_tiles and auto_split.
+
+Sync and async clients pass their POST/count callables into
+:func:`execute_places_search`. ``bbox_tiles`` and ``auto_split`` are
+client-side; they are not sent in the JSON body. Both only apply to bbox
+search. location+radius is a circle (same as ``query`` radius) and cannot
+split; convert with :func:`around_to_bbox` and search that bbox if
+you need tiles.
+
+``auto_split`` uses the same count-first walk as :func:`execute_query`.
+Counts are ``GET /v2/osm_features/count`` with ``way_shape=polygon``.
+``asOf`` / ``openNow`` AND ``opening_hours``. An ``asOf`` page ``limit``
+truncates; density-split vs the 10k parse cap only when ``limit`` is
+raised above 10k. ``openNow`` always density-splits vs that 10k scan cap
+(the drain returns 200 at 10k hours-tagged rows).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from ._geo_agent import places_search_body
+from ._pagination import DEFAULT_QUERY_ALL_TIMEOUT_S
+from ._split import (
+    await_maybe,
+    fold_auto_split,
+    hours_parse_split_cap,
+    iter_split_tiles,
+    match_split_cap,
+    max_limit_from_tier,
+    run_sync,
+)
+from .chunking import merge_features
+
+BBOX_TILES_REQUIRES_BBOX = (
+    "bbox_tiles only applies to bbox search, not location+radius"
+)
+AUTO_SPLIT_REQUIRES_BBOX = (
+    "auto_split only applies to bbox search, not location+radius"
+)
+
+
+_SUM_META_KEYS = ("units", "input_count", "kept_count", "hours_parsed")
+
+
+def _merge_place_metadata(metas: list[dict[str, Any]]) -> dict[str, Any]:
+    """Sum billed/scan fields across tiles. Keep first ``evaluated_at``."""
+    out = dict(metas[0])
+    out.pop("hint", None)
+    for key in _SUM_META_KEYS:
+        total = 0
+        seen = False
+        for meta in metas:
+            value = meta.get(key)
+            if value is None:
+                continue
+            try:
+                total += int(value)
+            except (TypeError, ValueError):
+                continue
+            seen = True
+        if seen:
+            out[key] = total
+    if any(m.get("hours_parse_capped") for m in metas):
+        out["hours_parse_capped"] = True
+    return out
+
+
+def _merge_place_collections(payloads: list[dict[str, Any]]) -> dict[str, Any]:
+    if not payloads:
+        return {"type": "FeatureCollection", "features": []}
+    features = merge_features(
+        [list(p.get("features") or []) for p in payloads if isinstance(p, dict)]
+    )
+    out = dict(payloads[0]) if isinstance(payloads[0], dict) else {}
+    out["type"] = "FeatureCollection"
+    out["features"] = features
+    metas = [
+        p["metadata"]
+        for p in payloads
+        if isinstance(p, dict) and isinstance(p.get("metadata"), dict)
+    ]
+    if metas:
+        out["metadata"] = _merge_place_metadata(metas)
+    return out
+
+
+def _hours_on(open_now: bool, as_of: str | None) -> bool:
+    return bool(open_now or as_of is not None)
+
+
+async def execute_places_search(
+    *,
+    post: Callable[[dict[str, Any]], Any],
+    count: Callable[..., Any],
+    account_tier: Callable[..., Any] | None = None,
+    bbox: str | None = None,
+    location: dict[str, float] | None = None,
+    radius: float | None = None,
+    type: str | None = None,  # noqa: A002
+    tags: list[str] | None = None,
+    or_tags: list[str] | None = None,
+    limit: int | None = None,
+    open_now: bool = False,
+    as_of: str | None = None,
+    bbox_tiles: int = 1,
+    auto_split: bool = False,
+    split_until_fit: bool | None = None,
+    timeout: float | None = DEFAULT_QUERY_ALL_TIMEOUT_S,
+) -> dict[str, Any]:
+    """POST places/search, optionally tiling *bbox* like :func:`execute_query`."""
+    auto_split = fold_auto_split(auto_split, split_until_fit)
+    if bbox_tiles != 1 and not isinstance(bbox, str):
+        raise ValueError(BBOX_TILES_REQUIRES_BBOX)
+    if auto_split and not isinstance(bbox, str):
+        raise ValueError(AUTO_SPLIT_REQUIRES_BBOX)
+
+    def _body(*, tile: str | None = None) -> dict[str, Any]:
+        return places_search_body(
+            bbox=tile if tile is not None else bbox,
+            location=location,
+            radius=radius,
+            type=type,
+            tags=tags,
+            or_tags=or_tags,
+            limit=limit,
+            open_now=open_now,
+            as_of=as_of,
+        )
+
+    if bbox_tiles == 1 and not auto_split:
+        return await await_maybe(post(_body()))  # type: ignore[no-any-return]
+
+    assert isinstance(bbox, str)
+
+    count_kwargs: dict[str, Any] = {"way_shape": "polygon"}
+    if tags is not None:
+        count_kwargs["tags"] = list(tags)
+    if or_tags is not None:
+        count_kwargs["or_tags"] = list(or_tags)
+    hours_on = _hours_on(open_now, as_of)
+    if hours_on:
+        count_kwargs["tags"] = [*count_kwargs.get("tags", []), "opening_hours"]
+    omitted_cap = 1
+    if auto_split and not hours_on:
+        if account_tier is None:
+            raise TypeError("auto_split requires account_tier")
+        omitted_cap = max_limit_from_tier(await await_maybe(account_tier()))
+    tile_cap = (
+        hours_parse_split_cap(limit, open_now=open_now)
+        if hours_on
+        else match_split_cap(limit, omitted_cap)
+    )
+
+    async def _fetch_tile(tile: str) -> dict[str, Any]:
+        return await await_maybe(post(_body(tile=tile)))  # type: ignore[no-any-return]
+
+    async def _match_count(tile: str) -> int | None:
+        body = await await_maybe(count(bbox=tile, **count_kwargs))
+        return int(body["total"])
+
+    payloads: list[dict[str, Any]] = []
+    async for page in iter_split_tiles(
+        bbox,
+        bbox_tiles=bbox_tiles,
+        auto_split=auto_split,
+        timeout=timeout,
+        tile_cap=tile_cap,
+        match_count=_match_count if auto_split else None,
+        fetch_tile=_fetch_tile,
+        overflow_name="places_search",
+    ):
+        payloads.append(page)
+    return _merge_place_collections(payloads)
+
+
+def execute_places_search_sync(
+    *,
+    post: Callable[[dict[str, Any]], Any],
+    count: Callable[..., Any],
+    account_tier: Callable[..., Any] | None = None,
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """Run :func:`execute_places_search` on a private loop (or a worker if nested)."""
+    return run_sync(
+        execute_places_search,
+        post=post,
+        count=count,
+        account_tier=account_tier,
+        **kwargs,
+    )