Fetch OpenStreetMap data for a bounding box as GeoJSON. One function, one dependency, minimal footprint.
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 |
pip install tiny-osmOr with conda/pixi:
pixi add tiny-osmTip: If
orjsonis installed,tiny-osmuses it automatically for faster JSON parsing of Overpass API responses.
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"]')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"]') |
- 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.)
Contributions are welcome! See CONTRIBUTING.md for details.
MIT License. See LICENSE for details.