osmfeatures 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MapLark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# MapLark OSM Features API client
+
+Official TypeScript/JavaScript client for the [MapLark OSM Features API](https://maplark.com) (GeoJSON, FlatGeobuf, GeoParquet, CSV). 
+
+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.
+
+The translation layer is very simple:
+
+- `node` - GIS Point
+- `way` - LineString or Polygon
+- `relation` - MultiPolygon or grouped geometries
+
+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:
+
+- `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).
+
+For example, to get all buildings in an area:
+
+`type=way & tags=building`
+
+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
+
+```bash
+# From npm (when published):
+npm install osmfeatures
+
+# Until then, from git:
+npm install git+https://github.com/MapLark/osmfeatures-ts.git
+```
+
+```ts
+import { OSMFeatures } from 'osmfeatures';
+
+const client = new OSMFeatures('sk-...');
+const page = await client.query({
+  bbox: '18.06,59.32,18.09,59.34',
+  tags: ['building'],
+});
+
+// Vanilla GeoJSON FeatureCollection (same shape as the HTTP body).
+map.getSource('buildings').setData(page.data);
+console.log(page.data.features.length);
+
+// Header-derived meta (not part of GeoJSON): 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.
+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);
+```
+
+Talks to `https://api.maplark.com` by default.
+
+Also exports layer presets (`resolveLayerFromQuery`, `OSM_FEATURES_LAYER_PRESETS`, …)
+and GeoJSON payload helpers (`featureCentroid`, `geometryBounds`, `parseFeatureId`, …).

package/dist/geojson-feature.d.ts

@@ -0,0 +1,25 @@
+/** Helpers for MapLark OSM Features API GeoJSON payloads. */
+export type GeometryGroupId = 'points' | 'lines' | 'polygons';
+export type GeoJSONGeometryLike = {
+    type: string;
+    coordinates?: unknown;
+} | null;
+export type QueryFeatureLike = {
+    id?: string | number;
+    properties?: Record<string, unknown>;
+    geometry: GeoJSONGeometryLike;
+};
+export declare function geometryGroup(geometryType: string): GeometryGroupId | null;
+export declare function parseFeatureId(id: string | number | undefined): {
+    type: string;
+    osmId: string;
+};
+export declare function readTags(properties: Record<string, unknown> | undefined): Record<string, unknown>;
+/** `[[minLon, minLat], [maxLon, maxLat]]`, or null when the geometry has no coordinates. */
+export declare function geometryBounds(geometry: GeoJSONGeometryLike): [[number, number], [number, number]] | null;
+/**
+ * Feature center as `[lon, lat]`.
+ * Non-points: `properties.centroid` from PostGIS (`centroid=true`).
+ * Points: the Point coordinates themselves (API omits centroid on nodes).
+ */
+export declare function featureCentroid(feature: QueryFeatureLike): [number, number] | null;

package/dist/geojson-feature.js

