Skip to content

TinyOSM: Lightweight OpenStreetMap GeoJSON Fetcher#

PyPI Conda License: MIT Binder

codecov CI Documentation Downloads

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.