osmviews

Python client for OSMViews, a world-wide ranking of geographic locations by how much they are looked at on OpenStreetMap-based maps. See the main project for background.

OSMViews aggregates a year of OpenStreetMap map-tile access logs into a single raster covering the whole planet. This package reads a copy of that raster from local disk and answers point queries.

Usage

# pip install osmviews
import osmviews

with osmviews.open("osmviews.tiff") as o:
    # rank() is 0.0 (nobody looks here) to 1.0 (one of the most-viewed places on
    # Earth). Coordinates are x, y — longitude then latitude, as in GeoJSON;
    # values drift weekly.
    shibuya = o.rank(139.7013, 35.6586)  # Tokyo, Shibuya     ~0.69
    altstetten = o.rank(8.4889, 47.3915)  # Zürich, Altstetten ~0.66
    ushuaia = o.rank(-68.3030, -54.8019)  # Ushuaia            ~0.56
    sahara = o.rank(13.0000, 23.0000)  # Sahara             ~0.00
    assert shibuya > altstetten > ushuaia > sahara

The package does not download anything. The dataset (~594 MB) is rebuilt weekly under a new dated file name, so there is no single download link: fetch the small data package descriptor at osmviews.DATAPACKAGE_URL, which names the current file and its SHA-256, download that however you like, then pass the path to osmviews.open. With the standard library alone:

import hashlib, json, shutil, urllib.parse, urllib.request
import osmviews

with urllib.request.urlopen(osmviews.DATAPACKAGE_URL) as r:
    package = json.load(r)
raster = next(res for res in package["resources"] if res["name"] == "osmviews")
url = urllib.parse.urljoin(osmviews.DATAPACKAGE_URL, raster["path"])
with urllib.request.urlopen(url) as r, open("osmviews.tiff", "wb") as f:
    shutil.copyfileobj(r, f)
with open("osmviews.tiff", "rb") as f:
    if f"sha256:{hashlib.file_digest(f, 'sha256').hexdigest()}" != raster["hash"]:
        raise ValueError(f"checksum mismatch for {url}")

o.date gives the last day of OpenStreetMap tile-log data in the raster (a datetime.date), so you can tell which week's views you have; it matches the data package's version.

osmviews.DOWNLOAD_URL is deprecated: the link it names stops working after 2026-12-10, and the constant goes away in 0.3.0.

An OSMViews instance is safe to share across threads: every query takes a lock only briefly, and tile decoding happens outside it. Decoded tiles are kept in a small LRU cache (osmviews.open(path, cache_tiles=...), 0 disables it), so queries clustered in one region stay fast. o.metrics() returns a snapshot of counters (cache hit rate, decode time, …) worth logging at the end of a long run.

The file is memory-mapped, so it must not be modified or truncated while an OSMViews is open.

Performance

Rough numbers on an Apple M5, CPython 3.13 (from benchmarks/bench.py): rank() returns in ~0.5 µs when the tile is already cached and ~57 µs on a miss that has to read and inflate one. Each decoded tile is 256 KiB; the default LRU holds 64 of them (~16 MiB), and the GeoTIFF is memory-mapped rather than read onto the heap. For bulk lookups, submit points in roughly spatial order (e.g. sorted by tile or by S2 cell ID) so neighbouring queries reuse cached tiles.

This is pure Python; it is not trying to be fast. If throughput matters, the Rust client answers the same query in tens of nanoseconds.

No dependencies

Pure Python 3.11+, standard library only (mmap, zlib, struct, array). The TIFF header parsing and the map projection are done in-package.

Contributing

Contributions are welcome — see CONTRIBUTING.md. The design and its rationale are written up in TECHNICAL_DESIGN.md.

Sponsoring

This package and the OSMViews pipeline behind it are maintained by Sascha Brawer as a volunteer effort. If your project relies on them, please consider sponsoring continued maintenance and future development via GitHub Sponsors.

License

MIT — see LICENSE.

The repository is REUSE compliant: every file declares its copyright and license, either in an SPDX header or via REUSE.toml. All code and documentation is MIT; the sole exception is CODE_OF_CONDUCT.md, adapted from the Contributor Covenant and licensed CC-BY-SA-4.0. It is not part of the published package.