osmfeatures 0.2.1 → 0.2.4

package/README.md

@@ -2,7 +2,7 @@
 
 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 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.
+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 translation layer is very simple:
 
@@ -12,11 +12,11 @@ The translation layer is very simple:
 
 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.
 
-To narrow down between "open ways" and "closed ways", use the `shape` parameter:
+To narrow down between "open ways" and "closed ways", use the `way_shape` parameter:
 
-- `shape=line` - open ways (roads, paths, rivers) or line-shaped relations (routes, boundaries)
-- `shape=polygon` - closed ways (buildings, parks) or multipolygon relations.
-- `shape=all` - both shapes (default when shape is omitted).
+- `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).
 
 For example, to get all buildings in an area:
 
@@ -102,7 +102,7 @@ Geometric filters such specific OSM element type, min length, or including centr
 | 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.                                           |
+| `wayShape`   | `line | polygon | all` | `all`   | Geometry class for ways and relations. `shape` is a deprecated alias.                   |
 | `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).                                                       |
@@ -168,7 +168,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`, `shape`, `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`, `osmIds`, `minLengthM`, `maxLengthM`, `minAreaM2`, `maxAreaM2`, `centroid`, `clipGeometry`, `disableBudgetWarning`), plus:
 
 
 | Param          | Type            | Default                | Description                                                                                                                                               |
@@ -221,9 +221,37 @@ const usage = await client.usage();
 console.log(usage.tier, usage.usage_this_month, usage.remaining_this_month);
 ```
 
-## `places_search` / `places_nearby` / `places_details`
+## Geo Agent (places and routes)
 
-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.
+`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.
+
+| 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. |
+
+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.
+
+#### Typical questions
+
+| 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`
 
 ```ts
 const origin = { lat: 59.316, lon: 18.075 };
@@ -250,9 +278,9 @@ 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`
+### Examples for `routes_isochrone` / `routes_path` / `routes_optimized_path`
 
-Walk or bicycle routing via `POST /v1/routes/*`. Points accept `lon` or `lng`.
+Points accept `lon` or `lng`. `routes_isochrone` takes exactly one of `maxDistanceM` or `durationS`. Optional `searchBufferM` widens the highway fetch corridor.
 
 ```ts
 const origin = { lon: 18.075, lat: 59.316 };
@@ -273,6 +301,4 @@ const tour = await client.routes_optimized_path({
 });
 ```
 
