osmfeatures 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
-# MapLark OSM Features API client
+# OSM Features API client
 
-Official TypeScript/JavaScript client for the [MapLark OSM Features API](https://maplark.com) (GeoJSON, FlatGeobuf, GeoParquet, CSV). 
+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.
 
-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 OpenStreetMap semantics intact, like tags and ways, and returns GeoJSON 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 predictable latency for real traffic. It also has self-host path for those willing to host complex infrastructure themselves.
+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 self-host path for those willing to host complex infrastructure themselves.
 
 The translation layer is very simple:
 
@@ -24,16 +24,10 @@ For example, to get all buildings in an area:
 
 This is the equivalent of the Overpass query `way[building]`.
 
-Read the full API reference here [https://maplark.com/developer](https://maplark.com/developer).
-
-# How to use it
+# Quick start
 
 ```bash
-# From npm (when published):
 npm install osmfeatures
-
-# Until then, from git:
-npm install git+https://github.com/MapLark/osmfeatures-ts.git
 ```
 
 ```ts
@@ -45,23 +39,164 @@ const page = await client.query({
   tags: ['building'],
 });
 
-// Vanilla GeoJSON FeatureCollection (same shape as the HTTP body).
-map.getSource('buildings').setData(page.data);
+// Get GeoJSON FeatureCollection
 console.log(page.data.features.length);
 
-// Header-derived meta (not part of GeoJSON): paging + usage.
+// Header meta for paging + usage
 console.log(page.meta.has_more, page.meta.next_cursor, page.meta.units_charged);
 
-// Binary / table encodings via Accept — same { data, meta } shape.
+// Binary / table encodings via Accept param
 const fgb = await client.query({
   bbox: '18.06,59.32,18.09,59.34',
   tags: ['building'],
   accept: 'application/flatgeobuf',
 });
-console.log(fgb.data instanceof ArrayBuffer, fgb.meta.has_more, fgb.meta.next_cursor);
+console.log(fgb.data);
+console.log(fgb.meta.has_more, fgb.meta.next_cursor);
 ```
 
 Talks to `https://api.maplark.com` by default.
 
-Also exports layer presets (`resolveLayerFromQuery`, `OSM_FEATURES_LAYER_PRESETS`, …)
-and GeoJSON payload helpers (`featureCentroid`, `geometryBounds`, `parseFeatureId`, …).
+# Functions and Parameters
+
+
+
+## `query()`
+
+Fetches a single page from the API. Returns `{ data, meta }` where `data` is a GeoJSON FeatureCollection (default) or an `ArrayBuffer` for binary encodings.
+
+#### Spatial anchors (required)
+
+The geographical area for the request in terms of GPS coordinates or specific OSM ids.
+
+
+| Param    | Type     | Description                                        |
+| -------- | -------- | -------------------------------------------------- |
+| `bbox`   | `string` | Bounding box as `min_lon,min_lat,max_lon,max_lat`. |
+| `around` | `string` | Circle filter as `lon,lat,radius_m`.               |
+| `osmIds` | `string` | Comma-separated OSM IDs to fetch by id.            |
+
+
+
+
+#### Tags
+
+The feature tags to filter on.
+
+
+| Param     | Type       | Description                                                                      |
+| --------- | ---------- | -------------------------------------------------------------------------------- |
+| `tags`    | `string[]` | Tag filters that must all match (AND). Values like `building` or `amenity=cafe`. |
+| `orTags`  | `string[]` | Tag filters where any may match (OR).                                            |
+| `notTags` | `string[]` | Tag filters to exclude.                                                          |
+
+
+
+
+#### Geometry
+
+Geometric filters such specific OSM element type, min length, or including centroid.
+
+
+| Param        | Type                   | Default | Description                                                                             |
+| ------------ | ---------------------- | ------- | --------------------------------------------------------------------------------------- |
+| `type`       | `string`               | all     | OSM element types, e.g. `node`, `way`, `relation`, or comma-separated (`way,relation`). |
+| `shape`      | `line | polygon | all` | `all`   | Geometry shape filter for ways and relations.                                           |
+| `centroid`   | `boolean`              | `false` | When `true`, include a centroid on non-point features.                                  |
+| `clipGeometry` | `boolean`            | `true`  | When `true`, clip returned geometry to the requested `bbox`. Set `false` for full geometry. |
+| `minLengthM` | `number`               |         | Minimum length in metres (lines).                                                       |
+| `maxLengthM` | `number`               |         | Maximum length in metres (lines).                                                       |
+| `minAreaM2`  | `number`               |         | Minimum area in square metres (polygons).                                               |
+| `maxAreaM2`  | `number`               |         | Maximum area in square metres (polygons).                                               |
+
+
+
+
+#### Other
+
+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`.                                                                                                                                                    |
+| `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).                                                                                                    |
+
+
+
+
+### Meta
+
+Fields for pagination and usage.
+
+
+| Field           | Description                                                           |
+| --------------- | --------------------------------------------------------------------- |
+| `returned`      | Features in this page.                                                |
+| `has_more`      | Whether more pages exist.                                             |
+| `next_cursor`   | Pass as `cursor` on the next `query` call, or `null` when done.       |
+| `units_charged` | Usage for this request when present in terms of cpu and ram consumed. |
+
+
+
+
+## `query_all`
+
+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.
+
+```ts
+const all = await client.query_all({
+  bbox: '18.06,59.32,18.09,59.34',
+  tags: ['building'],
+  limitPerPage: 1000,
+  bboxTiles: 2,
+  maxPages: 15,
+  maxFeatures: 55_000,
+});
+
+console.log(all.data.features.length);
+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`, `shape`, `zoom`, `around`, `osmIds`, `minLengthM`, `maxLengthM`, `minAreaM2`, `maxAreaM2`, `centroid`, `clipGeometry`, `disableBudgetWarning`), plus:
+
+
+| Param          | Type            | Default                | Description                                                                                                                                               |
+| -------------- | --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `limitPerPage` | `number`        | `1000`                 | Upstream `limit` per HTTP request (page size).                                                                                                            |
+| `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.                                                                                              |
+| `accept`       | `string`        | `application/geo+json` | Must be GeoJSON (or omitted). Non-GeoJSON throws.                                                                                                         |
+
+
+
+
+### Meta
+
+Same fields as `query`, plus:
+
+
+| Field                  | Description                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------ |
+| `page_count`           | Total upstream pages fetched.                                                        |
+| `has_more`             | `true` if stopped early (caps), or upstream still had more, or a partial relay stop. |
+| `next_cursor`          | Last cursor when incomplete; otherwise the final page cursor.                        |
+| `units_charged`        | Sum of units charged across pages when present.                                      |
+| `relay_partial`        | `true` if paging stopped after a mid-stream 400/429 (partial result kept).           |
+| `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`, ...).
+
+Read the full API reference here [https://maplark.com/developer](https://maplark.com/developer) such as the OpenAPI 2.0 HTTP docs.

package/dist/index.d.ts

@@ -47,6 +47,8 @@ export type OSMFeaturesParams = OSMFeaturesLayer & {
     maxAreaM2?: number;
     disableBudgetWarning?: boolean;
     centroid?: boolean;
+    /** When true (default), clip returned geometry to the requested bbox. */
+    clipGeometry?: boolean;
     /** Accept media type. Default application/geo+json; other types put bytes in ``data``. */
     accept?: string;
 };
@@ -81,9 +83,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, shape, limit, cursor, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, accept, }: OSMFeaturesParams, dependencies?: OSMFeaturesDependencies): Promise<OSMFeaturesResult>;
+    query({ bbox, tags, orTags, notTags, type, shape, limit, cursor, zoom, around, 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, shape, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, accept, limitPerPage, bboxTiles, maxPages, maxFeatures, }: Omit<OSMFeaturesParams, 'limit' | 'cursor'> & {
+    query_all({ bbox, tags, orTags, notTags, type, shape, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage, bboxTiles, maxPages, maxFeatures, }: Omit<OSMFeaturesParams, 'limit' | 'cursor'> & {
         /** Upstream `limit` per HTTP request (page size). */
         limitPerPage?: number;
         bboxTiles?: number;

package/dist/index.js

@@ -177,6 +177,9 @@ function buildFeaturesQuery(params) {
     if (params.centroid != null) {
         query.set('centroid', String(params.centroid));
     }
+    if (params.clipGeometry != null) {
+        query.set('clipGeometry', String(params.clipGeometry));
+    }
     if (params.type) {
         query.set('type', params.type);
     }
@@ -270,6 +273,7 @@ export class OSMFeatures {
             maxAreaM2: optionalNumber(query, 'max_area_m2'),
             disableBudgetWarning: optionalBoolean(query, 'disable_budget_warning'),
             centroid: optionalBoolean(query, 'centroid'),
+            clipGeometry: optionalBoolean(query, 'clipGeometry'),
         };
     }
     async throwUpstreamError(upstream) {
@@ -335,6 +339,8 @@ export class OSMFeatures {
                         }
                     }
                 }
+                // ponytail: simple stderr-visible warning for 429 retries; upgrade to injected logger if consumers need structured logs.
+                console.warn(`[osmfeatures] Upstream returned 429; retry ${retryAttempt}/${this.retryAttempts} in ${Math.round(waitMs)}ms.`);
                 await sleepFn(waitMs);
                 continue;
             }
@@ -352,7 +358,7 @@ export class OSMFeatures {
         };
     }
     /** Single upstream page. Params map 1:1 to server query string (no tiling). */
-    async query({ bbox, tags, orTags, notTags, type, shape, limit = DEFAULT_LIMIT, cursor, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, accept, }, dependencies = {}) {
+    async query({ bbox, tags, orTags, notTags, type, shape, limit = DEFAULT_LIMIT, cursor, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
         const payload = await this._rawQuery({
             bbox,
             tags,
@@ -371,12 +377,13 @@ export class OSMFeatures {
             maxAreaM2,
             disableBudgetWarning,
             centroid,
+            clipGeometry,
             accept,
         }, dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
         return payload;
     }
     /** Auto-paginate (and optionally tile) until complete. Each page uses `_rawQuery`. */
-    async query_all({ bbox, tags, orTags, notTags, type, shape, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, accept, limitPerPage = DEFAULT_LIMIT, bboxTiles = 2, maxPages = 15, maxFeatures = 55_000, }, dependencies = {}) {
+    async query_all({ bbox, tags, orTags, notTags, type, shape, zoom, around, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, limitPerPage = DEFAULT_LIMIT, 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.');
         }
@@ -413,6 +420,7 @@ export class OSMFeatures {
             maxAreaM2,
             disableBudgetWarning,
             centroid,
+            clipGeometry,
         };
         for (const tileBbox of tileBboxes) {
             if (allFeatures.length >= featureCap) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "osmfeatures",
-  "version": "0.1.0",
-  "description": "Official client for the MapLark OSM Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV)",
+  "version": "0.1.2",
+  "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",
   "types": "./dist/index.d.ts",