How kraina-ai/quackosm works
QuackOSM is a Python library and optional CLI for turning OpenStreetMap PBF data into GeoParquet, DuckDB, or GeoDataFrames. The main workflow accepts a PBF or geometry/extract request, filters and parses OSM data, then writes or returns the converted result. The README also documents geometry- and tag-based filtering, automatic extract downloads, caching, and geocoding. The reader and public conversion APIs are sampled; some detailed processing and extract internals are not, so those relationships are shown only where documented.
Main entry points: pbf_file_reader.py PBF reader · functions.py Conversion API · cli.py CLI commands · geocode.py Geocoding
Components 24
User interfaces
- Conversion API
quackosm/functions.py - CLI commands
quackosm/cli.py
Input discovery
- Geohash parsing
quackosm/_geohash_parser.py - Geocoding
quackosm/geocode.py - OSM extracts
quackosm/functions.py
OSM processing
- PBF reader
quackosm/pbf_file_reader.py - Tag filters
quackosm/_osm_tags_filters.py - Way polygon config
quackosm/_osm_way_polygon_features.py - Parquet workers
quackosm/_parquet_multiprocessing.py - Geometry intersection
quackosm/_intersection.py
Output and support
- GeoParquet output
quackosm/functions.py - GeoDataFrame output
quackosm/functions.py - DuckDB output
quackosm/functions.py - GeoParquet metadata
quackosm/_geoparquet_metadata.py - Progress reporting
quackosm/_rich_progress.py - Type validation
quackosm/_typing.py - Shared constants
quackosm/_constants.py - Errors and warnings
quackosm/_exceptions.py - Deprecation support
quackosm/_deprecate.py
Other components
- Python user
- CLI user
- OSM extract services
- Nominatim geocoder
- DuckDB Spatial
Connections 26
- Python user → Conversion API: calls
- CLI user → CLI commands: invokes
- CLI commands → Conversion API: dispatches
quackosm/cli.py - Conversion API → PBF reader: uses reader
quackosm/functions.py - CLI commands → PBF reader: uses reader
quackosm/cli.py - Conversion API → OSM extracts: requests extracts
README.md - OSM extracts → OSM extract services: downloads data
README.md - CLI commands → OSM extracts: selects extracts
quackosm/cli.py - CLI commands → Geocoding: resolves query
quackosm/cli.py - Geocoding → Nominatim geocoder: geocodes query
README.md - CLI commands → Geohash parsing: parses index
quackosm/cli.py - PBF reader → Tag filters: applies filters
quackosm/pbf_file_reader.py - PBF reader → Way polygon config: configures polygons
quackosm/pbf_file_reader.py - PBF reader → Geometry intersection: clips geometry
quackosm/_intersection.py - PBF reader → Parquet workers: processes parquet
quackosm/pbf_file_reader.py - PBF reader → DuckDB Spatial: queries spatial data
quackosm/pbf_file_reader.py - Conversion API → GeoParquet output: writes GeoParquet
README.md - Conversion API → GeoDataFrame output: returns frame
README.md - Conversion API → DuckDB output: exports database
README.md - Conversion API → GeoParquet metadata: writes metadata
- PBF reader → Progress reporting: reports progress
quackosm/pbf_file_reader.py - Tag filters → Type validation: validates types
quackosm/_osm_tags_filters.py - Way polygon config → Type validation: validates types
quackosm/_osm_way_polygon_features.py - PBF reader → Errors and warnings: raises errors
quackosm/pbf_file_reader.py - PBF reader → Shared constants: uses defaults
quackosm/pbf_file_reader.py - PBF reader → Deprecation support: marks deprecated args
quackosm/pbf_file_reader.py