-`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

@@ -32,6 +32,8 @@ export type OSMFeaturesLayer = {
     orTags?: string[];
     notTags?: string[];
     type?: string;
+    wayShape?: 'line' | 'polygon' | 'all';
+    /** @deprecated Use `wayShape`. */
     shape?: 'line' | 'polygon' | 'all';
 };
 /** Flat query params (same idea as Python `query(**params)`). */
@@ -146,9 +148,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, 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, 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, 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, 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

@@ -189,8 +189,9 @@ function buildFeaturesQuery(params) {
     if (params.type) {
         query.set('type', params.type);
     }
-    if (params.shape) {
-        query.set('shape', params.shape);
+    const wayShape = params.wayShape ?? params.shape;
+    if (wayShape) {
+        query.set('way_shape', wayShape);
     }
     for (const tag of params.tags ?? []) {
         query.append('tags', tag);
@@ -518,13 +519,14 @@ 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, location, radius, osmIds, minLengthM, maxLengthM, minAreaM2, maxAreaM2, disableBudgetWarning, centroid, clipGeometry, accept, }, dependencies = {}) {
+    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 = {}) {
         const payload = await this._rawQuery({
             bbox,
             tags,
             orTags,
             notTags,
             type,
+            wayShape,
             shape,
             limit,
             cursor,
@@ -544,7 +546,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, 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, 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.');
         }
@@ -570,6 +572,7 @@ export class OSMFeatures {
             orTags,
             notTags,
             type,
+            wayShape,
             shape,
             limit: limitPerPage,
             zoom,
@@ -670,7 +673,7 @@ export class OSMFeatures {
             orTags: params.orTags,
             notTags: params.notTags,
             type: params.type,
-            shape: params.shape,
+            wayShape: params.wayShape ?? params.shape,
             limit: params.limit ?? DEFAULT_LIMIT,
             zoom: params.zoom,
             location: params.location,

package/dist/preset/catalog.d.ts

@@ -7,6 +7,8 @@ export type OSMFeaturesLayerPreset = {
     orTags?: string[];
     notTags?: string[];
     type?: string;
+    wayShape?: 'line' | 'polygon';
+    /** @deprecated Use `wayShape`. */
     shape?: 'line' | 'polygon';
 };
 export declare const OSM_FEATURES_LAYER_PRESETS: Record<OSMFeaturesPresetId, OSMFeaturesLayerPreset>;

package/dist/preset/catalog.js

@@ -4,14 +4,14 @@ export const OSM_FEATURES_LAYER_PRESETS = {
         label: 'Buildings',
         tags: ['building'],
         type: 'way,relation',
-        shape: 'polygon',
+        wayShape: 'polygon',
     },
     roads_paths: {
         id: 'roads_paths',
         label: 'Roads & paths',
         tags: ['highway'],
         type: 'way,relation',
-        shape: 'line',
+        wayShape: 'line',
     },
     parks_green_space: {
         id: 'parks_green_space',
@@ -37,7 +37,7 @@ export const OSM_FEATURES_LAYER_PRESETS = {
             'amenity=pub',
             'amenity=biergarten',
         ],
-        shape: 'polygon',
+        wayShape: 'polygon',
     },
     shops_commerce: {
         id: 'shops_commerce',
@@ -112,7 +112,7 @@ export const OSM_FEATURES_LAYER_PRESETS = {
             'waterway=ditch',
         ],
         type: 'way,relation',
-        shape: 'line',
+        wayShape: 'line',
     },
 };
 export const OSM_FEATURES_LAYER_PRESET_ORDER = [

package/dist/preset/resolve.d.ts

@@ -12,6 +12,8 @@ export type ResolvedCustomLayer = {
     orTags?: string[];
     notTags?: string[];
     type?: string;
+    wayShape?: 'line' | 'polygon' | 'all';
+    /** @deprecated Use `wayShape`. */
     shape?: 'line' | 'polygon' | 'all';
 };
 export type ResolvedDemoLayer = ResolvedPresetLayer | ResolvedCustomLayer;
@@ -24,7 +26,7 @@ export declare function getPreset(id: string): OSMFeaturesLayerPreset | undefine
 export declare function resolvePresetFromQuery(query: PresetQuery): ResolvedPresetLayer;
 /**
  * Custom layer: `tags` / `or_tags` / `not_tags` + required `bbox`.
- * Optional `type` / `shape`. Needs at least one positive filter (`tags` or `or_tags`).
+ * Optional `type` / `way_shape`. Needs at least one positive filter (`tags` or `or_tags`).
  */
 export declare function resolveCustomLayerFromQuery(query: PresetQuery): ResolvedCustomLayer;
 /**

package/dist/preset/resolve.js

@@ -91,7 +91,7 @@ export function resolvePresetFromQuery(query) {
 }
 /**
  * Custom layer: `tags` / `or_tags` / `not_tags` + required `bbox`.
- * Optional `type` / `shape`. Needs at least one positive filter (`tags` or `or_tags`).
+ * Optional `type` / `way_shape`. Needs at least one positive filter (`tags` or `or_tags`).
  */
 export function resolveCustomLayerFromQuery(query) {
     const tags = stringList(query, 'tags');
@@ -114,9 +114,9 @@ export function resolveCustomLayerFromQuery(query) {
     if (type) {
         layer.type = type;
     }
-    const shape = optionalString(query, 'shape');
-    if (shape === 'line' || shape === 'polygon' || shape === 'all') {
-        layer.shape = shape;
+    const wayShape = optionalString(query, 'way_shape') ?? optionalString(query, 'shape');
+    if (wayShape === 'line' || wayShape === 'polygon' || wayShape === 'all') {
+        layer.wayShape = wayShape;
     }
     return layer;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osmfeatures",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "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",
+    "test": "tsx src/index.test.ts && tsx src/geojson-feature.test.ts && tsx src/preset/preset.test.ts && tsx src/tutorial.test.ts",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },
@@ -36,7 +36,7 @@
   "homepage": "https://maplark.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/MapLark/osmfeatures-typescript.git"
+    "url": "https://github.com/MapLark/osmfeatures-ts.git"
   },
   "license": "MIT",
   "engines": {