OSM Finder

Find and download publicly available OpenStreetMap *.osm.pbf extracts by name, id or geometry.

osmfinder wraps several public extract providers behind a single API: Geofabrik, BBBike, OpenStreetMap.fr, Movisda and GEO2day. It can look up an extract by a text query, or find the smallest set of extracts covering an arbitrary geometry, and download the matching *.osm.pbf files.

Logo attribution: The osmfinder logo uses icons from the Lucide icon set — specifically the earth and square-dashed icons.

Installation

pip install osmfinder

Usage

Python

import osmfinder
from shapely.geometry import box

# --- by name / id ---
# Returns an OsmfinderQueryResult with .extracts list and .extract accessor.
result = osmfinder.find("Monaco")
print(result.extracts[0].id)        # 'Movisda-admin_MC'
print(result.extracts[0].file_name) # 'movisda-admin_monaco'
print(result.extract.id)            # convenience accessor for single-match queries

# Download by name - returns OsmfinderDownloadResult with .download_paths.
dl = osmfinder.download("Monaco", download_directory="files")
print(dl.download_paths)         # [Path('files/movisda-admin_monaco.osm.pbf')]
print(dl.find_result.extract.id)    # 'Movisda-admin_MC'

# --- by geometry ---
geometry = box(2.11, 48.77, 2.54, 48.98)
result = osmfinder.find(geometry)
print(result)                       # multi-line OsmfinderGeometryResult with extracts, coverage, steps
print(len(result.extracts))         # number of extracts covering the geometry
print(result.extracts[0].id)        # 'BBBike_Paris'

# Download by geometry
dl = osmfinder.download(geometry, source="Geofabrik", download_directory="files")
print(len(dl.download_paths))       # number of downloaded files
print(dl.download_paths[0].name)    # 'geofabrik_europe_monaco.osm.pbf'

# --- by point ---
extracts = osmfinder.find_extracts_covering_point((-0.1276, 51.5074), source="Geofabrik")
print(len(extracts))            # number of extracts covering central London
print(extracts[0].id)           # 'Geofabrik_greater-london'

# --- force single extract ---
geometry = box(9.4, 47.2, 9.8, 47.6)
result = osmfinder.find_extracts_by_geometry(
    geometry, force_single_result=False  # default behaviour
)
print(len(result.extracts))     # 4
print(result.extracts[0].id)    # 'GEO2Day_europe_austria_vorarlberg'
print(result.extracts[1].id)    # 'BBBike_Konstanz'
print(result.extracts[2].id)    # 'GEO2Day_europe_switzerland_saint_gallen'
print(result.extracts[3].id)    # 'Movisda-admin_LI'

result = osmfinder.find_extracts_by_geometry(
    geometry, force_single_result=True
)
print(len(result.extracts))     # 1
print(result.extracts[0].id)    # 'Movisda-grid_N47W009'

# --- explore what's available ---
osmfinder.display_available_extracts(source="Geofabrik") # source is optional

# Get all extracts as a list for programmatic use
extracts = osmfinder.get_available_extracts(source="Geofabrik") # source is optional
for extract in extracts:
    print(extract.id, extract.file_name)

CLI

The package also provides a Typer-based CLI.

# Search and download by name
osmfinder search Monaco --output files/

# Search without download
osmfinder search Monaco --dry-run
                                        Query: Monaco
┏━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ #    ┃ Selected   ┃ ID                    ┃ Name   ┃ File name               ┃ Area (km²) ┃
┡━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ 1    │ ✔          │ Movisda-admin_MC      │ Monaco │ movisda-admin_monaco    │      80.01 │
│ 2    │            │ GEO2Day_europe_monaco │ monaco │ geo2day_europe_monaco   │     101.88 │
│ 3    │            │ osmfr_europe_monaco   │ monaco │ osmfr_europe_monaco     │     101.88 │
│ 4    │            │ Geofabrik_monaco      │ monaco │ geofabrik_europe_monaco │     184.39 │
└──────┴────────────┴───────────────────────┴────────┴─────────────────────────┴────────────┘

# Find and download extracts covering a bounding box
osmfinder covers --bbox 2.11,48.77,2.54,48.98 --source Geofabrik

# Find extracts without download
osmfinder covers --dry-run --wkt "POLYGON ((9.8 47.2, 9.8 47.6, 9.4 47.6, 9.4 47.2, 9.8 47.2))"
                                            Geometry covering result
