Metadata-Version: 2.4
Name: osmviews
Version: 0.2.3
Summary: Ranking geographic locations by how much they are viewed on OpenStreetMap-based maps
Keywords: openstreetmap,osm,geo,ranking,geotiff
Author: Sascha Brawer
Author-email: Sascha Brawer <sascha@brawer.ch>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/brawer/osmviews-py
Project-URL: Documentation, https://github.com/brawer/osmviews-py/blob/main/README.md
Project-URL: Changelog, https://github.com/brawer/osmviews-py/blob/main/CHANGELOG.md
Project-URL: Source, https://github.com/brawer/osmviews-py
Project-URL: Bug Tracker, https://github.com/brawer/osmviews-py/issues
Project-URL: Funding, https://github.com/sponsors/brawer
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 Sascha Brawer <sascha@brawer.ch>
SPDX-License-Identifier: MIT
-->

# osmviews

[![PyPI](https://img.shields.io/pypi/v/osmviews.svg)](https://pypi.org/project/osmviews/)
[![Python versions](https://img.shields.io/pypi/pyversions/osmviews.svg)](https://pypi.org/project/osmviews/)
[![CI](https://github.com/brawer/osmviews-py/actions/workflows/ci.yml/badge.svg)](https://github.com/brawer/osmviews-py/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/brawer/osmviews-py/badge)](https://scorecard.dev/viewer/?uri=github.com/brawer/osmviews-py)
[![REUSE status](https://api.reuse.software/badge/github.com/brawer/osmviews-py)](https://api.reuse.software/info/github.com/brawer/osmviews-py)

Python client for [OSMViews](https://osmviews.toolforge.org), a world-wide ranking
of geographic locations by how much they are looked at on OpenStreetMap-based
maps. See the [main project](https://github.com/brawer/osmviews) 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

```python
# 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. Fetch the dataset (~594 MB,
regenerated weekly) from `osmviews.DOWNLOAD_URL` however you like, then pass the
path to `osmviews.open`. `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.

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](https://github.com/brawer/osmviews-rs) 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](https://github.com/brawer/osmviews-py/blob/main/CONTRIBUTING.md).
The design and its rationale are written up in
[TECHNICAL_DESIGN.md](https://github.com/brawer/osmviews-py/blob/main/TECHNICAL_DESIGN.md).

## Sponsoring

This package and the [OSMViews](https://github.com/brawer/osmviews) pipeline
behind it are maintained by [Sascha Brawer](https://github.com/brawer) as a
volunteer effort. If your project relies on them, please consider sponsoring
continued maintenance and future development via
[GitHub Sponsors](https://github.com/sponsors/brawer).

## License

MIT — see [LICENSE](https://github.com/brawer/osmviews-py/blob/main/LICENSE).

The repository is [REUSE](https://reuse.software) 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](https://www.contributor-covenant.org) and
licensed CC-BY-SA-4.0. It is not part of the published package.