@@ -0,0 +1,108 @@
+/** Helpers for MapLark OSM Features API GeoJSON payloads. */
+export function geometryGroup(geometryType) {
+    if (geometryType === 'Point' || geometryType === 'MultiPoint') {
+        return 'points';
+    }
+    if (geometryType === 'LineString' || geometryType === 'MultiLineString') {
+        return 'lines';
+    }
+    if (geometryType === 'Polygon' || geometryType === 'MultiPolygon') {
+        return 'polygons';
+    }
+    return null;
+}
+export function parseFeatureId(id) {
+    if (typeof id === 'number' && Number.isFinite(id)) {
+        return { type: '', osmId: String(id) };
+    }
+    if (typeof id !== 'string' || id.trim() === '') {
+        return { type: '', osmId: '' };
+    }
+    const slash = id.indexOf('/');
+    if (slash <= 0 || slash === id.length - 1) {
+        return { type: '', osmId: id };
+    }
+    return { type: id.slice(0, slash), osmId: id.slice(slash + 1) };
+}
+export function readTags(properties) {
+    const tags = properties?.['tags'];
+    if (tags && typeof tags === 'object' && !Array.isArray(tags)) {
+        return tags;
+    }
+    if (typeof tags === 'string') {
+        try {
+            const parsed = JSON.parse(tags);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function collectPositions(coordinates, out) {
+    if (!Array.isArray(coordinates) || coordinates.length === 0) {
+        return;
+    }
+    if (typeof coordinates[0] === 'number') {
+        out.push(coordinates);
+        return;
+    }
+    for (const item of coordinates) {
+        collectPositions(item, out);
+    }
+}
+/** `[[minLon, minLat], [maxLon, maxLat]]`, or null when the geometry has no coordinates. */
+export function geometryBounds(geometry) {
+    const positions = [];
+    collectPositions(geometry?.coordinates, positions);
+    if (positions.length === 0) {
+        return null;
+    }
+    let minLon = Infinity;
+    let minLat = Infinity;
+    let maxLon = -Infinity;
+    let maxLat = -Infinity;
+    for (const [lon, lat] of positions) {
+        if (lon < minLon)
+            minLon = lon;
+        if (lon > maxLon)
+            maxLon = lon;
+        if (lat < minLat)
+            minLat = lat;
+        if (lat > maxLat)
+            maxLat = lat;
+    }
+    return [[minLon, minLat], [maxLon, maxLat]];
+}
+/**
+ * Feature center as `[lon, lat]`.
+ * Non-points: `properties.centroid` from PostGIS (`centroid=true`).
+ * Points: the Point coordinates themselves (API omits centroid on nodes).
+ */
+export function featureCentroid(feature) {
+    const group = geometryGroup(feature.geometry?.type?.trim() ?? '');
+    if (group === 'points') {
+        const coords = feature.geometry?.coordinates;
+        if (feature.geometry?.type === 'Point' && Array.isArray(coords) && typeof coords[0] === 'number') {
+            return [coords[0], coords[1]];
+        }
+        if (feature.geometry?.type === 'MultiPoint' && Array.isArray(coords) && coords.length === 1) {
+            const point = coords[0];
+            if (typeof point?.[0] === 'number') {
+                return [point[0], point[1]];
+            }
+        }
+        return null;
+    }
+    const centroid = feature.properties?.['centroid'];
+    if (centroid && typeof centroid === 'object' && !Array.isArray(centroid)) {
+        const coords = centroid.coordinates;
+        if (Array.isArray(coords) && typeof coords[0] === 'number' && typeof coords[1] === 'number') {
+            return [coords[0], coords[1]];
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/** Response metadata from headers (not part of GeoJSON body). */
+export type OSMFeaturesMeta = {
+    returned: number;
+    has_more: boolean;
+    next_cursor: string | null;
+    /** From ``X-Usage-Units-Charged`` when present (authenticated API). */
+    units_charged?: number;
+    /** Set by ``query_all`` only (pages fetched). */
+    page_count?: number;
+    relay_partial?: boolean;
+    relay_partial_reason?: string;
+};
+/** Wire GeoJSON FeatureCollection (no pagination fields). */
+export type OSMGeoJSONPayload = {
+    type: 'FeatureCollection';
+    features: unknown[];
+};
+/** GeoJSON page: FeatureCollection body + header-derived meta. */
+export type OSMGeoJSONResult = {
+    data: OSMGeoJSONPayload;
+    meta: OSMFeaturesMeta;
+};
+/** Any Accept: GeoJSON page, or raw bytes in ``data`` for binary encodings. */
+export type OSMFeaturesResult = {
+    data: OSMGeoJSONPayload | ArrayBuffer;
+    meta: OSMFeaturesMeta;
+};
+/** Layer filters from presets / custom resolve. Pass into `resolveRequest` or spread into `query`. */
+export type OSMFeaturesLayer = {
+    bbox: string;
+    tags?: string[];
+    orTags?: string[];
+    notTags?: string[];
+    type?: string;
+    shape?: 'line' | 'polygon' | 'all';
+};
+/** Flat query params (same idea as Python `query(**params)`). */
+export type OSMFeaturesParams = OSMFeaturesLayer & {
+    limit?: number;
+    cursor?: string;
+    zoom?: number;
+    around?: string;
+    osmIds?: string;
+    minLengthM?: number;
+    maxLengthM?: number;
+    minAreaM2?: number;
+    maxAreaM2?: number;
+    disableBudgetWarning?: boolean;
+    centroid?: 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>;
+type OSMFeaturesDependencies = {
+    fetchFn?: typeof fetch;
+    sleepFn?: (ms: number) => Promise<void>;
+    nowFn?: () => number;
+};
+/** Parse `bbox_tiles` from a query map for `query_all` (client-side only). */
+export declare function resolveBboxTiles(query?: OSMFeaturesQuery, fallback?: number): number;
+/** Split bbox into `tileCount` tiles by repeated longest-side bisection. */
+export declare function splitBbox(bbox: string, tileCount: number): string[];
+export declare class OSMFeatures {
+    private readonly apiKey;
+    private readonly apiBaseUrl;
+    private readonly timeoutMs;
+    private readonly retryAttempts;
+    private readonly retryBaseMs;
+    private readonly retryMaxMs;
+    constructor(apiKey: string, { apiBaseUrl, timeoutMs, retryAttempts, retryBaseMs, retryMaxMs, }?: {
+        apiBaseUrl?: string;
+        timeoutMs?: number;
+        retryAttempts?: number;
+        retryBaseMs?: number;
+        retryMaxMs?: number;
+    });
+    /** Map Express/query params + resolved layer into flat `query` / `query_all` params. */
+    resolveRequest(query: OSMFeaturesQuery, layer: OSMFeaturesLayer): OSMFeaturesParams;
+    private throwUpstreamError;
+    /** 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>;
+    /** 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'> & {
+        /** Upstream `limit` per HTTP request (page size). */
+        limitPerPage?: number;
+        bboxTiles?: number;
+        maxPages?: number;
+        /** Cap on merged features. `null` = no cap. */
+        maxFeatures?: number | null;
+    }, dependencies?: OSMFeaturesDependencies): Promise<OSMGeoJSONResult>;
+}
+export * from './geojson-feature.js';
+export * from './preset/index.js';