streetlevel.mapy: Mapy.cz Panorama

Finding panoramas

find_panorama(lat, lon, radius=100.0, year=None, links=True, historical=True)

Searches for a panorama within a radius around a point.

Parameters:

  • lat (float) – Latitude of the center point.

  • lon (float) – Longitude of the center point.

  • radius (float) – (optional) Search radius in meters. Defaults to 100.

  • year (int | None) – (optional) If given, searches for a specific year. Otherwise, the most recent panorama is returned.

  • links (bool) – (optional) Whether an additional network request is made to fetch linked panoramas. Defaults to True.

  • historical (bool) – (optional) Whether additional network requests are made to fetch metadata of panoramas from other years. Defaults to True.

Returns:

A MapyPanorama object if a panorama was found, or None.

Return type:

MapyPanorama | None

Usage sample:

from streetlevel import mapy

pano = mapy.find_panorama(50.704732, 14.404809)
print(pano.lat, pano.lon)
print(pano.id)
print(pano.date)
async find_panorama_async(lat, lon, radius=100.0, year=None, links=True, historical=True)
Parameters:

  • lat (float)

  • lon (float)

  • radius (float)

  • year (int | None)

  • links (bool)

  • historical (bool)

Return type:

MapyPanorama | None

Usage sample:

from streetlevel import mapy
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await mapy.find_panorama_async(50.704732, 14.404809, session)
    print(pano.lat, pano.lon)
    print(pano.id)
    print(pano.date)
find_panorama_by_id(panoid, links=True, historical=True)

Fetches metadata of a specific panorama.

Parameters:

  • panoid (int) – The pano ID.

  • links (bool) – (optional) Whether an additional network request is made to fetch linked panoramas. Defaults to True.

  • historical (bool) – (optional) Whether additional network requests are made to fetch metadata of panoramas from other years. Defaults to True.

Returns:

A MapyPanorama object if a panorama with this ID exists, or None.

Return type:

MapyPanorama | None

Usage sample:

from streetlevel import mapy

pano = mapy.find_panorama_by_id(82102772)
print(pano.lat, pano.lon)
print(pano.date)
print(pano.heading)
async find_panorama_by_id_async(panoid, links=True, historical=True)
Parameters:

  • panoid (int)

  • links (bool)

  • historical (bool)

Return type:

MapyPanorama | None

Usage sample:

from streetlevel import mapy
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await mapy.find_panorama_by_id_async(82102772, session)
    print(pano.lat, pano.lon)
    print(pano.date)
    print(pano.heading)

Fetches linked panoramas.

Parameters:

  • panoid (int) – The pano ID.

  • year (int | None) – (optional) If given, fetches links for a specific year. Otherwise, the most recent coverage is returned.

Returns:

A list of nearby panoramas.

Return type:

List[Link]

Parameters:

  • panoid (int)

  • year (int | None)

Return type:

List[Link]

Downloading panoramas

get_panorama(pano, zoom=2)

Downloads a panorama and returns it as PIL image.

Parameters:

  • pano (MapyPanorama) – The panorama.

  • zoom (int) – (optional) Image size; 0 is lowest, 2 is highest. If 2 is not available, 1 will be downloaded. Defaults to 2.

Returns:

A PIL image containing the panorama.

Return type:

Image

async get_panorama_async(pano, session, zoom=2)
Parameters:
Return type:

Image

download_panorama(pano, path, zoom=2, pil_args=None)

Downloads a panorama to a file.

Parameters:

  • pano (MapyPanorama) – The panorama.

  • path (str) – Output path.

  • zoom (int) – (optional) Image size; 0 is lowest, 2 is highest. If 2 is not available, 1 will be downloaded. Defaults to 2.

  • pil_args (dict | None) – (optional) Additional arguments for PIL’s Image.save method, e.g. {"quality":100}. Defaults to {}.

Return type:

None

Usage sample:

from streetlevel import mapy

pano = mapy.find_panorama_by_id(82102772)
mapy.download_panorama(pano, f"{pano.id}.jpg")
async download_panorama_async(pano, path, session, zoom=2, pil_args=None)
Parameters:

  • pano (MapyPanorama)

  • path (str)

  • session (ClientSession)

  • zoom (int)

  • pil_args (dict | None)

Return type:

None

Usage sample:

from streetlevel import mapy
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await mapy.find_panorama_by_id_async(82102772, session)
    await mapy.download_panorama_async(pano, f"{pano.id}.jpg", session)

Data classes

class MapyPanorama(id, lat, lon, tile_size, max_zoom, domain_prefix, uri_path, file_mask, date, elevation, provider, num_tiles=None, heading=None, omega=None, phi=None, kappa=None, pitch=None, roll=None, links=<factory>, historical=<factory>)

Metadata of a Mapy.cz panorama.

Parameters:

  • id (int)

  • lat (float)

  • lon (float)

  • tile_size (Size)

  • max_zoom (int)

  • domain_prefix (str)

  • uri_path (str)

  • file_mask (str)

  • date (datetime)

  • elevation (float)

  • provider (str)

  • num_tiles (List[Size])

  • heading (float)

  • omega (float)

  • phi (float)

  • kappa (float)

  • pitch (float)

  • roll (float)

  • links (List[Link])

  • historical (List[MapyPanorama])

date: datetime

Capture date and time of the panorama.

domain_prefix: str

Part of the panorama tile URL.

elevation: float

Elevation at the capture location in meters.

file_mask: str

Part of the panorama tile URL.

heading: float = None

Heading offset in radians, where 0° is north, 90° is east, -180°/180° is south, and -90° is west.

historical: List[MapyPanorama]

A list of panoramas with a different date at the same location.

id: int

The pano ID.

kappa: float = None
lat: float

Latitude of the panorama’s location.

The panoramas which the arrows in the client link to.

lon: float

Longitude of the panorama’s location.

max_zoom: int

Highest zoom level available; either 1 or 2.

omega: float = None

Creates a permalink to this panorama.

Parameters:

  • heading (float) – (optional) Initial heading of the viewport. Defaults to 0°.

  • pitch (float) – (optional) Initial pitch of the viewport. Defaults to 0°.

  • fov (float) – (optional) Initial FOV of the viewport. Defaults to 72°.

  • map_zoom (float) – (optional) Initial zoom level of the map. Defaults to 17.

  • radians (bool) – (optional) Whether angles are in radians. Defaults to False.

  • self (MapyPanorama)

Returns:

A Mapy.cz URL which will open the given panorama.

Return type:

str

phi: float = None
pitch: float = None

Pitch offset for upright correction of the panorama, in radians.

provider: str

The name of the company which created the panorama.

roll: float = None

Roll offset for upright correction of the panorama, in radians.

tile_size: Size

Mapy panoramas are broken up into a grid of tiles. This returns the size of one tile.

uri_path: str

Part of the panorama tile URL.

Miscellaneous

Creates a permalink to the given panorama. All parameters are optional, but either a location, or a pano ID, or both must be passed.

Parameters:

  • id (int | None) – (optional) The pano ID.

  • lat (float | None) – (optional) Latitude of the panorama’s location.

  • lon (float | None) – (optional) Longitude of the panorama’s location.

  • heading (float) – (optional) Initial heading of the viewport. Defaults to 0°.

  • pitch (float) – (optional) Initial pitch of the viewport. Defaults to 0°.

  • fov (float) – (optional) Initial FOV of the viewport. Defaults to 72°.

  • map_zoom (float) – (optional) Initial zoom level of the map. Defaults to 17.

  • radians (bool) – (optional) Whether angles are in radians. Defaults to False.

Returns:

A Mapy.cz URL which will open the given panorama.

Return type:

str