osmfeatures 0.1.0__tar.gz

osmfeatures-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,11 @@
+# Copilot Instructions for osmgeojson-python
+
+Always-on baseline for this repository.
+
+MapLark is a self-hosted GeoJSON API over OpenStreetMap data, backed by PostGIS and served via FastAPI.
+
+- Keep changes minimal and backward compatible unless a task explicitly asks for breaking changes.
+- Prefer strong typing and mypy-compatible changes.
+- Keep sync and async client behavior aligned for equivalent features.
+- Prefer deterministic tests with mocked HTTP over live network calls.
+- Treat `.github/instructions/*.instructions.md` as the source of detailed, file-specific rules.

osmfeatures-0.1.0/.github/instructions/osmgeojson-python-conventions.instructions.md

@@ -0,0 +1,15 @@
+---
+description: "Use when editing Python code in osmgeojson (SDK, tests, or examples). Prefer strict typing, sync/async parity, and deterministic tests unless the task requires an exception."
+name: "OSMGeoJSON Python Conventions"
+applyTo: "**/*.py"
+---
+# OSMGeoJSON Python Conventions
+
+- Prefer complete type hints that remain compatible with strict mypy checks.
+- Prefer preserving public API compatibility unless the task explicitly requests a breaking change.
+- When adding or changing request parameters in the sync client, prefer mirroring the behavior in the async client unless there is a documented reason not to.
+- Prefer routing HTTP retries and rate-limit handling through shared retry/http helpers instead of duplicating retry logic in client methods.
+- For pagination or chunking changes, preserve deduplication-by-id behavior and existing guardrails against stale offsets.
+- For tests that exercise HTTP flows, prefer mocked HTTP requests (for example with `responses`) and avoid live network calls.
+- Add or update tests for behavioral changes, including both success and error paths when practical.
+- Keep docstrings user-focused: include parameter semantics and API-specific constraints rather than generic restatements.

osmfeatures-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+dist
+.env
+.env.deploy
+__pycache__/
+.pytest_cache/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+ENV/
+*.log
+.DS_Store
+cache/

osmfeatures-0.1.0/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.

osmfeatures-0.1.0/Makefile

@@ -0,0 +1,15 @@
+SHELL := /bin/bash
+
+VENV_DIR := $(CURDIR)/.venv
+VENV_PY := $(VENV_DIR)/bin/python3
+VENV_PIP := $(VENV_DIR)/bin/pip
+setup:
+	python3 -m venv $(VENV_DIR)
+	source $(VENV_DIR)/bin/activate
+	$(VENV_PIP) install -e ".[all,test]"
+
+test: setup
+	$(VENV_PY) -m pytest tests/ -v
+
+clean:
+	rm -rf $(VENV_DIR)

