random-streetview 0.1.0__tar.gz

random_streetview-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env

random_streetview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AngLaboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

random_streetview-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: random-streetview
+Version: 0.1.0
+Summary: One call, one random Google Street View panorama
+Project-URL: Homepage, https://github.com/AngLaboratory/random-streetview
+Project-URL: Source, https://github.com/AngLaboratory/random-streetview
+Project-URL: Issues, https://github.com/AngLaboratory/random-streetview/issues
+Author-email: AngLaboratory <anglaboratory@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: geoguessr,google-street-view,panoid,panorama,random,street-view,streetview
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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 :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# random-streetview
+
+[![PyPI](https://img.shields.io/pypi/v/random-streetview)](https://pypi.org/project/random-streetview/)
+[![Python](https://img.shields.io/pypi/pyversions/random-streetview)](https://pypi.org/project/random-streetview/)
+
+One call, one random Google Street View panorama.
+
+```bash
+pip install random-streetview
+```
+
+```python
+from random_streetview import random_panorama
+
+pano = random_panorama()
+
+pano.id     # 'ptFCsB5aFyaWDDlpbCliVw'
+pano.lon    # 2.2954822
+pano.lat    # 48.8583758
+pano.url    # 'https://www.google.com/maps/@?api=1&map_action=pano&pano=...'
+```
+
+`Panorama` is a named tuple, so `panoid, lon, lat = random_panorama()` works too.
+
+Nothing raises on a network or parsing failure — you get `None` once the
+attempts are used up.
+
+## Timeouts
+
+```python
+random_panorama(max_retry=10, timeout=3.0)   # the defaults
+```
+
+`timeout` is per request, in seconds, and is raised to **0.5** if you ask for
+less. A single call budgets at most **30 seconds** of timeout across its
+attempts, so `max_retry` is an upper bound rather than a promise: at
+`timeout=10.0` you get 3 attempts, not 10. The default pairing is sized to
+reach all 10. Time actually spent on the wire does not count against the
+budget — only the timeouts do.
+
+## How it works, and why it can break
+
+Picking a coordinate at random mostly lands you in the ocean, so candidates
+come from [randomstreetview.com][rsv] and [wandery.it][wandery], which keep
+lists of places known to have coverage. Each candidate is then resolved to a
+panorama id through `GeoPhotoService.SingleImageSearch`, an **undocumented
+internal Google Maps endpoint**.
+
+That means no API key — and no guarantees. The scraped sites will change their
+HTML, and Google can alter or start refusing that endpoint at any time; when
+that happens this library returns `None` rather than breaking your program. If
+you need something dependable, use the official
+[Street View Static API metadata endpoint][meta] with a key instead (metadata
+requests are not billed).
+
+Requests are not rate-limited for you. Space out your calls.
+
+## Development
+
+```bash
+uv sync
+uv run pytest    # fully offline; network calls are monkeypatched
+```
+
+## License
+
+MIT
+
+[rsv]: https://randomstreetview.com/
+[wandery]: https://www.wandery.it/
+[meta]: https://developers.google.com/maps/documentation/streetview/metadata

random_streetview-0.1.0/README.md

@@ -0,0 +1,71 @@
+# random-streetview
+
+[![PyPI](https://img.shields.io/pypi/v/random-streetview)](https://pypi.org/project/random-streetview/)
+[![Python](https://img.shields.io/pypi/pyversions/random-streetview)](https://pypi.org/project/random-streetview/)
+
+One call, one random Google Street View panorama.
+
+```bash
+pip install random-streetview
+```
+
+```python
+from random_streetview import random_panorama
+
+pano = random_panorama()
+
+pano.id     # 'ptFCsB5aFyaWDDlpbCliVw'
+pano.lon    # 2.2954822
+pano.lat    # 48.8583758
+pano.url    # 'https://www.google.com/maps/@?api=1&map_action=pano&pano=...'
+```
+
+`Panorama` is a named tuple, so `panoid, lon, lat = random_panorama()` works too.
+
+Nothing raises on a network or parsing failure — you get `None` once the
+attempts are used up.
+
+## Timeouts
+
+```python
+random_panorama(max_retry=10, timeout=3.0)   # the defaults
+```
+
+`timeout` is per request, in seconds, and is raised to **0.5** if you ask for
+less. A single call budgets at most **30 seconds** of timeout across its
+attempts, so `max_retry` is an upper bound rather than a promise: at
+`timeout=10.0` you get 3 attempts, not 10. The default pairing is sized to
+reach all 10. Time actually spent on the wire does not count against the
+budget — only the timeouts do.
+
+## How it works, and why it can break
+
+Picking a coordinate at random mostly lands you in the ocean, so candidates
+come from [randomstreetview.com][rsv] and [wandery.it][wandery], which keep
+lists of places known to have coverage. Each candidate is then resolved to a
+panorama id through `GeoPhotoService.SingleImageSearch`, an **undocumented
+internal Google Maps endpoint**.
+
+That means no API key — and no guarantees. The scraped sites will change their
+HTML, and Google can alter or start refusing that endpoint at any time; when
+that happens this library returns `None` rather than breaking your program. If
+you need something dependable, use the official
+[Street View Static API metadata endpoint][meta] with a key instead (metadata
+requests are not billed).
+
+Requests are not rate-limited for you. Space out your calls.
+
+## Development
+
+```bash
+uv sync
+uv run pytest    # fully offline; network calls are monkeypatched
+```
+
+## License
+
+MIT
+
+[rsv]: https://randomstreetview.com/
+[wandery]: https://www.wandery.it/
+[meta]: https://developers.google.com/maps/documentation/streetview/metadata

random_streetview-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "random-streetview"
+version = "0.1.0"
+description = "One call, one random Google Street View panorama"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AngLaboratory", email = "anglaboratory@gmail.com" }]
+keywords = [
+    "streetview",
+    "street-view",
+    "google-street-view",
+    "random",
+    "panorama",
+    "panoid",
+    "geoguessr",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+    "Typing :: Typed",
+]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://github.com/AngLaboratory/random-streetview"
+Source = "https://github.com/AngLaboratory/random-streetview"
+Issues = "https://github.com/AngLaboratory/random-streetview/issues"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/random_streetview"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

random_streetview-0.1.0/src/random_streetview/__init__.py

@@ -0,0 +1,180 @@
+"""One call, one random Google Street View panorama.
+
+    >>> from random_streetview import random_panorama
+    >>> random_panorama()
+    Panorama(id='ptFCsB5aFyaWDDlpbCliVw', lon=2.2954822, lat=48.8583758)
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import re
+from typing import NamedTuple, Optional, Tuple
+
+import requests
+
+__version__ = "0.1.0"
+__all__ = ["Panorama", "random_panorama"]
+
+# Per-request timeout: the default, and the floor any caller is held to.
+_DEFAULT_TIMEOUT = 3.0
+_MIN_TIMEOUT = 0.5
+
+# Total timeout a single call may budget across its attempts. Measured in
+# timeout units rather than wall clock, so time actually spent on the wire
+# does not count against it.
+_TIMEOUT_BUDGET = 30.0
+
+_USER_AGENT = (
+    "random-streetview/0.1.0 "
+    "(+https://github.com/AngLaboratory/random-streetview)"
+)
+
+# Google's panorama ids are always this long; anything else is a miss.
+_PANOID_LENGTH = 22
+
+# Undocumented internal Maps endpoint -- no API key, no guarantees.
+_SEARCH_URL = (
+    "https://maps.googleapis.com/maps/api/js/GeoPhotoService.SingleImageSearch"
+)
+
+# Picking a point at random mostly lands you in the ocean, so candidates come
+# from sites that keep their own lists of places known to have coverage.
+_RSV_URL = "https://randomstreetview.com/"
+_RSV_RE = re.compile(r"randomLocations\.all\s*=\s*(\[\{.*?\}\]);", re.S)
+
+_WANDERY_URL = (
+    "https://www.wandery.it/random-street/random-streetview-lateral-thinking.php"
+)
+_WANDERY_RE = re.compile(r"!2m2!1d([-\d.]+)!2d([-\d.]+)", re.S)
+
+_LonLat = Tuple[Optional[float], Optional[float]]
+
+
+class Panorama(NamedTuple):
+    """A Street View panorama and where it is."""
+
+    id: str
+    lon: float
+    lat: float
+
+    @property
+    def url(self) -> str:
+        """A google.com/maps link that opens this panorama."""
+        return (
+            "https://www.google.com/maps/@"
+            f"?api=1&map_action=pano&pano={self.id}"
+        )
+
+
+def _get(url: str, timeout: float) -> Optional[str]:
+    try:
+        response = requests.get(
+            url, headers={"User-Agent": _USER_AGENT}, timeout=timeout
+        )
+        response.raise_for_status()
+        return response.text
+    except Exception:
+        return None
+
+
+def _from_randomstreetview(timeout: float) -> _LonLat:
+    body = _get(_RSV_URL, timeout)
+    if body is None:
+        return None, None
+
+    match = _RSV_RE.search(body)
+    if not match:
+        return None, None
+    try:
+        locations = json.loads(match.group(1))
+        point = random.choice(locations)
+        return float(point["lng"]), float(point["lat"])
+    except (ValueError, KeyError, TypeError, IndexError):
+        return None, None
+
+
+def _from_wandery(timeout: float) -> _LonLat:
+    body = _get(_WANDERY_URL, timeout)
+    if body is None:
+        return None, None
+
+    match = _WANDERY_RE.search(body)
+    if not match:
+        return None, None
+    try:
+        return float(match.group(2)), float(match.group(1))
+    except ValueError:
+        return None, None
+
+
+def _random_lonlat(timeout: float) -> _LonLat:
+    for source in (_from_randomstreetview, _from_wandery):
+        lon, lat = source(timeout)
+        if lon is not None and lat is not None:
+            return lon, lat
+    return None, None
+
+
+def _panoid_at(lon: float, lat: float, timeout: float) -> Optional[str]:
+    body = _get(
+        f"{_SEARCH_URL}?pb=!1m5!1sapiv3!5sUS!11m2!1m1!1b0"
+        f"!2m4!1m2!3d{lat}!4d{lon}!2d50!3m10"
+        "!2m2!1sen!2sGB!9m1!1e2!11m4!1m3!1e2!2b1!3e2!4m10!1e1!1e2!1e3!1e4"
+        "!1e8!1e6!5m1!1e2!6m1!1e2&callback=callbackfunc",
+        timeout,
+    )
+    if body is None:
+        return None
+
+    # The id is the first quoted string in the JSONP payload.
+    start = body.find('"')
+    end = body.find('"', start + 1) if start != -1 else -1
+    if start == -1 or end == -1:
+        return None
+
+    panoid = body[start + 1 : end]
+    # "generic" is what the endpoint returns when it has nothing to offer.
+    if panoid == "generic" or len(panoid) != _PANOID_LENGTH:
+        return None
+    return panoid
+
+
+def random_panorama(
+    *, max_retry: int = 10, timeout: float = _DEFAULT_TIMEOUT
+) -> Optional[Panorama]:
+    """A random Street View panorama from somewhere on Earth.
+
+    ``timeout`` is the per-request timeout in seconds, raised to
+    :data:`_MIN_TIMEOUT` if you ask for less. Attempts stop early once
+    ``timeout`` times the attempts made would exceed the 30 second budget, so
+    ``max_retry`` is an upper bound rather than a promise -- the defaults are
+    sized to reach all 10.
+
+    Returns ``None`` when the attempts are used up without a hit. Nothing here
+    raises on a network or parsing failure.
+    """
+    if max_retry < 1:
+        raise ValueError("max_retry must be at least 1")
+
+    timeout = max(timeout, _MIN_TIMEOUT)
+    if timeout > _TIMEOUT_BUDGET:
+        raise ValueError(
+            "timeout must not exceed the {:.0f}s budget".format(_TIMEOUT_BUDGET)
+        )
+
+    budgeted = 0.0
+    for _ in range(max_retry):
+        if budgeted + timeout > _TIMEOUT_BUDGET:
+            break
+        budgeted += timeout
+
+        lon, lat = _random_lonlat(timeout)
+        if lon is None or lat is None:
+            continue
+        panoid = _panoid_at(lon, lat, timeout)
+        if panoid is not None:
+            return Panorama(panoid, lon, lat)
+
+    return None

random_streetview-0.1.0/tests/test_random_streetview.py

@@ -0,0 +1,126 @@
+"""Offline tests -- every network call is monkeypatched."""
+
+import pytest
+
+import random_streetview as rsv
+from random_streetview import Panorama, random_panorama
+
+_RSV_BODY = 'var x; randomLocations.all = [{"lat":48.8584,"lng":2.2945}];'
+_WANDERY_BODY = "?pb=!2m2!1d48.8584!2d2.2945!3m1"
+_JSONP = 'callbackfunc([1,"ptFCsB5aFyaWDDlpbCliVw",[null]])'
+
+
+def test_panorama_unpacks_and_builds_a_url():
+    pano = Panorama("a" * 22, 2.2945, 48.8584)
+    assert (pano.id, pano.lon, pano.lat) == tuple(pano)
+    assert pano.url.endswith("pano=" + "a" * 22)
+
+
+def test_max_retry_must_be_positive():
+    with pytest.raises(ValueError):
+        random_panorama(max_retry=0)
+
+
+def test_timeout_is_raised_to_the_floor(monkeypatch):
+    seen = []
+
+    def fake_get(url, timeout):
+        seen.append(timeout)
+        return None
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    random_panorama(max_retry=1, timeout=0.01)
+    assert seen and all(t == rsv._MIN_TIMEOUT for t in seen)
+
+
+def test_timeout_larger_than_the_budget_is_rejected():
+    with pytest.raises(ValueError):
+        random_panorama(timeout=rsv._TIMEOUT_BUDGET + 1)
+
+
+def test_attempts_stop_at_the_budget(monkeypatch):
+    attempts = []
+
+    def fake_get(url, timeout):
+        if url.startswith("https://randomstreetview"):
+            attempts.append(url)
+        return None
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    # 10s per request leaves room for 3 attempts inside the 30s budget,
+    # not the 10 that max_retry asks for.
+    assert random_panorama(max_retry=10, timeout=10.0) is None
+    assert len(attempts) == 3
+
+
+def test_defaults_reach_every_retry(monkeypatch):
+    attempts = []
+
+    def fake_get(url, timeout):
+        if url.startswith("https://randomstreetview"):
+            attempts.append(url)
+        return None
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    assert random_panorama() is None
+    assert len(attempts) == 10
+
+
+def test_happy_path(monkeypatch):
+    def fake_get(url, timeout):
+        return _RSV_BODY if url.startswith("https://randomstreetview") else _JSONP
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    assert random_panorama() == Panorama("ptFCsB5aFyaWDDlpbCliVw", 2.2945, 48.8584)
+
+
+def test_falls_back_to_the_second_source(monkeypatch):
+    def fake_get(url, timeout):
+        if url.startswith("https://randomstreetview"):
+            return None
+        if url.startswith("https://www.wandery"):
+            return _WANDERY_BODY
+        return _JSONP
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    pano = random_panorama()
+    assert pano is not None
+    assert (pano.lon, pano.lat) == (2.2945, 48.8584)
+
+
+def test_returns_none_when_everything_fails(monkeypatch):
+    monkeypatch.setattr(rsv, "_get", lambda url, timeout: None)
+    assert random_panorama(max_retry=3) is None
+
+
+def test_rejects_a_generic_panoid(monkeypatch):
+    def fake_get(url, timeout):
+        if url.startswith("https://randomstreetview"):
+            return _RSV_BODY
+        return 'callbackfunc([1,"generic",[null]])'
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    assert random_panorama(max_retry=2) is None
+
+
+def test_rejects_a_wrong_length_panoid(monkeypatch):
+    def fake_get(url, timeout):
+        if url.startswith("https://randomstreetview"):
+            return _RSV_BODY
+        return 'callbackfunc([1,"tooshort",[null]])'
+
+    monkeypatch.setattr(rsv, "_get", fake_get)
+    assert random_panorama(max_retry=2) is None
+
+
+def test_survives_an_unparseable_source(monkeypatch):
+    monkeypatch.setattr(rsv, "_get", lambda url, timeout: "not what we expected")
+    assert random_panorama(max_retry=2) is None
+
+
+def test_get_swallows_network_errors(monkeypatch):
+    def boom(*args, **kwargs):
+        raise OSError("no network")
+
+    monkeypatch.setattr(rsv.requests, "get", boom)
+    assert rsv._get("https://example.com", 1.0) is None