GoogleStreetViewClient

class rapidtools.data_sources.GoogleStreetViewClient(max_workers: int = 8, timeout: float = 30)

Bases: object

Keyless client for locating, downloading and cropping Street View panoramas.

Parameters:

• max_workers – Threads used to download panorama tiles in parallel.

• timeout – Per-request timeout in seconds.

Example

>>> from shapely.geometry import Point
>>> from rapidtools.data_sources import GoogleStreetViewClient
>>> client = GoogleStreetViewClient()
>>> pano = client.find_panorama(34.1879, -118.1350)
>>> pano = client.get_panorama_metadata(pano.id)
>>> image = client.download_panorama(pano, zoom=3)
>>> crop, bounds = client.crop_to_geometry(
...     image, pano, Point(-118.13500, 34.18800).buffer(0.0001)
... )
>>> crop.size[1] == image.size[1]
True

Methods

crop_to_geometry	Crop a panorama to the horizontal span occupied by a geometry.
download_panorama	Download and stitch the full equirectangular panorama.
find_panorama	Find the Street View panorama closest to a coordinate.
get_panorama_metadata	Fetch full metadata (including the depth map) for a panorama ID.
view_angles	Signed viewing angles (degrees) of a geometry's vertices from the camera.

find_panorama(lat: float, lon: float, radius_m: float = 50.0) → StreetViewPanorama | None

Find the Street View panorama closest to a coordinate.

Parameters:

• lat – Latitude in degrees.

• lon – Longitude in degrees.

• radius_m – Search radius in metres. Defaults to 50.

Returns:

StreetViewPanorama | None – The nearest official panorama with its location, heading, sizes, date and neighbour links (the depth map requires get_panorama_metadata()), or None when nothing is within the radius or the request failed.

Example

>>> client = GoogleStreetViewClient()
>>> pano = client.find_panorama(34.1879, -118.1350, radius_m=50)
>>> pano.capture_date
'2025-11'

get_panorama_metadata(pano_id: str) → StreetViewPanorama | None

Fetch full metadata (including the depth map) for a panorama ID.

Parameters:

pano_id – Google panorama ID.

Returns:

StreetViewPanorama | None – Metadata, or None on failure.

Example

>>> client = GoogleStreetViewClient()
>>> pano = client.get_panorama_metadata('u3PxkEsnYto4l1N3yTmO_Q')
>>> pano.depth_map_b64 is not None
True

download_panorama(pano: StreetViewPanorama | str, zoom: int = 3) → Image | None

Download and stitch the full equirectangular panorama.

Parameters:

• pano – A StreetViewPanorama or a bare panorama ID.

• zoom – Tile zoom level 0-5; the width doubles per level (zoom 3 is 4096 x 2048 px, 45 deg of view per 512 px).

Returns:

Image.Image | None – The stitched RGB panorama, or None when no tile could be downloaded.

Raises:

ValueError – If zoom is outside 0-5.

Example

>>> client = GoogleStreetViewClient()
>>> image = client.download_panorama('u3PxkEsnYto4l1N3yTmO_Q', zoom=1)
>>> image.size
(1024, 512)

static view_angles(pano: StreetViewPanorama, geometry: BaseGeometry) → list[float]

Signed viewing angles (degrees) of a geometry’s vertices from the camera.

Angles are measured relative to the panorama heading: 0 is straight ahead, positive to the right, negative to the left.

Parameters:

• pano – Panorama metadata providing camera position and heading.

• geometry – Shapely geometry in WGS84 (any type with coordinates).

Returns:

list[float] – One angle per vertex of the geometry’s convex hull (or the point itself).

Example

>>> from shapely.geometry import Point
>>> pano = StreetViewPanorama(id='p', lat=0.0, lon=0.0, heading=0.0)
>>> GoogleStreetViewClient.view_angles(pano, Point(0.001, 0.0))
[90.0]

crop_to_geometry(image: Image, pano: StreetViewPanorama, geometry: BaseGeometry, fov_buffer_deg: float = 10.0, min_fov_deg: float = 30.0, vertical_crop: tuple[float, float] = (0.0, 1.0)) → tuple[Image, tuple[float, float]]

Crop a panorama to the horizontal span occupied by a geometry.

Parameters:

• image – The full panorama from download_panorama().

• pano – Its metadata (camera position and heading).

• geometry – Target asset geometry in WGS84.

• fov_buffer_deg – Extra margin added on both sides. Defaults to 10.

• min_fov_deg – Minimum horizontal field of view of the crop, so tiny or distant assets still yield a usable image. Defaults to 30.

• vertical_crop – (top, bottom) fractions of the panorama height to keep, e.g. (0.2, 0.9) removes sky and the vehicle hood.

Returns:

tuple[Image.Image, tuple[float, float]] – The crop and the (start, end) viewing angles in degrees relative to the heading that it covers.

Raises:

ValueError – If vertical_crop is not an increasing pair in [0, 1].

Example

>>> crop, (start, end) = client.crop_to_geometry(image, pano, footprint)
>>> end - start >= 30.0
True