osmfeatures 0.2.4 → 0.5.0

package/README.md

@@ -1,28 +1,42 @@
-# OSM Features API client
+# TypeScript OSM Features client
 
-Official client for the [MapLark OSM Features API](https://maplark.com) to get GeoJSON, FlatGeobuf, GeoParquet, or CSV from OpenStreetMap. The API gets data from dedicated postgis OSM servers separate from public Overpass.
+npm package for the [MapLark OSM Features API](https://maplark.com). Fetch OpenStreetMap buildings, roads, parks, and POIs as GeoJSON, FlatGeobuf, GeoParquet, or CSV from Node.js or the browser without standing up Overpass or converting extracts by hand. Simply search by tag and bounding box or location + radius. The API keeps OSM semantics intact, like node, way, relation, and returns GeoJSON Features you can feed straight into Leaflet, MapLibre, OpenLayers, or any geospatial toolchain. Use this lib to build geospatial apps on OSM easily without hitting rate limits or setting up complex and expensive infrastructure yourself.
 
-Query OpenStreetMap features such as buildings, streets, and POIs easily. Search for OSM features by bounding box, tags, and geometry shape and get GeoJSON back within less than 250ms (dependent on query size). No converting between formats manually. The API keeps OSM semantics intact, like tags and ways, and returns OSM features you can feed straight into Leaflet, MapLibre, OpenLayers, or any geospatial toolchain. It is backed by postgis with tiered API keys and rate limiting to keep noisy neighbours out to give you low, predictable latency for real traffic. It also has a self-host path for those willing to host complex infrastructure themselves, and Geo Agent methods for places search, opening hours, and walk or bike routing.
+The backend is dedicated PostGIS, not the public Overpass endpoint, with API keys and rate limits so map tiles and POI queries stay fast under load. This SDK also covers local-search and mobility: amenity lookup, OSM opening hours, and walk or bicycle routing.
 
-The translation layer is very simple:
+## Contents
 
-- `node` - GIS Point
-- `way` - LineString or Polygon
-- `relation` - MultiPolygon or grouped geometries
+- [Quick start](#quick-start)
+- [Functions and Parameters](#functions-and-parameters)
+  - [query()](#query)
+  - [query_all](#query_all)
+  - [stats](#stats)
+  - [estimate_cost](#estimate_cost)
+  - [usage](#usage)
+- [Places and routes](#places-and-routes)
+  - [Places search](#places-search)
+  - [Nearby](#nearby-ranked-from-a-point)
+  - [Place details](#place-details)
+  - [Opening hours](#opening-hours)
+  - [X near Y](#x-near-y-local-join)
+  - [Walk and bike routes](#walk-and-bike-routes)
+- [MCP server](#mcp-server)
 
-You filter with the same tags mappers already use (`amenity=cafe`, `building=yes`, and so on). Knowledge from OSM, Overpass, and tagging docs transfers immediately.
+OSM types map to GeoJSON the way GIS tools expect:
 
-To narrow down between "open ways" and "closed ways", use the `way_shape` parameter:
+- `node` → Point
+- `way` → LineString or Polygon
+- `relation` → MultiPolygon or a bundle of geometries
 
-- `way_shape=line` - open ways (roads, paths, rivers) or line-shaped relations (routes, boundaries)
-- `way_shape=polygon` - closed ways (buildings, parks) or multipolygon relations.
-- `way_shape=all` - both shapes (default when way_shape is omitted).
+Filters use ordinary OSM tags (`amenity=cafe`, `building=yes`). If you already write Overpass or edit OSM, the same keys work here. Drop a FeatureCollection into Leaflet, MapLibre, OpenLayers, or Turf.
 
-For example, to get all buildings in an area:
+Use `way_shape` when you need lines vs areas:
 
-`type=way & tags=building`
+- `way_shape=line` — unclosed ways (streets, footpaths, rivers) and line-like relations (routes, some boundaries)
+- `way_shape=polygon` — closed ways (building footprints, parks) and multipolygon relations
+- `way_shape=all` — both (the default if you leave it off)
 
-This is the equivalent of the Overpass query `way[building]`.
+Buildings in a box: `type=way & tags=building` — the same idea as Overpass `way[building]`.
 
 # Quick start
 
@@ -75,6 +89,7 @@ The geographical area for the request in terms of GPS coordinates or specific OS
 | `bbox`   | `string` | Bounding box as `min_lon,min_lat,max_lon,max_lat`. |
 | `location` | `string` | Point for a radius search as `lat,lng`. Requires `radius`. |
 | `radius` | `number` | Search radius in metres. Requires `location`. |
+| `within` | `string` | Polygon spatial anchor as `way/<id>` or `relation/<id>`. Mutually exclusive with `bbox` / `location`. |
 | `osmIds` | `string` | Comma-separated OSM IDs to fetch by id.            |
 
 
@@ -121,7 +136,7 @@ Extra filters to for pagination, output format (accept),
 | Param                  | Type      | Default                | Description                                                                                                                                                               |
 | ---------------------- | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `accept`               | `string`  | `application/geo+json` | Response media type in header. Options - `application/geo+json`, `text/csv`, `text/tab-separated-values`, `application/flatgeobuf`, and `application/vnd.apache.parquet`. |
-| `limit`                | `number`  | `1000`                 | Page size. Max `6000`.                                                                                                                                                    |
+| `limit`                | `number`  | API `1000`             | Page size. Omit to use the API default. Max `6000`.                                                                                                       |
 | `cursor`               | `string`  |                        | Pagination cursor from a previous `meta.next_cursor`.                                                                                                                     |
 | `disableBudgetWarning` | `boolean` | `false`                | Ignore warnings for large queries that consume budget quotas.                                                                                                             |
 | `zoom`                 | `number`  |                        | Map zoom hint (used by presets / server-side simplification policies).                                                                                                    |
@@ -148,7 +163,7 @@ Fields for pagination and usage.
 
 Auto-paginates (and optionally tiles the bbox) until the result is complete or a client-side cap is hit. GeoJSON only — for FlatGeobuf / other encodings, use `query` with `accept`.
 
-Does not take `limit` or `cursor`; paging is handled internally.
+Does not take `limit` or `cursor`; paging is handled internally. Does not tile when `within` is set (`bboxTiles` is ignored).
 
 ```ts
 const all = await client.query_all({
@@ -168,12 +183,12 @@ console.log(all.meta.page_count, all.meta.has_more, all.meta.units_charged);
 
 ### Params
 
-Same filter params as `query` (`bbox`, `tags`, `orTags`, `notTags`, `type`, `wayShape`, `zoom`, `location`, `radius`, `osmIds`, `minLengthM`, `maxLengthM`, `minAreaM2`, `maxAreaM2`, `centroid`, `clipGeometry`, `disableBudgetWarning`), plus:
+Same filter params as `query` (`bbox`, `tags`, `orTags`, `notTags`, `type`, `wayShape`, `zoom`, `location`, `radius`, `within`, `osmIds`, `minLengthM`, `maxLengthM`, `minAreaM2`, `maxAreaM2`, `centroid`, `clipGeometry`, `disableBudgetWarning`), plus:
 
 
 | Param          | Type            | Default                | Description                                                                                                                                               |
 | -------------- | --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `limitPerPage` | `number`        | `1000`                 | Upstream `limit` per HTTP request (page size).                                                                                                            |
+| `limitPerPage` | `number`        | API `1000`             | Upstream `limit` per HTTP request (page size). Omit to use the API default.                                                                               |
 | `bboxTiles`    | `number`        | `2`                    | Split `bbox` into this many tiles (must be a power of 2: `1`, `2`, `4`, `8`, …). Each tile is paginated separately, then features are merged and deduped. |
 | `maxPages`     | `number`        | `15`                   | Max pages fetched **per tile**.                                                                                                                           |
 | `maxFeatures`  | `number | null` | `55000`                | Cap on merged features after dedupe. Pass `null` for no cap.                                                                                              |
@@ -197,8 +212,33 @@ Same fields as `query`, plus:
 | `relay_partial_reason` | e.g. `upstream_rejected_cursor` or `upstream_rate_limited_after_retries`.            |
 
 
-Also exports layer presets (`resolveLayerFromQuery`, `OSM_FEATURES_LAYER_PRESETS`, ...)
-and GeoJSON payload helpers (`featureCentroid`, `geometryBounds`, `parseFeatureId`, ...).
+Also exports layer presets (`resolveLayerFromQuery`, `OSM_FEATURES_LAYER_PRESETS`, ...),
+GeoJSON payload helpers (`featureCentroid`, `geometryBounds`, `parseFeatureId`, ...),
+and local helpers (`nearest_within`, `point_in_geometry`, `isOpenNow`).
+
+## `stats`
+
+Count features grouped by a tag key via `GET /v2/osm_features/stats`. Returns `{ groups, total, truncated }`. Spatial windows are larger than `query` (country-scale on every tier) and billed count-only. `limit` is max histogram buckets (API default 100), not a scan cap. `groupBy` is required. Same tag filters as `query`; no `osmIds`, `cursor`, `zoom`, `centroid`, or `clipGeometry`. Map Express/query strings with `resolveStatsRequest` (requires `group_by`).
+
+```ts
+const histogram = await client.stats({
+  groupBy: 'amenity',
+  bbox: '18.05,59.32,18.10,59.34',
+  type: 'node',
+  tags: ['amenity'],
+});
+console.log(histogram.total, histogram.groups);
+```
+
+City boundary:
+
+```ts
+const mix = await client.stats({
+  groupBy: 'amenity',
+  within: 'relation/398021',
+  tags: ['amenity'],
+});
+```
 
 ## `estimate_cost`
 
@@ -221,37 +261,15 @@ const usage = await client.usage();
 console.log(usage.tier, usage.usage_this_month, usage.remaining_this_month);
 ```
 
-## Geo Agent (places and routes)
-
-`query()` is the generic OpenStreetMap layer: buildings, roads, park polygons, any tag and geometry shape. Geo Agent is the place and mobility layer on top of the same OSM data. You pick OSM tags (`amenity=cafe`), an area, a time, and walk or bike. The API returns coordinates, opening-hours status, nearest-first ranks, and walk or bike geometry.
-
-These endpoints answer questions like "cafes near me", "bars open at 20:00", or "suggest a walking bar crawl in Stockholm". An AI agent or a script can call the same methods.
+## Places and routes
 
-| Endpoint | HTTP | What it does |
-| -------- | ---- | ------------ |
-| `places_search` | `POST /v1/places/search` | Find places in a bounding box **or** a `location` plus `radius`. Filter with OSM tags. Optional `openNow` / `asOf` for opening hours. |
-| `places_nearby` | `POST /v1/places/nearby` | "X near this point". Same tags and hours filters, ranked nearest-first by straight-line distance. |
-| `places_details` | `GET /v1/places/{osm_type}/{osm_id}` | Reload one place by the id search or nearby returned (`node/123`). |
-| `routes_isochrone` | `POST /v1/routes/isochrone` | Walk or bike reach polygon from an origin (how far you can get in N metres or seconds). |
-| `routes_path` | `POST /v1/routes/path` | Walk or bike through stops in the order you list them. No reordering. |
-| `routes_optimized_path` | `POST /v1/routes/optimized_path` | Order the stops for you (a tour from `start`). `loop` (default true) returns to start. |
+`query()` is the raw OSM layer: footprints, highways, park polygons, any tag and geometry class. Places and routes sit on the same planet extract but answer product questions: amenities in a box, ranked POIs from a pin, opening hours, walk/bike isochrones, and multi-stop paths. You supply tags, extent, time, and `WALK` or `BICYCLE`. The API returns coordinates, `openNow`, distances, and network geometry.
 
-Search and nearby hours use each place's local timezone. Optional `asOf` pins the evaluation instant. Routing is walk or bicycle on the OSM network (`travelMode`: `WALK` or `BICYCLE`). Car routing is not available yet.
+Unset fields are omitted so server defaults apply (`places_search` limit 100, `places_nearby` radius 1000 m and limit 100, `loop` true). HTTP docs: [maplark.com/developer](https://maplark.com/developer).
 
-#### Typical questions
+### Places search
 
-| Prompt | SDK |
-|------|-----|
-| "Cafes near me" | `client.places_nearby()` or `client.places_search()` with `location` + `radius` |
-| "Restaurants within 150 m of a station" | two `client.places_search()` calls, then join locally by distance |
-| "Bars open at 20:00" | `client.places_search()` with `asOf`, keep `openingHours.status == "open"` |
-| "Cafes within a 10-minute bike ride" | `client.routes_isochrone()` + `client.places_search()` in a covering radius + keep points inside the polygon |
-| "A walking bar crawl in Stockholm" | `client.places_search()` + `client.routes_optimized_path()` (`loop: true`) |
-| "Walk from my hotel to the cafe, then the office" | `client.routes_path()` with those stops in listed order |
-| "Suggest a walk to a bar, a restaurant, and a cafe, no particular order" | `client.routes_optimized_path()` with `loop: false` |
-| "Is the office a 20-minute walk from the apartment?" | `client.routes_isochrone()` from A, point-in-polygon for B |
-
-### Examples for `places_search` / `places_nearby` / `places_details`
+`places_search()` looks up POIs inside a bounding box **or** around `{ lat, lon }` + `radius` (pick one). `tags` is AND; `orTags` is OR; both use the same OSM keys as `query()`. Leave `limit` off for the API default (100, max 10_000).
 
 ```ts
 const origin = { lat: 59.316, lon: 18.075 };
@@ -263,7 +281,13 @@ const cafes = await client.places_search({
   openNow: true,
   asOf: '2026-08-10T18:00:00+02:00',
 });
+```
 
+### Nearby (ranked from a point)
+
+`places_nearby()` is “what is closest to this coordinate?”. You must pass `tags` or `orTags`. Hits are ordered by straight-line spheroid distance. Defaults if omitted: 1000 m radius, 100 results.
+
+```ts
 const nearby = await client.places_nearby({
   location: origin,
   orTags: ['amenity=cafe'],
@@ -271,16 +295,55 @@ const nearby = await client.places_nearby({
   openNow: true,
   asOf: '2026-08-10T18:00:00+02:00',
 });
+```
+
+### Place details
 
+`places_details()` reloads a single OSM place by the id search or nearby gave you (`node/123`), or as `{ osmType, osmId }`.
+
+```ts
 const first = (cafes.features as { id: string }[])[0];
 const details = await client.places_details({ osmType: first.id });
+// same as: client.places_details({ osmType: 'node', osmId: 123 })
+```
+
+Hours are evaluated at request time in that place’s timezone.
+
+### Opening hours
+
+When OSM `opening_hours` can be parsed, the feature gets `properties.openNow` as `true` or `false`. Missing or junk hours omit the field. `isOpenNow(feature)` keeps known-open places and unwraps the details `{ feature }` envelope.
+
+Timezone is inferred from coordinates (IANA). There is no `timezone` request field.
+
+- `openNow: true` drops closed and unknown-hours POIs (Google Places–style `openNow`).
+- `asOf` is the evaluation instant (default: now). An offset (`Z`, `+02:00`) is an absolute instant. A naive `2026-08-10T20:00:00` is local clock at the search point or bbox centre.
+- `asOf` or `openNow` also require an `opening_hours` tag, so untagged amenities do not pad the page.
+- Places that are closed but tagged still appear unless `openNow` is set.
+
+### "X near Y" (local join)
+
+`places_nearby` ranks against one origin. “Restaurants within 150 m of a station” is two searches plus an in-process join. `nearest_within` does not hit the API.
+
+```ts
+import { nearest_within } from 'osmfeatures';
+
+const bbox = '18.05,59.33,18.10,59.36';
+const restaurants = await client.places_search({ bbox, orTags: ['amenity=restaurant'] });
+const stations = await client.places_search({ bbox, orTags: ['railway=station'] });
+const pairs = nearest_within(restaurants, stations, 150, { limit: 20 });
+
+for (const pair of pairs) {
+  console.log(pair.distance_m, pair.feature, 'near', pair.nearest);
+}
 ```
 
-`places_details` also accepts `{ osmType: 'node', osmId: 123 }`. Hours are annotated at request time in the place's local timezone.
+Each pair is `{ feature, distance_m, nearest }`. The point is `geometry` when it is a Point, otherwise `properties.centroid` (same as `featureCentroid`). Neither present throws. Empty secondary → `[]`. Distances are spherical haversine (mean Earth radius 6371000 m). `limit` keeps the closest pairs (default 20); `{ limit: null }` returns every primary with a match. More than 500000 comparisons throws — lower `places_search` / `places_nearby` `limit`, do not use `query_all`. `{ data, meta }` from `query()` / `query_all()` is accepted.
+
+### Walk and bike routes
 
-### Examples for `routes_isochrone` / `routes_path` / `routes_optimized_path`
+Paths follow OSM walk and bicycle ways. Default `travelMode` is `WALK`; pass `'BICYCLE'` for bikes. Driving is not offered yet.
 
-Points accept `lon` or `lng`. `routes_isochrone` takes exactly one of `maxDistanceM` or `durationS`. Optional `searchBufferM` widens the highway fetch corridor.
+Coordinates take `lon` or `lng`. For `routes_isochrone`, set exactly one of `maxDistanceM` or `durationS`. `searchBufferM` widens the highway fetch if the default corridor cannot form a path.
 
 ```ts
 const origin = { lon: 18.075, lat: 59.316 };
@@ -299,6 +362,15 @@ const tour = await client.routes_optimized_path({
   start: origin,
   stops: [cafe],
 });
+
+const office = { lon: 18.08, lat: 59.318 };
+point_in_geometry(office.lon, office.lat, iso);
 ```
 
-Read the full API reference here [https://maplark.com/developer](https://maplark.com/developer) such as the OpenAPI 2.0 HTTP docs.
+In-process (no HTTP): `nearest_within(primary, secondary, maxDistanceM)` for proximity joins, `point_in_geometry(lon, lat, geom)` for isochrone containment. The latter accepts a Polygon/MultiPolygon, a Feature, a GeometryCollection, or `{ geometry }` from the isochrone response.
+
+
+## MCP server
+
+Maplark has an MCP server to integrate OpenStreetMap data into AI and LLMs such as Claude, Cursor, and Copilot. However, it is implemented in another Python sister repo. See [maplark.com/products/mcp-server](https://maplark.com/products/mcp-server) for more details.
+

package/dist/geojson-feature.js

@@ -42,6 +42,15 @@ export function readTags(properties) {
     }
     return {};
 }
+function finiteLonLat(lon, lat) {
+    if (typeof lon !== 'number' || typeof lat !== 'number') {
+        return null;
+    }
+    if (!Number.isFinite(lon) || !Number.isFinite(lat)) {
+        return null;
+    }
+    return [lon, lat];
+}
 function collectPositions(coordinates, out) {
     if (!Array.isArray(coordinates) || coordinates.length === 0) {
         return;
@@ -86,22 +95,20 @@ export function featureCentroid(feature) {
     const group = geometryGroup(feature.geometry?.type?.trim() ?? '');
     if (group === 'points') {
         const coords = feature.geometry?.coordinates;
-        if (feature.geometry?.type === 'Point' && Array.isArray(coords) && typeof coords[0] === 'number') {
-            return [coords[0], coords[1]];
+        if (feature.geometry?.type === 'Point' && Array.isArray(coords)) {
+            return finiteLonLat(coords[0], coords[1]);
         }
         if (feature.geometry?.type === 'MultiPoint' && Array.isArray(coords) && coords.length === 1) {
             const point = coords[0];
-            if (typeof point?.[0] === 'number') {
-                return [point[0], point[1]];
-            }
+            return finiteLonLat(point?.[0], point?.[1]);
         }
         return null;
     }
     const centroid = feature.properties?.['centroid'];
     if (centroid && typeof centroid === 'object' && !Array.isArray(centroid)) {
         const coords = centroid.coordinates;
-        if (Array.isArray(coords) && typeof coords[0] === 'number' && typeof coords[1] === 'number') {
-            return [coords[0], coords[1]];
+        if (Array.isArray(coords)) {
+            return finiteLonLat(coords[0], coords[1]);
         }
     }
     return null;

package/dist/geometry.d.ts

@@ -0,0 +1,12 @@
+/** Local geometry helpers. No HTTP. The planner must not invent containment. */
+export type GeometryLike = {
+    type?: string;
+    coordinates?: unknown;
+    geometries?: unknown;
+    geometry?: GeometryLike | null;
+};
+/**
+ * Point-in-polygon for GeoJSON Polygon/MultiPolygon, including holes.
+ * Also accepts a Feature, GeometryCollection, or `{ geometry }` (isochrone body).
+ */
+export declare function point_in_geometry(lon: number, lat: number, geom: unknown): boolean;

package/dist/geometry.js

@@ -0,0 +1,60 @@
+/** Local geometry helpers. No HTTP. The planner must not invent containment. */
+function pointInRing(lon, lat, ring) {
+    let inside = false;
+    const n = ring.length;
+    for (let i = 0; i < n; i += 1) {
+        const x1 = ring[i][0];
+        const y1 = ring[i][1];
+        const next = ring[(i + 1) % n];
+        const x2 = next[0];
+        const y2 = next[1];
+        if ((y1 > lat) !== (y2 > lat)) {
+            const xAtLat = x1 + ((lat - y1) * (x2 - x1)) / (y2 - y1);
+            if (lon < xAtLat) {
+                inside = !inside;
+            }
+        }
+    }
+    return inside;
+}
+function pointInPolygonRings(lon, lat, rings) {
+    let inside = false;
+    for (const ring of rings) {
+        if (Array.isArray(ring) && ring.length > 0 && pointInRing(lon, lat, ring)) {
+            inside = !inside;
+        }
+    }
+    return inside;
+}
+function pointInUnknown(lon, lat, geom, depth) {
+    if (geom == null || typeof geom !== 'object' || depth > 4) {
+        return false;
+    }
+    const g = geom;
+    const gtype = g.type;
+    if (gtype === 'Polygon') {
+        const coords = g.coordinates;
+        return Array.isArray(coords) && pointInPolygonRings(lon, lat, coords);
+    }
+    if (gtype === 'MultiPolygon') {
+        const coords = g.coordinates;
+        return Array.isArray(coords)
+            && coords.some((poly) => Array.isArray(poly) && poly.length > 0
+                && pointInPolygonRings(lon, lat, poly));
+    }
+    if (gtype === 'GeometryCollection') {
+        const parts = g.geometries;
+        return Array.isArray(parts) && parts.some((part) => pointInUnknown(lon, lat, part, depth + 1));
+    }
+    if (gtype === 'Feature' || (gtype == null && g.geometry != null)) {
+        return pointInUnknown(lon, lat, g.geometry, depth + 1);
+    }
+    return false;
+}
+/**
+ * Point-in-polygon for GeoJSON Polygon/MultiPolygon, including holes.
+ * Also accepts a Feature, GeometryCollection, or `{ geometry }` (isochrone body).
+ */
+export function point_in_geometry(lon, lat, geom) {
+    return pointInUnknown(lon, lat, geom, 0);
+}

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export type OSMFeaturesLayer = {
 };
 /** Flat query params (same idea as Python `query(**params)`). */
 export type OSMFeaturesParams = OSMFeaturesLayer & {
+    /** Page size. Omit to use the API default (1000). Max `6000`. */
     limit?: number;
     cursor?: string;
     zoom?: number;
@@ -45,18 +46,53 @@ export type OSMFeaturesParams = OSMFeaturesLayer & {
     location?: string;
     /** Search radius in metres. Requires `location`. */
     radius?: number;
+    /** Polygon spatial anchor as `way/<id>` or `relation/<id>`. Mutually exclusive with `bbox` / `location`. */
+    within?: string;
     osmIds?: string;
     minLengthM?: number;
     maxLengthM?: number;
     minAreaM2?: number;
     maxAreaM2?: number;
     disableBudgetWarning?: boolean;
+    /** When true, include `properties.centroid` on non-point features. Omit for the API default (false). */
     centroid?: boolean;
-    /** When true (default), clip returned geometry to the requested bbox. */
+    /** When true, clip returned geometry to the requested bbox. Omit for the API default (false). */
     clipGeometry?: boolean;
     /** Accept media type. Default application/geo+json; other types put bytes in ``data``. */
     accept?: string;
 };
+/** `GET /v2/osm_features/stats`. Same filters as `query` except paging/geometry extras. */
+export type OSMFeaturesStatsParams = {
+    /** Tag key to group on (required). Features without this key are not counted. */
+    groupBy: string;
+    bbox?: string;
+    location?: string;
+    radius?: number;
+    within?: string;
+    type?: string;
+    wayShape?: 'line' | 'polygon' | 'all';
+    /** @deprecated Use `wayShape`. */
+    shape?: 'line' | 'polygon' | 'all';
+    tags?: string[];
+    orTags?: string[];
+    notTags?: string[];
+    /** Max histogram buckets (API default 100, max 10000). Does not cap the scan. */
+    limit?: number;
+    minLengthM?: number;
+    maxLengthM?: number;
+    minAreaM2?: number;
+    maxAreaM2?: number;
+    disableBudgetWarning?: boolean;
+};
+export type OSMStatsGroup = {
+    value: string;
+    count: number;
+};
+export type OSMStatsResponse = {
+    groups: OSMStatsGroup[];
+    total: number;
+    truncated: boolean;
+};
 type QueryValue = unknown;
 export type OSMFeaturesQuery = Record<string, QueryValue>;
 /** Routing point. Accepts ``lon`` or ``lng``. */
@@ -95,6 +131,7 @@ export type PlacesSearchParams = {
     tags?: string[];
     orTags?: string[];
     limit?: number;
+    /** Keep only places known open at ``asOf`` (or now). Untagged hours are dropped. */
     openNow?: boolean;
     asOf?: string;
 };
@@ -105,9 +142,29 @@ export type PlacesNearbyParams = {
     tags?: string[];
     orTags?: string[];
     limit?: number;
+    /** Keep only places known open at ``asOf`` (or now). Untagged hours are dropped. */
     openNow?: boolean;
     asOf?: string;
 };
+/**
+ * Place GeoJSON ``properties`` from search / nearby / details.
+ * ``openNow`` is true/false when hours are evaluable at ``asOf`` (or now);
+ * omitted when missing or unparseable.
+ */
+export type PlaceProperties = {
+    tags?: Record<string, unknown>;
+    openNow?: boolean;
+    centroid?: unknown;
+};
+export type PlaceFeatureLike = {
+    properties?: PlaceProperties | Record<string, unknown>;
+    /** ``places_details`` envelope: ``{ status, feature }``. */
+    feature?: PlaceFeatureLike;
+};
+/** ``properties.openNow === true`` (known open). Missing / non-boolean is not open. Unwraps ``{ feature }``. */
+export declare function isOpenNow(feature: PlaceFeatureLike | undefined): boolean;
+/** ``true`` / ``false`` when hours are known; ``undefined`` when the field is omitted. Unwraps ``{ feature }``. */
+export declare function readOpenNow(feature: PlaceFeatureLike | undefined): boolean | undefined;
 export type PlacesDetailsParams = {
     /** ``node`` / ``way`` / ``relation``, or a full ``node/123`` feature id. */
     osmType: string;
@@ -138,6 +195,8 @@ export declare class OSMFeatures {
     });
     /** Map Express/query params + resolved layer into flat `query` / `query_all` params. */
     resolveRequest(query: OSMFeaturesQuery, layer: OSMFeaturesLayer): OSMFeaturesParams;
+    /** Map Express/query params into `stats` params. `group_by` is required. */
+    resolveStatsRequest(query: OSMFeaturesQuery | URLSearchParams): OSMFeaturesStatsParams;
     private throwUpstreamError;
     /** GET/POST with 429 retry. Throws on non-OK. */
     private _fetchOk;
@@ -148,25 +207,27 @@ export declare class OSMFeatures {
     /** Single HTTP request with retry. Throws on non-OK (same role as Python `_raw_query`). */
     private _rawQuery;
     /** Single upstream page. Params map 1:1 to server query string (no tiling). */
-    query({ bbox, tags, orTags, notTags, type, wayShape, shape, limit, cursor, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }: OSMFeaturesParams, dependencies?: OSMFeaturesDependencies): Promise<OSMFeaturesResult>;
+    query({ bbox, tags, orTags, notTags, type, wayShape, shape, limit, cursor, zoom, location, radius, within, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }: OSMFeaturesParams, dependencies?: OSMFeaturesDependencies): Promise<OSMFeaturesResult>;
     /** Auto-paginate (and optionally tile) until complete. Each page uses `_rawQuery`. */
-    query_all({ bbox, tags, orTags, notTags, type, wayShape, shape, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage, bboxTiles, maxPages, maxFeatures, }: Omit<OSMFeaturesParams, 'limit' | 'cursor'> & {
-        /** Upstream `limit` per HTTP request (page size). */
+    query_all({ bbox, tags, orTags, notTags, type, wayShape, shape, zoom, location, radius, within, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage, bboxTiles, maxPages, maxFeatures, }: Omit<OSMFeaturesParams, 'limit' | 'cursor'> & {
+        /** Upstream `limit` per HTTP request (page size). Omit to use the API default (1000). */
         limitPerPage?: number;
         bboxTiles?: number;
         maxPages?: number;
         /** Cap on merged features. `null` = no cap. */
         maxFeatures?: number | null;
     }, dependencies?: OSMFeaturesDependencies): Promise<OSMGeoJSONResult>;
+    /** Count features grouped by a tag key (``GET /v2/osm_features/stats``). */
+    stats(params: OSMFeaturesStatsParams, dependencies?: OSMFeaturesDependencies): Promise<OSMStatsResponse>;
     /** Preflight credit cost (``GET /v2/osm_features/cost``). */
     estimate_cost(params?: OSMFeaturesParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
     /** This month's unit-budget usage (``GET /v1/usage``). */
     usage(dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
-    /** Find places in a bbox or radius (``POST /v1/places/search``). */
+    /** Find places in a bbox or radius (``POST /v1/places/search``). Features have ``properties.openNow`` when hours are known. */
     places_search(params: PlacesSearchParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
-    /** Nearest places from a point (``POST /v1/places/nearby``). */
+    /** Nearest places from a point (``POST /v1/places/nearby``). Features have ``properties.openNow`` when hours are known. */
     places_nearby(params: PlacesNearbyParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
-    /** One place by OSM id (``GET /v1/places/{osm_type}/{osm_id}``). */
+    /** One place by OSM id (``GET /v1/places/{osm_type}/{osm_id}``). Feature has ``properties.openNow`` when hours are known. */
     places_details(params: PlacesDetailsParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
     /** Reach polygon along the walk/bike network (``POST /v1/routes/isochrone``). */
     routes_isochrone(params: RoutesIsochroneParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
@@ -176,4 +237,6 @@ export declare class OSMFeatures {
     routes_optimized_path(params: RoutesOptimizedPathParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
 }
 export * from './geojson-feature.js';
+export * from './geometry.js';
+export * from './nearest.js';
 export * from './preset/index.js';

package/dist/index.js

@@ -21,9 +21,30 @@ function metaFromHeaders(headers, featureCount) {
     }
     return meta;
 }
+function openNowValue(feature) {
+    if (feature == null) {
+        return undefined;
+    }
+    const props = feature.properties;
+    if (props && typeof props === 'object' && 'openNow' in props) {
+        return props['openNow'];
+    }
+    if (feature.feature != null && feature.feature !== feature) {
+        return openNowValue(feature.feature);
+    }
+    return undefined;
+}
+/** ``properties.openNow === true`` (known open). Missing / non-boolean is not open. Unwraps ``{ feature }``. */
+export function isOpenNow(feature) {
+    return openNowValue(feature) === true;
+}
+/** ``true`` / ``false`` when hours are known; ``undefined`` when the field is omitted. Unwraps ``{ feature }``. */
+export function readOpenNow(feature) {
+    const value = openNowValue(feature);
+    return typeof value === 'boolean' ? value : undefined;
+}
 const PLACE_TYPES = new Set(['node', 'way', 'relation']);
 const DEFAULT_BASE_URL = 'https://api.maplark.com';
-const DEFAULT_LIMIT = 1000;
 const MAX_LIMIT = 6000;
 const GEOJSON_ACCEPT = 'application/geo+json';
 function isGeojsonAccept(accept) {
@@ -88,14 +109,43 @@ function optionalBoolean(query, key) {
     }
     return undefined;
 }
-function parseLimit(query, fallback = DEFAULT_LIMIT) {
+function stringList(query, key) {
+    const raw = query[key];
+    if (raw == null || raw === '') {
+        return [];
+    }
+    const values = Array.isArray(raw) ? raw : [raw];
+    const out = [];
+    for (const value of values) {
+        if (value == null || value === '') {
+            continue;
+        }
+        const trimmed = String(value).trim();
+        if (trimmed) {
+            out.push(trimmed);
+        }
+    }
+    return out;
+}
+function queryFromSearchParams(params) {
+    const out = {};
+    for (const key of new Set(params.keys())) {
+        const all = params.getAll(key);
+        out[key] = all.length <= 1 ? (all[0] ?? '') : all;
+    }
+    return out;
+}
+function asQueryMap(query) {
+    return query instanceof URLSearchParams ? queryFromSearchParams(query) : query;
+}
+function parseLimit(query) {
     const raw = optionalString(query, 'limit');
     if (raw == null) {
-        return fallback;
+        return undefined;
     }
     const parsed = Number.parseInt(raw, 10);
     if (!Number.isFinite(parsed)) {
-        return fallback;
+        return undefined;
     }
     if (parsed > MAX_LIMIT) {
         throw appError(400, 'invalid_limit', `limit must be <= ${MAX_LIMIT}.`);
@@ -149,7 +199,9 @@ function buildFeaturesQuery(params) {
     if (params.bbox) {
         query.set('bbox', params.bbox);
     }
-    query.set('limit', String(params.limit));
+    if (params.limit != null) {
+        query.set('limit', String(params.limit));
+    }
     if (params.cursor) {
         query.set('cursor', params.cursor);
     }
@@ -162,6 +214,12 @@ function buildFeaturesQuery(params) {
     if (params.radius != null) {
         query.set('radius', String(params.radius));
     }
+    if (params.within) {
+        query.set('within', params.within);
+    }
+    if (params.groupBy) {
+        query.set('group_by', params.groupBy);
+    }
     if (params.osmIds) {
         query.set('osm_ids', params.osmIds);
     }
@@ -177,10 +235,10 @@ function buildFeaturesQuery(params) {
     if (params.maxAreaM2 != null) {
         query.set('max_area_m2', String(params.maxAreaM2));
     }
-    if (params.disableBudgetWarning != null) {
+    if (params.disableBudgetWarning) {
         query.set('disable_budget_warning', String(params.disableBudgetWarning));
     }
-    if (params.centroid != null) {
+    if (params.centroid) {
         query.set('centroid', String(params.centroid));
     }
     if (params.clipGeometry != null) {
@@ -232,7 +290,7 @@ function parsePlaceRef(osmType, osmId) {
     return { osmType: kind, osmId: n };
 }
 function placesSearchBody(params) {
-    const body = { limit: params.limit ?? 100 };
+    const body = {};
     if (params.bbox != null) {
         body['bbox'] = params.bbox;
     }
@@ -251,6 +309,9 @@ function placesSearchBody(params) {
     if (params.orTags?.length) {
         body['orTags'] = params.orTags;
     }
+    if (params.limit != null) {
+        body['limit'] = params.limit;
+    }
     if (params.openNow) {
         body['openNow'] = true;
     }
@@ -262,9 +323,10 @@ function placesSearchBody(params) {
 function placesNearbyBody(params) {
     const body = {
         location: latlng(params.location),
-        radius: params.radius ?? 1000,
-        limit: params.limit ?? 10,
     };
+    if (params.radius != null) {
+        body['radius'] = params.radius;
+    }
     if (params.type != null) {
         body['type'] = params.type;
     }
@@ -274,6 +336,9 @@ function placesNearbyBody(params) {
     if (params.orTags?.length) {
         body['orTags'] = params.orTags;
     }
+    if (params.limit != null) {
+        body['limit'] = params.limit;
+    }
     if (params.openNow) {
         body['openNow'] = true;
     }
@@ -285,7 +350,6 @@ function placesNearbyBody(params) {
 function routesIsochroneBody(params) {
     const body = {
         origin: lonlat(params.origin),
-        travelMode: params.travelMode ?? 'WALK',
     };
     if (params.maxDistanceM != null) {
         body['max_distance_m'] = params.maxDistanceM;
@@ -296,28 +360,37 @@ function routesIsochroneBody(params) {
     if (params.searchBufferM != null) {
         body['search_buffer_m'] = params.searchBufferM;
     }
+    if (params.travelMode != null) {
+        body['travelMode'] = params.travelMode;
+    }
     return body;
 }
 function routesPathBody(params) {
     const body = {
         stops: params.stops.map(lonlat),
-        travelMode: params.travelMode ?? 'WALK',
     };
     if (params.searchBufferM != null) {
         body['search_buffer_m'] = params.searchBufferM;
     }
+    if (params.travelMode != null) {
+        body['travelMode'] = params.travelMode;
+    }
     return body;
 }
 function routesOptimizedPathBody(params) {
     const body = {
         start: lonlat(params.start),
         stops: params.stops.map(lonlat),
-        loop: params.loop ?? true,
-        travelMode: params.travelMode ?? 'WALK',
     };
+    if (params.loop != null) {
+        body['loop'] = params.loop;
+    }
     if (params.searchBufferM != null) {
         body['search_buffer_m'] = params.searchBufferM;
     }
+    if (params.travelMode != null) {
+        body['travelMode'] = params.travelMode;
+    }
     return body;
 }
 function sleep(ms) {
@@ -390,6 +463,7 @@ export class OSMFeatures {
             zoom: optionalNumber(query, 'zoom'),
             location: optionalString(query, 'location'),
             radius: optionalNumber(query, 'radius'),
+            within: optionalString(query, 'within'),
             osmIds: optionalString(query, 'osm_ids'),
             minLengthM: optionalNumber(query, 'min_length_m'),
             maxLengthM: optionalNumber(query, 'max_length_m'),
@@ -400,6 +474,64 @@ export class OSMFeatures {
             clipGeometry: optionalBoolean(query, 'clipGeometry'),
         };
     }
+    /** Map Express/query params into `stats` params. `group_by` is required. */
+    resolveStatsRequest(query) {
+        const q = asQueryMap(query);
+        const groupBy = optionalString(q, 'group_by');
+        if (groupBy == null) {
+            throw appError(400, 'invalid_group_by', 'group_by is required.');
+        }
+        const tags = stringList(q, 'tags');
+        const orTags = stringList(q, 'or_tags');
+        const notTags = stringList(q, 'not_tags');
+        const wayShapeRaw = optionalString(q, 'way_shape') ?? optionalString(q, 'shape');
+        const wayShape = wayShapeRaw === 'line' || wayShapeRaw === 'polygon' || wayShapeRaw === 'all'
+            ? wayShapeRaw
+            : undefined;
+        const params = { groupBy };
+        const bbox = optionalString(q, 'bbox');
+        if (bbox)
+            params.bbox = bbox;
+        const within = optionalString(q, 'within');
+        if (within)
+            params.within = within;
+        const location = optionalString(q, 'location');
+        if (location)
+            params.location = location;
+        const radius = optionalNumber(q, 'radius');
+        if (radius != null)
+            params.radius = radius;
+        const type = optionalString(q, 'type');
+        if (type)
+            params.type = type;
+        if (wayShape)
+            params.wayShape = wayShape;
+        if (tags.length > 0)
+            params.tags = tags;
+        if (orTags.length > 0)
+            params.orTags = orTags;
+        if (notTags.length > 0)
+            params.notTags = notTags;
+        const limit = optionalNumber(q, 'limit');
+        if (limit != null && Number.isFinite(limit))
+            params.limit = Math.trunc(limit);
+        const minLengthM = optionalNumber(q, 'min_length_m');
+        if (minLengthM != null)
+            params.minLengthM = minLengthM;
+        const maxLengthM = optionalNumber(q, 'max_length_m');
+        if (maxLengthM != null)
+            params.maxLengthM = maxLengthM;
+        const minAreaM2 = optionalNumber(q, 'min_area_m2');
+        if (minAreaM2 != null)
+            params.minAreaM2 = minAreaM2;
+        const maxAreaM2 = optionalNumber(q, 'max_area_m2');
+        if (maxAreaM2 != null)
+            params.maxAreaM2 = maxAreaM2;
+        const disableBudgetWarning = optionalBoolean(q, 'disable_budget_warning');
+        if (disableBudgetWarning)
+            params.disableBudgetWarning = true;
+        return params;
+    }
     async throwUpstreamError(upstream) {
         const subtype = upstream.status === 429 ? 'upstream_rate_limit' : undefined;
         const upstreamDetail = await readUpstreamErrorDetail(upstream);
@@ -519,7 +651,7 @@ export class OSMFeatures {
         };
     }
     /** Single upstream page. Params map 1:1 to server query string (no tiling). */
-    async query({ bbox, tags, orTags, notTags, type, wayShape, shape, limit = DEFAULT_LIMIT, cursor, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
+    async query({ bbox, tags, orTags, notTags, type, wayShape, shape, limit, cursor, zoom, location, radius, within, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
         const payload = await this._rawQuery({
             bbox,
             tags,
@@ -533,6 +665,7 @@ export class OSMFeatures {
             zoom,
             location,
             radius,
+            within,
             osmIds,
             minLengthM,
             maxLengthM,
@@ -546,7 +679,7 @@ export class OSMFeatures {
         return payload;
     }
     /** Auto-paginate (and optionally tile) until complete. Each page uses `_rawQuery`. */
-    async query_all({ bbox, tags, orTags, notTags, type, wayShape, shape, zoom, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage = DEFAULT_LIMIT, bboxTiles = 2, maxPages = 15, maxFeatures = 55_000, }, dependencies = {}) {
+    async query_all({ bbox, tags, orTags, notTags, type, wayShape, shape, zoom, location, radius, within, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage, bboxTiles = 2, maxPages = 15, maxFeatures = 55_000, }, dependencies = {}) {
         if (!isGeojsonAccept(accept)) {
             throw appError(400, 'invalid_accept', 'query_all only supports GeoJSON; use query({ accept }) for binary encodings.');
         }
@@ -557,7 +690,7 @@ export class OSMFeatures {
         const sleepFn = dependencies.sleepFn ?? sleep;
         const nowFn = dependencies.nowFn ?? Date.now;
         const featureCap = maxFeatures == null ? Number.POSITIVE_INFINITY : maxFeatures;
-        const tileBboxes = bbox ? splitBbox(bbox, bboxTiles) : [undefined];
+        const tileBboxes = within || !bbox ? [undefined] : splitBbox(bbox, bboxTiles);
         const allFeatures = [];
         let pageCount = 0;
         let lastPage = null;
@@ -578,6 +711,7 @@ export class OSMFeatures {
             zoom,
             location,
             radius,
+            within,
             osmIds,
             minLengthM,
             maxLengthM,
@@ -601,7 +735,7 @@ export class OSMFeatures {
             while (tilePages < maxPages && allFeatures.length < featureCap) {
                 let page;
                 try {
-                    const raw = await this._rawQuery({ ...baseParams, bbox: tileBbox, cursor }, fetchFn, sleepFn, nowFn);
+                    const raw = await this._rawQuery({ ...baseParams, bbox: within ? undefined : tileBbox, cursor }, fetchFn, sleepFn, nowFn);
                     if (raw.data instanceof ArrayBuffer) {
                         throw appError(400, 'invalid_accept', 'query_all only supports GeoJSON; use query({ accept }) for binary encodings.');
                     }
@@ -665,6 +799,31 @@ export class OSMFeatures {
         }
         return resultFromFeatures(features, meta);
     }
+    /** Count features grouped by a tag key (``GET /v2/osm_features/stats``). */
+    async stats(params, dependencies = {}) {
+        if (!params.groupBy) {
+            throw appError(400, 'invalid_group_by', 'group_by is required.');
+        }
+        const body = await this._getJson('/v2/osm_features/stats', buildFeaturesQuery({
+            bbox: params.bbox,
+            tags: params.tags,
+            orTags: params.orTags,
+            notTags: params.notTags,
+            type: params.type,
+            wayShape: params.wayShape ?? params.shape,
+            limit: params.limit,
+            location: params.location,
+            radius: params.radius,
+            within: params.within,
+            groupBy: params.groupBy,
+            minLengthM: params.minLengthM,
+            maxLengthM: params.maxLengthM,
+            minAreaM2: params.minAreaM2,
+            maxAreaM2: params.maxAreaM2,
+            disableBudgetWarning: params.disableBudgetWarning,
+        }), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
+        return body;
+    }
     /** Preflight credit cost (``GET /v2/osm_features/cost``). */
     async estimate_cost(params = {}, dependencies = {}) {
         return this._getJson('/v2/osm_features/cost', buildFeaturesQuery({
@@ -674,10 +833,11 @@ export class OSMFeatures {
             notTags: params.notTags,
             type: params.type,
             wayShape: params.wayShape ?? params.shape,
-            limit: params.limit ?? DEFAULT_LIMIT,
+            limit: params.limit,
             zoom: params.zoom,
             location: params.location,
             radius: params.radius,
+            within: params.within,
             osmIds: params.osmIds,
             minLengthM: params.minLengthM,
             maxLengthM: params.maxLengthM,
@@ -692,15 +852,15 @@ export class OSMFeatures {
     async usage(dependencies = {}) {
         return this._getJson('/v1/usage', {}, dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
     }
-    /** Find places in a bbox or radius (``POST /v1/places/search``). */
+    /** Find places in a bbox or radius (``POST /v1/places/search``). Features have ``properties.openNow`` when hours are known. */
     async places_search(params, dependencies = {}) {
         return this._postJson('/v1/places/search', placesSearchBody(params), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
     }
-    /** Nearest places from a point (``POST /v1/places/nearby``). */
+    /** Nearest places from a point (``POST /v1/places/nearby``). Features have ``properties.openNow`` when hours are known. */
     async places_nearby(params, dependencies = {}) {
         return this._postJson('/v1/places/nearby', placesNearbyBody(params), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
     }
-    /** One place by OSM id (``GET /v1/places/{osm_type}/{osm_id}``). */
+    /** One place by OSM id (``GET /v1/places/{osm_type}/{osm_id}``). Feature has ``properties.openNow`` when hours are known. */
     async places_details(params, dependencies = {}) {
         const { osmType, osmId } = parsePlaceRef(params.osmType, params.osmId);
         return this._getJson(`/v1/places/${osmType}/${osmId}`, {}, dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
@@ -719,4 +879,6 @@ export class OSMFeatures {
     }
 }
 export * from './geojson-feature.js';
+export * from './geometry.js';
+export * from './nearest.js';
 export * from './preset/index.js';

package/dist/nearest.d.ts

@@ -0,0 +1,28 @@
+/** Local nearest-neighbor join over two GeoJSON feature sets. No HTTP. */
+export declare const MAX_COMPARISONS = 500000;
+export type NearestWithinPair = {
+    feature: unknown;
+    distance_m: number;
+    nearest: unknown;
+};
+/**
+ * Nearest secondary for each primary, within `maxDistanceM`.
+ *
+ * Accepts a FeatureCollection, a `{ data, meta }` `query` / `query_all` result,
+ * or a list of Features. Point comes from `geometry` when it is a Point, else
+ * `properties.centroid` (same rules as `featureCentroid`). A feature with
+ * neither throws.
+ *
+ * Returns pairs sorted by `distance_m`:
+ * `{ feature, distance_m, nearest }`
+ *
+ * `limit` keeps the closest pairs (SDK default 20). Pass `null` for every
+ * primary that has a match. O(n×m) haversine. Fine at search `limit`
+ * (default 100). Joins whose `len(primary) * len(secondary)` exceeds
+ * `maxComparisons` (default 500_000) throw. Pass `maxComparisons: null`
+ * for no cap.
+ */
+export declare function nearest_within(primary: unknown, secondary: unknown, maxDistanceM: number, { limit, maxComparisons, }?: {
+    limit?: number | null;
+    maxComparisons?: number | null;
+}): NearestWithinPair[];

package/dist/nearest.js

@@ -0,0 +1,98 @@
+/** Local nearest-neighbor join over two GeoJSON feature sets. No HTTP. */
+import { featureCentroid } from './geojson-feature.js';
+// Mean Earth radius. ponytail: sphere, not WGS84 ellipsoid; swap if you need centimetre-grade distances.
+const EARTH_RADIUS_M = 6_371_000;
+// O(n×m) haversine. 500k is ~1000×500 or 10_000×50; search-sized joins fit.
+export const MAX_COMPARISONS = 500_000;
+function haversineM(lon1, lat1, lon2, lat2) {
+    const p1 = (lat1 * Math.PI) / 180;
+    const p2 = (lat2 * Math.PI) / 180;
+    const dlat = ((lat2 - lat1) * Math.PI) / 180;
+    const dlon = ((lon2 - lon1) * Math.PI) / 180;
+    const a = Math.sin(dlat / 2) ** 2 + Math.cos(p1) * Math.cos(p2) * Math.sin(dlon / 2) ** 2;
+    return 2 * EARTH_RADIUS_M * Math.asin(Math.sqrt(Math.min(a, 1)));
+}
+function features(src) {
+    if (Array.isArray(src)) {
+        return src;
+    }
+    if (src && typeof src === 'object') {
+        const record = src;
+        if (Array.isArray(record['features'])) {
+            return record['features'];
+        }
+        const data = record['data'];
+        if (data && typeof data === 'object' && Array.isArray(data.features)) {
+            return data.features;
+        }
+    }
+    throw new TypeError('expected a FeatureCollection or list of Features');
+}
+function lonLat(feat) {
+    if (!feat || typeof feat !== 'object') {
+        throw new Error('feature must be a GeoJSON Feature dict');
+    }
+    const record = feat;
+    const point = featureCentroid({
+        geometry: (record['geometry'] ?? null),
+        properties: record['properties'],
+    });
+    if (point == null || !Number.isFinite(point[0]) || !Number.isFinite(point[1])) {
+        throw new Error('feature has no Point geometry or properties.centroid');
+    }
+    return point;
+}
+/**
+ * Nearest secondary for each primary, within `maxDistanceM`.
+ *
+ * Accepts a FeatureCollection, a `{ data, meta }` `query` / `query_all` result,
+ * or a list of Features. Point comes from `geometry` when it is a Point, else
+ * `properties.centroid` (same rules as `featureCentroid`). A feature with
+ * neither throws.
+ *
+ * Returns pairs sorted by `distance_m`:
+ * `{ feature, distance_m, nearest }`
+ *
+ * `limit` keeps the closest pairs (SDK default 20). Pass `null` for every
+ * primary that has a match. O(n×m) haversine. Fine at search `limit`
+ * (default 100). Joins whose `len(primary) * len(secondary)` exceeds
+ * `maxComparisons` (default 500_000) throw. Pass `maxComparisons: null`
+ * for no cap.
+ */
+export function nearest_within(primary, secondary, maxDistanceM, { limit = 20, maxComparisons = MAX_COMPARISONS, } = {}) {
+    if (limit != null && limit < 1) {
+        throw new Error('limit must be a positive int');
+    }
+    if (maxComparisons != null && maxComparisons < 1) {
+        throw new Error('max_comparisons must be a positive int');
+    }
+    const primaries = features(primary);
+    const secondaries = features(secondary);
+    if (primaries.length === 0 || secondaries.length === 0) {
+        return [];
+    }
+    const n = primaries.length;
+    const m = secondaries.length;
+    if (maxComparisons != null && n * m > maxComparisons) {
+        throw new Error(`nearest_within join is ${n}×${m} comparisons `
+            + `(cap ${maxComparisons}). Shrink the collections `
+            + '(places_search/nearby limit, not query_all).');
+    }
+    const secPts = secondaries.map((s) => [s, lonLat(s)]);
+    const pairs = [];
+    for (const p of primaries) {
+        const [plon, plat] = lonLat(p);
+        let best = null;
+        for (const [s, [slon, slat]] of secPts) {
+            const d = haversineM(plon, plat, slon, slat);
+            if (best === null || d < best[0]) {
+                best = [d, s];
+            }
+        }
+        if (best !== null && best[0] <= maxDistanceM) {
+            pairs.push({ feature: p, distance_m: best[0], nearest: best[1] });
+        }
+    }
+    pairs.sort((a, b) => a.distance_m - b.distance_m);
+    return limit == null ? pairs : pairs.slice(0, limit);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osmfeatures",
-  "version": "0.2.4",
+  "version": "0.5.0",
   "description": "Get OpenStreetMap features such as buildings, roads, or points of interest from dedicated servers with a single API call in GeoJSON, FlatGeobuf, Geoparquet, and CSV formats.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "tsx src/index.test.ts && tsx src/geojson-feature.test.ts && tsx src/preset/preset.test.ts && tsx src/tutorial.test.ts",
+    "test": "tsx src/index.test.ts && tsx src/geojson-feature.test.ts && tsx src/geometry.test.ts && tsx src/nearest.test.ts && tsx src/preset/preset.test.ts && tsx src/tutorial.test.ts",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },