osmfeatures 0.1.0 → 0.2.0

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,240 @@ 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`. |
+| `location` | `string` | Point for a radius search as `lat,lng`. Requires `radius`. |
+| `radius` | `number` | Search radius in metres. Requires `location`. |
+| `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`, `location`, `radius`, `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`, ...).
+
+## `estimate_cost`
+
+Preflight credit cost via `GET /v2/osm_features/cost`. Same filter params as `query`. No OSM data is fetched.
+
+```ts
+const estimate = await client.estimate_cost({
+  bbox: '18.06,59.32,18.09,59.34',
+  tags: ['building'],
+});
+console.log(estimate.estimated_credits);
+```
+
+## `usage`
+
+This month's unit-budget usage via `GET /v1/usage`.
+
+```ts
+const usage = await client.usage();
+console.log(usage.tier, usage.usage_this_month, usage.remaining_this_month);
+```
+
+## `places_search` / `places_nearby` / `places_details`
+
+Place discovery and lookup. Search is a bbox or `location`+`radius`. Nearby ranks one set from a point. Details refetches a search/nearby feature id (`node/123`). Search and nearby hours use each place's local timezone; optional `asOf` pins the evaluation instant.
+
+```ts
+const origin = { lat: 59.316, lon: 18.075 };
+
+const cafes = await client.places_search({
+  location: origin,
+  radius: 800,
+  orTags: ['amenity=cafe'],
+  openNow: true,
+  asOf: '2026-08-10T18:00:00+02:00',
+});
+
+const nearby = await client.places_nearby({
+  location: origin,
+  orTags: ['amenity=cafe'],
+  limit: 5,
+  openNow: true,
+  asOf: '2026-08-10T18:00:00+02:00',
+});
+
+const first = (cafes.features as { id: string }[])[0];
+const details = await client.places_details({ osmType: first.id });
+```
+
+`places_details` also accepts `{ osmType: 'node', osmId: 123 }`. Hours are annotated at request time in the place's local timezone.
+
+## `routes_isochrone` / `routes_path` / `routes_optimized_path`
+
+Walk or bicycle routing via `POST /v1/routes/*`. Points accept `lon` or `lng`.
+
+```ts
+const origin = { lon: 18.075, lat: 59.316 };
+const cafe = { lon: 18.08, lat: 59.318 };
+
+const iso = await client.routes_isochrone({
+  origin,
+  durationS: 600,
+});
+
+const path = await client.routes_path({
+  stops: [origin, cafe],
+});
+
+const tour = await client.routes_optimized_path({
+  start: origin,
+  stops: [cafe],
+});
+```
+
+`routes_isochrone` takes exactly one of `maxDistanceM` or `durationS`. `routes_path` follows `stops` in listed order (no TSP). `routes_optimized_path` orders `stops` from `start`; `loop` (default true) returns to start. Optional `searchBufferM` and `travelMode` (`WALK` or `BICYCLE`).
+
+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

@@ -27,7 +27,7 @@ export type OSMFeaturesResult = {
 };
 /** Layer filters from presets / custom resolve. Pass into `resolveRequest` or spread into `query`. */
 export type OSMFeaturesLayer = {
-    bbox: string;
+    bbox?: string;
     tags?: string[];
     orTags?: string[];
     notTags?: string[];
@@ -39,7 +39,10 @@ export type OSMFeaturesParams = OSMFeaturesLayer & {
     limit?: number;
     cursor?: string;
     zoom?: number;
-    around?: string;
+    /** Point for a radius search as `lat,lng`. Requires `radius`. */
+    location?: string;
+    /** Search radius in metres. Requires `location`. */
+    radius?: number;
     osmIds?: string;
     minLengthM?: number;
     maxLengthM?: number;
@@ -47,11 +50,67 @@ 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;
 };
 type QueryValue = unknown;
 export type OSMFeaturesQuery = Record<string, QueryValue>;
+/** Routing point. Accepts ``lon`` or ``lng``. */
+export type LonLat = {
+    lat: number;
+} & ({
+    lon: number;
+} | {
+    lng: number;
+});
+export type RouteTravelMode = 'WALK' | 'BICYCLE';
+export type RoutesIsochroneParams = {
+    origin: LonLat;
+    maxDistanceM?: number;
+    durationS?: number;
+    searchBufferM?: number;
+    travelMode?: RouteTravelMode;
+};
+export type RoutesPathParams = {
+    stops: LonLat[];
+    searchBufferM?: number;
+    travelMode?: RouteTravelMode;
+};
+export type RoutesOptimizedPathParams = {
+    start: LonLat;
+    stops: LonLat[];
+    searchBufferM?: number;
+    loop?: boolean;
+    travelMode?: RouteTravelMode;
+};
+export type PlacesSearchParams = {
+    bbox?: string;
+    location?: LonLat;
+    radius?: number;
+    type?: string;
+    tags?: string[];
+    orTags?: string[];
+    limit?: number;
+    openNow?: boolean;
+    asOf?: string;
+};
+export type PlacesNearbyParams = {
+    location: LonLat;
+    radius?: number;
+    type?: string;
+    tags?: string[];
+    orTags?: string[];
+    limit?: number;
+    openNow?: boolean;
+    asOf?: string;
+};
+export type PlacesDetailsParams = {
+    /** ``node`` / ``way`` / ``relation``, or a full ``node/123`` feature id. */
+    osmType: string;
+    osmId?: number | string;
+};
 type OSMFeaturesDependencies = {
     fetchFn?: typeof fetch;
     sleepFn?: (ms: number) => Promise<void>;
@@ -78,12 +137,18 @@ export declare class OSMFeatures {
     /** Map Express/query params + resolved layer into flat `query` / `query_all` params. */
     resolveRequest(query: OSMFeaturesQuery, layer: OSMFeaturesLayer): OSMFeaturesParams;
     private throwUpstreamError;
+    /** GET/POST with 429 retry. Throws on non-OK. */
+    private _fetchOk;
+    /** POST JSON to a geo-agent path. */
+    private _postJson;
+    /** GET JSON from a geo-agent or account path. */
+    private _getJson;
     /** 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, location, radius, 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, 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). */
         limitPerPage?: number;
         bboxTiles?: number;
@@ -91,6 +156,22 @@ export declare class OSMFeatures {
         /** Cap on merged features. `null` = no cap. */
         maxFeatures?: number | null;
     }, dependencies?: OSMFeaturesDependencies): Promise<OSMGeoJSONResult>;
+    /** 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``). */
+    places_search(params: PlacesSearchParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
+    /** Nearest places from a point (``POST /v1/places/nearby``). */
+    places_nearby(params: PlacesNearbyParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
+    /** One place by OSM id (``GET /v1/places/{osm_type}/{osm_id}``). */
+    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>>;
+    /** Given-order walk/bike path (``POST /v1/routes/path``). */
+    routes_path(params: RoutesPathParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
+    /** TSP walk/bike tour from ``start`` (``POST /v1/routes/optimized_path``). ``loop`` returns to start. */
+    routes_optimized_path(params: RoutesOptimizedPathParams, dependencies?: OSMFeaturesDependencies): Promise<Record<string, unknown>>;
 }
 export * from './geojson-feature.js';
 export * from './preset/index.js';

package/dist/index.js

@@ -21,6 +21,7 @@ function metaFromHeaders(headers, featureCount) {
     }
     return meta;
 }
+const PLACE_TYPES = new Set(['node', 'way', 'relation']);
 const DEFAULT_BASE_URL = 'https://api.maplark.com';
 const DEFAULT_LIMIT = 1000;
 const MAX_LIMIT = 6000;
@@ -145,7 +146,9 @@ export function splitBbox(bbox, tileCount) {
 }
 function buildFeaturesQuery(params) {
     const query = new URLSearchParams();
-    query.set('bbox', params.bbox);
+    if (params.bbox) {
+        query.set('bbox', params.bbox);
+    }
     query.set('limit', String(params.limit));
     if (params.cursor) {
         query.set('cursor', params.cursor);
@@ -153,8 +156,11 @@ function buildFeaturesQuery(params) {
     if (params.zoom != null) {
         query.set('zoom', String(params.zoom));
     }
-    if (params.around) {
-        query.set('around', params.around);
+    if (params.location) {
+        query.set('location', params.location);
+    }
+    if (params.radius != null) {
+        query.set('radius', String(params.radius));
     }
     if (params.osmIds) {
         query.set('osm_ids', params.osmIds);
@@ -177,6 +183,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);
     }
@@ -194,6 +203,122 @@ function buildFeaturesQuery(params) {
     }
     return query;
 }
+function lonlat(point) {
+    const lon = 'lon' in point ? point.lon : point.lng;
+    return { lon, lat: point.lat };
+}
+function latlng(point) {
+    const lng = 'lng' in point ? point.lng : point.lon;
+    return { lat: point.lat, lng };
+}
+function parsePlaceRef(osmType, osmId) {
+    if (osmId == null) {
+        const raw = osmType.trim();
+        const slash = raw.indexOf('/');
+        if (slash < 0) {
+            throw appError(400, 'invalid_place_id', 'place id must be node|way|relation plus a positive osm_id');
+        }
+        return parsePlaceRef(raw.slice(0, slash), raw.slice(slash + 1));
+    }
+    const kind = osmType.trim().toLowerCase();
+    if (!PLACE_TYPES.has(kind)) {
+        throw appError(400, 'invalid_place_id', 'osm_type must be node, way, or relation');
+    }
+    const n = typeof osmId === 'number' ? osmId : Number.parseInt(String(osmId).trim(), 10);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw appError(400, 'invalid_place_id', 'osm_id must be a positive integer');
+    }
+    return { osmType: kind, osmId: n };
+}
+function placesSearchBody(params) {
+    const body = { limit: params.limit ?? 100 };
+    if (params.bbox != null) {
+        body['bbox'] = params.bbox;
+    }
+    if (params.location != null) {
+        body['location'] = latlng(params.location);
+    }
+    if (params.radius != null) {
+        body['radius'] = params.radius;
+    }
+    if (params.type != null) {
+        body['type'] = params.type;
+    }
+    if (params.tags?.length) {
+        body['tags'] = params.tags;
+    }
+    if (params.orTags?.length) {
+        body['orTags'] = params.orTags;
+    }
+    if (params.openNow) {
+        body['openNow'] = true;
+    }
+    if (params.asOf != null) {
+        body['asOf'] = params.asOf;
+    }
+    return body;
+}
+function placesNearbyBody(params) {
+    const body = {
+        location: latlng(params.location),
+        radius: params.radius ?? 1000,
+        limit: params.limit ?? 10,
+    };
+    if (params.type != null) {
+        body['type'] = params.type;
+    }
+    if (params.tags?.length) {
+        body['tags'] = params.tags;
+    }
+    if (params.orTags?.length) {
+        body['orTags'] = params.orTags;
+    }
+    if (params.openNow) {
+        body['openNow'] = true;
+    }
+    if (params.asOf != null) {
+        body['asOf'] = params.asOf;
+    }
+    return body;
+}
+function routesIsochroneBody(params) {
+    const body = {
+        origin: lonlat(params.origin),
+        travelMode: params.travelMode ?? 'WALK',
+    };
+    if (params.maxDistanceM != null) {
+        body['max_distance_m'] = params.maxDistanceM;
+    }
+    if (params.durationS != null) {
+        body['duration_s'] = params.durationS;
+    }
+    if (params.searchBufferM != null) {
+        body['search_buffer_m'] = params.searchBufferM;
+    }
+    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;
+    }
+    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.searchBufferM != null) {
+        body['search_buffer_m'] = params.searchBufferM;
+    }
+    return body;
+}
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -262,7 +387,8 @@ export class OSMFeatures {
             limit: parseLimit(query),
             cursor: optionalString(query, 'cursor'),
             zoom: optionalNumber(query, 'zoom'),
-            around: optionalString(query, 'around'),
+            location: optionalString(query, 'location'),
+            radius: optionalNumber(query, 'radius'),
             osmIds: optionalString(query, 'osm_ids'),
             minLengthM: optionalNumber(query, 'min_length_m'),
             maxLengthM: optionalNumber(query, 'max_length_m'),
@@ -270,6 +396,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) {
@@ -283,25 +410,15 @@ export class OSMFeatures {
         err.upstreamDetail = upstreamDetail;
         throw err;
     }
-    /** Single HTTP request with retry. Throws on non-OK (same role as Python `_raw_query`). */
-    async _rawQuery(params, fetchFn, sleepFn, nowFn) {
-        const query = buildFeaturesQuery(params);
-        const upstreamUrl = new URL(`${this.apiBaseUrl}/v2/osm_features`);
-        for (const [key, value] of query.entries()) {
-            upstreamUrl.searchParams.append(key, value);
-        }
-        let upstream;
+    /** GET/POST with 429 retry. Throws on non-OK. */
+    async _fetchOk(url, init, fetchFn, sleepFn, nowFn) {
         let retryAttempt = 0;
         while (true) {
+            let upstream;
             try {
-                upstream = await fetchFn(upstreamUrl.toString(), {
-                    method: 'GET',
-                    headers: {
-                        Authorization: `Bearer ${this.apiKey}`,
-                        Accept: params.accept || GEOJSON_ACCEPT,
-                        'User-Agent': 'osmfeatures',
-                    },
-                    signal: AbortSignal.timeout(this.timeoutMs),
+                upstream = await fetchFn(url, {
+                    ...init,
+                    signal: init.signal ?? AbortSignal.timeout(this.timeoutMs),
                 });
             }
             catch (error) {
@@ -313,7 +430,7 @@ export class OSMFeatures {
                 throw err;
             }
             if (upstream.ok) {
-                break;
+                return upstream;
             }
             if (upstream.status === 429 && retryAttempt < this.retryAttempts) {
                 retryAttempt += 1;
@@ -335,11 +452,60 @@ 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;
             }
             await this.throwUpstreamError(upstream);
         }
+    }
+    /** POST JSON to a geo-agent path. */
+    async _postJson(path, body, fetchFn, sleepFn, nowFn) {
+        const upstream = await this._fetchOk(`${this.apiBaseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                'User-Agent': 'osmfeatures',
+            },
+            body: JSON.stringify(body),
+        }, fetchFn, sleepFn, nowFn);
+        return (await upstream.json());
+    }
+    /** GET JSON from a geo-agent or account path. */
+    async _getJson(path, query, fetchFn, sleepFn, nowFn) {
+        const url = new URL(`${this.apiBaseUrl}${path}`);
+        const entries = query instanceof URLSearchParams ? query.entries() : Object.entries(query);
+        for (const [key, value] of entries) {
+            url.searchParams.append(key, value);
+        }
+        const upstream = await this._fetchOk(url.toString(), {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                Accept: 'application/json',
+                'User-Agent': 'osmfeatures',
+            },
+        }, fetchFn, sleepFn, nowFn);
+        return (await upstream.json());
+    }
+    /** Single HTTP request with retry. Throws on non-OK (same role as Python `_raw_query`). */
+    async _rawQuery(params, fetchFn, sleepFn, nowFn) {
+        const query = buildFeaturesQuery(params);
+        const upstreamUrl = new URL(`${this.apiBaseUrl}/v2/osm_features`);
+        for (const [key, value] of query.entries()) {
+            upstreamUrl.searchParams.append(key, value);
+        }
+        const upstream = await this._fetchOk(upstreamUrl.toString(), {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                Accept: params.accept || GEOJSON_ACCEPT,
+                'User-Agent': 'osmfeatures',
+            },
+        }, fetchFn, sleepFn, nowFn);
         if (isGeojsonAccept(params.accept)) {
             const body = (await upstream.json());
             const features = Array.isArray(body.features) ? body.features : [];
@@ -352,7 +518,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, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
         const payload = await this._rawQuery({
             bbox,
             tags,
@@ -363,7 +529,8 @@ export class OSMFeatures {
             limit,
             cursor,
             zoom,
-            around,
+            location,
+            radius,
             osmIds,
             minLengthM,
             maxLengthM,
@@ -371,12 +538,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, location, radius, 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.');
         }
@@ -387,7 +555,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 = splitBbox(bbox, bboxTiles);
+        const tileBboxes = bbox ? splitBbox(bbox, bboxTiles) : [undefined];
         const allFeatures = [];
         let pageCount = 0;
         let lastPage = null;
@@ -405,7 +573,8 @@ export class OSMFeatures {
             shape,
             limit: limitPerPage,
             zoom,
-            around,
+            location,
+            radius,
             osmIds,
             minLengthM,
             maxLengthM,
@@ -413,6 +582,7 @@ export class OSMFeatures {
             maxAreaM2,
             disableBudgetWarning,
             centroid,
+            clipGeometry,
         };
         for (const tileBbox of tileBboxes) {
             if (allFeatures.length >= featureCap) {
@@ -492,6 +662,58 @@ export class OSMFeatures {
         }
         return resultFromFeatures(features, meta);
     }
+    /** Preflight credit cost (``GET /v2/osm_features/cost``). */
+    async estimate_cost(params = {}, dependencies = {}) {
+        return this._getJson('/v2/osm_features/cost', buildFeaturesQuery({
+            bbox: params.bbox,
+            tags: params.tags,
+            orTags: params.orTags,
+            notTags: params.notTags,
+            type: params.type,
+            shape: params.shape,
+            limit: params.limit ?? DEFAULT_LIMIT,
+            zoom: params.zoom,
+            location: params.location,
+            radius: params.radius,
+            osmIds: params.osmIds,
+            minLengthM: params.minLengthM,
+            maxLengthM: params.maxLengthM,
+            minAreaM2: params.minAreaM2,
+            maxAreaM2: params.maxAreaM2,
+            disableBudgetWarning: params.disableBudgetWarning,
+            centroid: params.centroid,
+            clipGeometry: params.clipGeometry,
+        }), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
+    }
+    /** This month's unit-budget usage (``GET /v1/usage``). */
+    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``). */
+    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``). */
+    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}``). */
+    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);
+    }
+    /** Reach polygon along the walk/bike network (``POST /v1/routes/isochrone``). */
+    async routes_isochrone(params, dependencies = {}) {
+        return this._postJson('/v1/routes/isochrone', routesIsochroneBody(params), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
+    }
+    /** Given-order walk/bike path (``POST /v1/routes/path``). */
+    async routes_path(params, dependencies = {}) {
+        return this._postJson('/v1/routes/path', routesPathBody(params), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
+    }
+    /** TSP walk/bike tour from ``start`` (``POST /v1/routes/optimized_path``). ``loop`` returns to start. */
+    async routes_optimized_path(params, dependencies = {}) {
+        return this._postJson('/v1/routes/optimized_path', routesOptimizedPathBody(params), dependencies.fetchFn ?? fetch, dependencies.sleepFn ?? sleep, dependencies.nowFn ?? Date.now);
+    }
 }
 export * from './geojson-feature.js';
 export * from './preset/index.js';

package/dist/preset/catalog.js

@@ -37,6 +37,7 @@ export const OSM_FEATURES_LAYER_PRESETS = {
             'amenity=pub',
             'amenity=biergarten',
         ],
+        shape: 'polygon',
     },
     shops_commerce: {
         id: 'shops_commerce',

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.2.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",
   "types": "./dist/index.d.ts",