osmfeatures 0.3.0 → 0.5.0

package/README.md

@@ -10,6 +10,7 @@ The backend is dedicated PostGIS, not the public Overpass endpoint, with API key
 - [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)
@@ -88,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.            |
 
 
@@ -161,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({
@@ -181,7 +183,7 @@ 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                                                                                                                                               |
@@ -214,6 +216,30 @@ 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`
 
 Preflight credit cost via `GET /v2/osm_features/cost`. Same filter params as `query`. No OSM data is fetched.

package/dist/index.d.ts

@@ -46,6 +46,8 @@ 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;
@@ -59,6 +61,38 @@ export type OSMFeaturesParams = OSMFeaturesLayer & {
     /** 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``. */
@@ -161,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;
@@ -171,9 +207,9 @@ 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'> & {
+    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;
@@ -181,6 +217,8 @@ export declare class OSMFeatures {
         /** 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``). */

package/dist/index.js

@@ -109,6 +109,35 @@ function optionalBoolean(query, key) {
     }
     return undefined;
 }
+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) {
@@ -185,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);
     }
@@ -428,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'),
@@ -438,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);
@@ -557,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, 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,
@@ -571,6 +665,7 @@ export class OSMFeatures {
             zoom,
             location,
             radius,
+            within,
             osmIds,
             minLengthM,
             maxLengthM,
@@ -584,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, 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.');
         }
@@ -595,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;
@@ -616,6 +711,7 @@ export class OSMFeatures {
             zoom,
             location,
             radius,
+            within,
             osmIds,
             minLengthM,
             maxLengthM,
@@ -639,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.');
                     }
@@ -703,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({
@@ -716,6 +837,7 @@ export class OSMFeatures {
             zoom: params.zoom,
             location: params.location,
             radius: params.radius,
+            within: params.within,
             osmIds: params.osmIds,
             minLengthM: params.minLengthM,
             maxLengthM: params.maxLengthM,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osmfeatures",
-  "version": "0.3.0",
+  "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",