Skip to content

API Reference#

TinyOSM: Fetch OpenStreetMap data for a bounding box.

OverpassError #

OverpassError()

Bases: RuntimeError

Raised when all Overpass API mirrors fail to return a response.

OSMFilters #

Predefined Overpass QL tag-filter strings for :func:fetch.

Each attribute is a valid osm_filter value — either a single string or a tuple of strings (which :func:fetch issues as separate queries and merges into one FeatureCollection). Any other Overpass QL tag-filter string works too.

configure_logger #

configure_logger(
    *,
    verbose=None,
    level=None,
    file=None,
    file_level=None,
    file_mode="a",
    file_only=False,
)

Configure logging settings.

Parameters:

  • verbose (bool, default: None ) –

    Shortcut: True sets console to DEBUG, False to WARNING. If both level and verbose are given, level wins.

  • level (str or int, default: None ) –

    Console logging level ("DEBUG", "INFO", "WARNING", etc.).

  • file (str or Path, default: None ) –

    Enable file logging at this path. Pass None to disable file logging.

  • file_level (str or int, default: None ) –

    File handler level. Defaults to DEBUG.

  • file_mode (('a', 'w'), default: 'a' ) –

    Append or overwrite the log file. Defaults to 'a'.

  • file_only (bool, default: False ) –

    If True, disable console logging. Requires file to be set.

fetch #

fetch(left, bottom, right, top, osm_filter)

Fetch OSM data within a bounding box as a GeoJSON FeatureCollection.

Large bounding boxes are automatically subdivided into tiles and fetched across rotating Overpass mirrors with retries. The response is returned as a valid GeoJSON FeatureCollection dict that can be fed directly to geopandas with no post-processing.

Parameters:

  • left (float) –

    Bounding box coordinates in WGS84 (EPSG:4326).

  • bottom (float) –

    Bounding box coordinates in WGS84 (EPSG:4326).

  • right (float) –

    Bounding box coordinates in WGS84 (EPSG:4326).

  • top (float) –

    Bounding box coordinates in WGS84 (EPSG:4326).

  • osm_filter (str or sequence of str) –

    Overpass QL tag-filter string(s) selecting which features to fetch. Use a member of :class:OSMFilters for the built-in presets (OSMFilters.HIGHWAY, OSMFilters.WATERWAY, OSMFilters.WATER_BODY) or pass any valid Overpass QL tag-filter (e.g. '["amenity"="restaurant"]'). When a sequence is given, each filter is queried separately and the results are merged into a single deduplicated FeatureCollection.

Returns:

  • dict[str, Any] –

    A GeoJSON FeatureCollection dict — {"type": "FeatureCollection", "features": [...]} — where every feature has an osm_type and osm_id in its properties alongside the OSM tags.

Raises:

  • ValueError –

    If the bounding box is invalid.

  • OverpassError –

    If all Overpass mirrors fail to return a response.

Examples:

Fetch highway features using a preset:

>>> import geopandas as gpd
>>> fc = fetch(-97.75, 30.25, -97.70, 30.30, osm_filter=OSMFilters.HIGHWAY)
>>> gdf = gpd.GeoDataFrame.from_features(fc, crs=4326)

Fetch with a custom Overpass filter:

>>> fc = fetch(-97.75, 30.25, -97.70, 30.30, osm_filter='["amenity"="restaurant"]')