┏━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃    ┃                                  ┃            ┃            ┃        ┃       Cum. ┃          ┃           ┃
┃ #  ┃ ID                               ┃ Name       ┃ Area (km²) ┃    IoU ┃   Coverage ┃ Status   ┃ Reason    ┃
┡━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ 1  │ GEO2Day_europe...tria_vorarlberg │ vorarlberg │    2748.28 │ 0.1820 │      46.9% │ selected │ first_ex… │
│ 2  │ GEO2Day_europe...nd_saint_gallen │ saint_gal… │    2565.17 │ 0.1797 │      84.1% │ selected │ selected  │
│ 3  │ Movisda-admin_LI                 │ Liechtens… │     159.04 │ 0.0624 │      85.7% │ selected │ selected  │
│ 4  │ GEO2Day_europe...zerland_thurgau │ thurgau    │    1092.62 │ 0.0462 │      85.7% │ rejected │ redundant │
│ 5  │ BBBike_Konstanz                  │ Konstanz   │    4471.33 │ 0.0302 │     100.0% │ selected │ selected  │
└────┴──────────────────────────────────┴────────────┴────────────┴────────┴────────────┴──────────┴───────────┘
╭────────────────────────────────────────────────── Summary ───────────────────────────────────────────────────╮
│ Coverage: 100.0%                                                                                             │
│ IoU threshold: 0.01                                                                                          │
│ Sources used: BBBike, GEO2Day, Geofabrik, Movisda-admin, Movisda-grid, osmfr                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

# Find extracts from a GeoJSON file
osmfinder covers --file area.geojson --output downloads/

# List available extracts
osmfinder list --source Geofabrik

# Clear the local index cache
osmfinder clear

Sources

The source argument accepts a single value, an iterable, or a comma-separated string. Available values: any, Geofabrik, BBBike, osmfr, GEO2Day, Movisda-admin, Movisda-grid.

osmfinder.find_extract_by_query("Berlin", ["Geofabrik", "BBBike"])
osmfinder.find_extract_by_query("Berlin", "geofabrik,bbbike")

Public API

Note: find() and download() are dual-purpose helpers. When called with a string query they return an OsmfinderQueryResult / OsmfinderDownloadResult. When called with a geometry they return an OsmfinderGeometryResult / OsmfinderDownloadResult.

Result classes

All find and download operations return typed result objects instead of raw lists.

OpenStreetMapExtract

Metadata object returned by search and listing operations.

OsmfinderQueryResult

Returned by find_extract_by_query() and find() when called with a string query.

OsmfinderGeometryResult

Returned by find_extracts_by_geometry() and find() when called with a geometry.

OsmfinderDownloadResult

Returned by download().

GeometryCoveringStep

Record of a single extract considered during geometry covering.

Example repr output

All result objects use a verbose multi-line repr for easier debugging:

>>> result = osmfinder.find("Monaco")
>>> print(result)
OsmfinderQueryResult
  query: Monaco
  extract: Movisda-admin_MC — Monaco
  matched extracts: Movisda-admin_MC, Geofabrik_monaco, BBBike_Monaco, OSM_fr_monaco, geofabrik_andorra, +3 more
  sources used: Geofabrik, BBBike, OSM_fr, Movisda-admin, GEO2Day

>>> geometry = box(7.40, 43.71, 7.44, 43.75)
>>> result = osmfinder.find(geometry, source="Geofabrik")
>>> print(result)
OsmfinderGeometryResult
  extracts:
    Geofabrik_europe_monaco — Monaco
  coverage: 100.0%
  iou threshold: 0.01
  steps:
    Geofabrik_europe_monaco — Monaco
      iou: 1.0000, selected, first_extract
  sources used: Geofabrik

>>> dl = osmfinder.download("Monaco", download_directory="files")
>>> print(dl)
OsmfinderDownloadResult
  downloaded:
    files/movisda-admin_monaco.osm.pbf
  unavailable:
    none
  find result:
    OsmfinderQueryResult
      query: Monaco
      extract: Movisda-admin_MC — Monaco
      matched extracts: Movisda-admin_MC, Geofabrik_monaco, BBBike_Monaco, OSM_fr_monaco, geofabrik_andorra, +3 more
      sources used: Geofabrik, BBBike, OSM_fr, Movisda-admin, GEO2Day

Index cache

Provider indexes are cached locally (in the platform cache dir) as GeoParquet (*.parquet). Precalculated indexes are downloaded from this repo's precalculated_indexes/ folder on first use, so most sources don't need to be rebuilt from scratch. Use clear_osm_index_cache() to force a refresh.

License

MIT