Metadata-Version: 2.4
Name: osmgeojson
Version: 0.2.0
Summary: Python SDK for the MapLark OSM GeoJSON API to query OpenStreetMap data easily.
Project-URL: Homepage, https://maplark.com
Project-URL: Repository, https://github.com/MapLark/osmgeojson-python
License: MIT
License-File: LICENSE
Keywords: geojson,geospatial,maps,openstreetmap,osm
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

# OSMGeoJSON API

This API keeps OpenStreetMap semantics intact and returns GeoJSON FeatureCollections you can feed straight into Leaflet, MapLibre, OpenLayers, or any geospatial toolchain. All you need to do is specify a bounding box and geometry types. 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, bounding box chunking, retry/backoff, pandas/geopandas output, async support, and convenience methods to get common OSM data such as buildings, amenities, bike roads, etc. 

```
pip install osmgeojson
pip install "osmgeojson[geo]"   # pandas / geopandas / shapely support
```

The SDK talks to `api.maplark.com` by default.

## Quick start

```python
from osmgeojson import OSMGeoJSONClient

with OSMGeoJSONClient(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 osmgeojson import OSMGeoJSONClient

client = OSMGeoJSONClient(api_key="sk-...")
```

You can use the client directly and close it when done, or use a context manager:

```python
from osmgeojson import OSMGeoJSONClient

with OSMGeoJSONClient(api_key="sk-...") as client:
    ...
```



### 2) Query OSM elements

`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 `meta.next_cursor` from previous page)



### 3) Auto-pagination

Use `query_all()` to fetch all pages and deduplicate by OSM feature id:

```python
all_restaurants = client.query_all(
    bbox="18.063,59.322,18.082,59.332",
    tags="amenity=restaurant",
    page_size=1000,
)

print(all_restaurants.meta.returned)
```



### 4) Async client

Async methods mirror the sync API (`query_async`, `query_all_async`, `query_large_area_async`):

```python
import asyncio
from osmgeojson import AsyncOSMGeoJSONClient


async def main() -> None:
    async with AsyncOSMGeoJSONClient(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 osmgeojson import OSMGeoJSONClient, get_buildings, get_restaurants

with OSMGeoJSONClient(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 `osmgeojson`:

```bash
export MAPLARK_API_KEY="sk-..."
osmgeojson query --bbox "18.063,59.322,18.082,59.332" --tags building --type way
```



## 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
```

