tiny-osm 0.1.0

Fetch OpenStreetMap road, waterway, and water-body data for a bounding box.

TinyOSM: Lightweight OpenStreetMap GeoJSON Fetcher

Fetch OpenStreetMap data for a bounding box as GeoJSON. One function, one dependency, minimal footprint.

Why

OSMnx is the go-to tool for working with OpenStreetMap data in Python. It handles street-network analysis, building footprints, amenity lookups, graph-theoretic routing, and more. But it pulls in geopandas, shapely, and networkx, a heavy dependency stack, that can be slow to install in constrained environments like AWS Lambda, minimal Docker images, or CI runners.

tiny-osm exists for the narrower case where you just need OSM features as clean GeoJSON. It ships with presets for roads, waterways, and water bodies, and accepts any Overpass QL tag-filter for custom queries. It has one runtime dependency (httpx), installs in seconds, and returns standards-compliant GeoJSON that works with any downstream tool such as geopandas, shapely, or even a JavaScript map library.

	tiny-osm	osmnx
Dependencies	1 (httpx)	7+ (geopandas, shapely, networkx, ...)
Output format	GeoJSON dicts	GeoDataFrames/networkx graphs
Scope	Any Overpass tag-filter	Full OSM toolkit
API surface	1 function	Dozens of modules

Installation

pip install tiny-osm

Or with conda/pixi:

pixi add tiny-osm

Tip: If orjson is installed, tiny-osm uses it automatically for faster JSON parsing of Overpass API responses.

Usage

import tiny_osm

# Each call returns a GeoJSON FeatureCollection dict
bbox = (-97.75, 30.25, -97.70, 30.30)
highways = tiny_osm.fetch(*bbox, osm_filter=tiny_osm.OSMFilters.HIGHWAY)
waterways = tiny_osm.fetch(*bbox, osm_filter=tiny_osm.OSMFilters.WATERWAY)
water_bodies = tiny_osm.fetch(*bbox, osm_filter=tiny_osm.OSMFilters.WATER_BODY)

# Load into geopandas (optional - tiny-osm doesn't require it)
import geopandas as gpd

gdf = gpd.GeoDataFrame.from_features(highways, crs=4326)

# Custom Overpass QL filter
parks = tiny_osm.fetch(*bbox, osm_filter='["leisure"="park"]')

Filters

osm_filter	What it queries
OSMFilters.HIGHWAY	highway=* ways (excluding areas, abandoned, planned, raceway)
OSMFilters.WATERWAY	waterway=* ways
OSMFilters.WATER_BODY	Closed water features: ponds, lakes, reservoirs, detention/retention basins
any string	Raw Overpass QL tag-filter (e.g. '["amenity"="restaurant"]')

What it handles

• Auto-subdivides large bounding boxes into tiles
• Retries across multiple Overpass API mirrors with automatic failover
• Assembles multi-polygon relations (ring stitching, hole assignment)
• Deduplicates elements across tile boundaries
• Applies the OSM polygon-features rule tree (area=yes/no, coastline exceptions, etc.)

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

MIT License. See LICENSE for details.