osmfeatures-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: osmfeatures
+Version: 0.1.0
+Summary: Official client for the MapLark OSM Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV)
+Project-URL: Homepage, https://maplark.com
+Project-URL: Repository, https://github.com/MapLark/osmfeatures-python
+License: MIT
+License-File: LICENSE
+Keywords: flatgeobuf,geojson,geoparquet,geospatial,maplark,maps,openstreetmap,osm,overpass
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: geojson>=3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: requests>=2.28
+Provides-Extra: all
+Requires-Dist: geopandas>=0.14; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Requires-Dist: shapely>=2.0; extra == 'all'
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.14; extra == 'geo'
+Requires-Dist: pandas>=2.0; extra == 'geo'
+Requires-Dist: shapely>=2.0; extra == 'geo'
+Provides-Extra: test
+Requires-Dist: haversine>=2.8; extra == 'test'
+Requires-Dist: networkx>=3.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Requires-Dist: python-dotenv>=1.0; extra == 'test'
+Requires-Dist: responses>=0.25; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MapLark OSM Features API
+
+Query OpenStreetMap features such as buildings, streets, and Points of Interest 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` - GeoJSON 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).
+
+## Python SDK
+
+This client library comes with auto-pagination, bbox tiling (enables larger bbox queries), retry/backoff, pandas/geopandas output, async support, and convenience methods to get common OSM data such as buildings, amenities, bike roads, etc. 
+
+```
+pip install osmfeatures
+pip install "osmfeatures[geo]"   # pandas / geopandas / shapely support
+```
+
+Official client for the MapLark OSM Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV).
+The SDK talks to `api.maplark.com` by default.
+
+## Quick start
+
+```python
+from osmfeatures import OSMFeaturesClient
+
+with OSMFeaturesClient(api_key="sk-...") as client:
+    fc = client.query(bbox="18.06,59.32,18.09,59.34", tags=["building"])
+    print(len(fc.features), "buildings found")
+```
+
+
+
+## Basic API usage
+
+
+
+### 1) Create a client
+
+```python
+from osmfeatures import OSMFeaturesClient
+
+client = OSMFeaturesClient(api_key="sk-...")
+```
+
+You can use the client directly and close it when done, or use a context manager:
+
+```python
+from osmfeatures import OSMFeaturesClient
+
+with OSMFeaturesClient(api_key="sk-...") as client:
+    ...
+```
+
+
+
+### 2) Query OSM features
+
+`query()` fetches a single page:
+
+```python
+fc = client.query(
+    bbox="18.063,59.322,18.082,59.332",
+    type="way",
+    shape="line",
+    tags=["highway=cycleway"],
+    limit=500,
+)
+
+for feature in fc.features:
+    print(feature["id"], feature["geometry"]["type"], feature.tags)
+```
+
+Common filters:
+
+- `bbox="min_lon,min_lat,max_lon,max_lat"`
+- `around="lon,lat,radius_m"`
+- `tags=["amenity=restaurant"]` (AND)
+- `or_tags=["bicycle=yes", "bicycle=designated"]` (OR)
+- `not_tags=["access=private"]` (exclude)
+- `type="node" | "way" | "relation"`
+- `shape="polygon" | "line" | "all"` (omit = both shapes; `all` also means both)
+- `cursor` (pagination; use SDK `meta.next_cursor` from previous page, sourced from `X-Next-Cursor`)
+
+
+
+### 3) Auto-pagination and bbox tiling
+
+Use `query_all()` to fetch all pages and deduplicate by OSM feature id. By default it splits the bbox into 2 tiles (power of 2) so large areas use more requests; pass `bbox_tiles=1` to disable, or raise it (`4`, `8`, …) for bigger areas:
+
+```python
+all_restaurants = client.query_all(
+    bbox="18.063,59.322,18.082,59.332",
+    tags="amenity=restaurant",
+    limit_per_page=1000,  # page size per HTTP request
+    max_features=55_000,  # total cap; pass None for no cap
+    bbox_tiles=2,  # default
+)
+
+print(all_restaurants.meta.returned)
+```
+
+
+
+### 4) Async client
+
+Async methods mirror the sync API (`query_async`, `query_all_async`):
+
+```python
+import asyncio
+from osmfeatures import AsyncOSMFeaturesClient
+
+
+async def main() -> None:
+    async with AsyncOSMFeaturesClient(api_key="sk-...") as client:
+        fc = await client.query_async(
+            bbox="18.06,59.32,18.09,59.34",
+            tags=["building"],
+        )
+        print(len(fc.features))
+
+
+asyncio.run(main())
+```
+
+
+
+### 5) Convenience helpers
+
+For common datasets, use convenience methods built on top of `query_all()`:
+
+```python
+from osmfeatures import OSMFeaturesClient, get_buildings, get_restaurants
+
+with OSMFeaturesClient(api_key="sk-...") as client:
+    buildings = get_buildings(client, bbox="18.063,59.322,18.082,59.332")
+    restaurants = get_restaurants(client, bbox="18.063,59.322,18.082,59.332")
+    print(len(buildings.features), len(restaurants.features))
+```
+
+
+
+### 6) Cost and usage
+
+```python
+estimate = client.estimate_cost(
+    bbox="18.063,59.322,18.082,59.332",
+    tags=["building"],
+)
+print("estimated credits:", estimate.estimated_credits)
+
+usage = client.usage()
+print("Usage:", usage)
+```
+
+
+
+### 7) CLI usage
+
+If the package is installed, the CLI is available as `osmfeatures`:
+
+```bash
+export MAPLARK_API_KEY="sk-..."
+osmfeatures query --bbox "18.063,59.322,18.082,59.332" --tags building --type way
+osmfeatures query --bbox "18.063,59.322,18.082,59.332" --tags building --all-pages --bbox-tiles 4
+```
+
+
+
+## Example apps
+
+The repository includes runnable example-app tests in `tests/example_apps/` showing end-to-end usage patterns against real OSM data.
+
+- `test_restaurant_guide.py`: restaurant discovery list with names/cuisines and map coordinates.
+- `test_park_bench_finder.py`: bench finder for park maps (`amenity=bench`).
+- `test_park_explorer.py`: park browser with polygon boundaries, centroids, and area estimates.
+- `test_cycling_trails.py`: unpaved cycling trail layer for MTB/gravel planning.
+- `test_city_cycling_infrastructure.py`: city cycling overlay combining cycleways and bike lanes.
+- `test_lakeside_ice_cream_hunt.py`: nearest ice cream shops to waterfront edges.
+- `test_pedestrian_shortest_path.py`: shortest walking route via graph + Dijkstra.
+- `test_pedestrian_wavefront_bfs.py`: hop-based accessibility rings via BFS.
+- `test_bike_path_dijkstra_liljeholmen_to_djurgarden.py`: tiled corridor bike routing from Liljeholmen to Djurgarden.
+- `test_geometry_filters.py`: zoom + area/length filters for large buildings and long roads.
+
+Run all example apps:
+
+```bash
+pytest tests/example_apps -v
+```
+
+Run one example app:
+
+```bash
+pytest tests/example_apps/test_restaurant_guide.py -v
+```
+

osmfeatures-0.1.0/README.md

@@ -0,0 +1,213 @@
+# MapLark OSM Features API
+
+Query OpenStreetMap features such as buildings, streets, and Points of Interest 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` - GeoJSON 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).
+
+## Python SDK
+
+This client library comes with auto-pagination, bbox tiling (enables larger bbox queries), retry/backoff, pandas/geopandas output, async support, and convenience methods to get common OSM data such as buildings, amenities, bike roads, etc. 
+
+```
+pip install osmfeatures
+pip install "osmfeatures[geo]"   # pandas / geopandas / shapely support
+```
+
+Official client for the MapLark OSM Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV).
+The SDK talks to `api.maplark.com` by default.
+
+## Quick start
+
+```python
+from osmfeatures import OSMFeaturesClient
+
+with OSMFeaturesClient(api_key="sk-...") as client:
+    fc = client.query(bbox="18.06,59.32,18.09,59.34", tags=["building"])
+    print(len(fc.features), "buildings found")
+```
+
+
+
+## Basic API usage
+
+
+
+### 1) Create a client
+
+```python
+from osmfeatures import OSMFeaturesClient
+
+client = OSMFeaturesClient(api_key="sk-...")
+```
+
+You can use the client directly and close it when done, or use a context manager:
+
+```python
+from osmfeatures import OSMFeaturesClient
+
+with OSMFeaturesClient(api_key="sk-...") as client:
+    ...
+```
+
+
+
+### 2) Query OSM features
+
+`query()` fetches a single page:
+
+```python
+fc = client.query(
+    bbox="18.063,59.322,18.082,59.332",
+    type="way",
+    shape="line",
+    tags=["highway=cycleway"],
+    limit=500,
+)
+
+for feature in fc.features:
+    print(feature["id"], feature["geometry"]["type"], feature.tags)
+```
+
+Common filters:
+
+- `bbox="min_lon,min_lat,max_lon,max_lat"`
+- `around="lon,lat,radius_m"`
+- `tags=["amenity=restaurant"]` (AND)
+- `or_tags=["bicycle=yes", "bicycle=designated"]` (OR)
+- `not_tags=["access=private"]` (exclude)
+- `type="node" | "way" | "relation"`
+- `shape="polygon" | "line" | "all"` (omit = both shapes; `all` also means both)
+- `cursor` (pagination; use SDK `meta.next_cursor` from previous page, sourced from `X-Next-Cursor`)
+
+
+
+### 3) Auto-pagination and bbox tiling
+
+Use `query_all()` to fetch all pages and deduplicate by OSM feature id. By default it splits the bbox into 2 tiles (power of 2) so large areas use more requests; pass `bbox_tiles=1` to disable, or raise it (`4`, `8`, …) for bigger areas:
+
+```python
+all_restaurants = client.query_all(
+    bbox="18.063,59.322,18.082,59.332",
+    tags="amenity=restaurant",
+    limit_per_page=1000,  # page size per HTTP request
+    max_features=55_000,  # total cap; pass None for no cap
+    bbox_tiles=2,  # default
+)
+
+print(all_restaurants.meta.returned)
+```
+
+
+
+### 4) Async client
+
+Async methods mirror the sync API (`query_async`, `query_all_async`):
+
+```python
+import asyncio
+from osmfeatures import AsyncOSMFeaturesClient
+
+
+async def main() -> None:
+    async with AsyncOSMFeaturesClient(api_key="sk-...") as client:
+        fc = await client.query_async(
+            bbox="18.06,59.32,18.09,59.34",
+            tags=["building"],
+        )
+        print(len(fc.features))
+
+
+asyncio.run(main())
+```
+
+
+
+### 5) Convenience helpers
+
+For common datasets, use convenience methods built on top of `query_all()`:
+
+```python
+from osmfeatures import OSMFeaturesClient, get_buildings, get_restaurants
+
+with OSMFeaturesClient(api_key="sk-...") as client:
+    buildings = get_buildings(client, bbox="18.063,59.322,18.082,59.332")
+    restaurants = get_restaurants(client, bbox="18.063,59.322,18.082,59.332")
+    print(len(buildings.features), len(restaurants.features))
+```
+
+
+
+### 6) Cost and usage
+
+```python
+estimate = client.estimate_cost(
+    bbox="18.063,59.322,18.082,59.332",
+    tags=["building"],
+)
+print("estimated credits:", estimate.estimated_credits)
+
+usage = client.usage()
+print("Usage:", usage)
+```
+
+
+
+### 7) CLI usage
+
+If the package is installed, the CLI is available as `osmfeatures`:
+
+```bash
+export MAPLARK_API_KEY="sk-..."
+osmfeatures query --bbox "18.063,59.322,18.082,59.332" --tags building --type way
+osmfeatures query --bbox "18.063,59.322,18.082,59.332" --tags building --all-pages --bbox-tiles 4
+```
+
+
+
+## Example apps
+
+The repository includes runnable example-app tests in `tests/example_apps/` showing end-to-end usage patterns against real OSM data.
+
+- `test_restaurant_guide.py`: restaurant discovery list with names/cuisines and map coordinates.
+- `test_park_bench_finder.py`: bench finder for park maps (`amenity=bench`).
+- `test_park_explorer.py`: park browser with polygon boundaries, centroids, and area estimates.
+- `test_cycling_trails.py`: unpaved cycling trail layer for MTB/gravel planning.
+- `test_city_cycling_infrastructure.py`: city cycling overlay combining cycleways and bike lanes.
+- `test_lakeside_ice_cream_hunt.py`: nearest ice cream shops to waterfront edges.
+- `test_pedestrian_shortest_path.py`: shortest walking route via graph + Dijkstra.
+- `test_pedestrian_wavefront_bfs.py`: hop-based accessibility rings via BFS.
+- `test_bike_path_dijkstra_liljeholmen_to_djurgarden.py`: tiled corridor bike routing from Liljeholmen to Djurgarden.
+- `test_geometry_filters.py`: zoom + area/length filters for large buildings and long roads.
+
+Run all example apps:
+
+```bash
+pytest tests/example_apps -v
+```
+
+Run one example app:
+
+```bash
+pytest tests/example_apps/test_restaurant_guide.py -v
+```
+

osmfeatures-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "osmfeatures"
+version = "0.1.0"
+description = "Official client for the MapLark OSM Features API (GeoJSON, FlatGeobuf, GeoParquet, CSV)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["openstreetmap", "osm", "geojson", "flatgeobuf", "geoparquet", "overpass", "maplark", "geospatial", "maps"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.28",
+    "httpx>=0.27",
+    "click>=8.1",
+    "geojson>=3.0",
+]
+
+[project.optional-dependencies]
+geo = [
+    "pandas>=2.0",
+    "geopandas>=0.14",
+    "shapely>=2.0",
+]
+all = ["pandas>=2.0", "geopandas>=0.14", "shapely>=2.0"]
+test = [
+    "pytest>=7.0",
+    "responses>=0.25",
+    "pytest-asyncio>=0.23",
+    "networkx>=3.0",
+    "haversine>=2.8",
+    "python-dotenv>=1.0",
+]
+
+[project.scripts]
+osmfeatures = "osmfeatures.cli:cli"
+
+[project.urls]
+Homepage = "https://maplark.com"
+Repository = "https://github.com/MapLark/osmfeatures-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/osmfeatures"]
+include = ["src/osmfeatures/py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true