streetlevel.naver: Naver Street View

Finding panoramas

find_panorama(lat, lon, neighbors=True, historical=True, depth=False, session=None)

Searches for a panorama near the given point.

Aerial and underwater panoramas are ignored by this API call.

Parameters:

lat (float) – Latitude of the point.

lon (float) – Longitude of the point.

neighbors (bool) – (optional) Whether an additional network request is made to fetch nearby panoramas. Defaults to True.

historical (bool) – (optional) Whether an additional network request is made to fetch metadata of historical panoramas. Defaults to True.

depth (bool) – (optional) Whether an additional network request is made to fetch the depth map. Defaults to False.

session (Session | None) – (optional) A requests session.

Returns:

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

Return type:

NaverPanorama | None

Usage sample:
from streetlevel import naver

pano = naver.find_panorama(37.4481486, 126.4509719)
print(pano.lat, pano.lon)
print(pano.id)
print(pano.date)
async find_panorama_async(lat, lon, session, neighbors=True, historical=True, depth=False)

Parameters:

lat (float)

lon (float)

session (ClientSession)

neighbors (bool)

historical (bool)

depth (bool)

Return type:

NaverPanorama | None

Usage sample:
from streetlevel import naver
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await naver.find_panorama_async(37.4481486, 126.4509719, session)
    print(pano.lat, pano.lon)
    print(pano.id)
    print(pano.date)
find_panorama_by_id(panoid, language='en', neighbors=True, historical=True, depth=False, session=None)

Fetches metadata of a specific panorama.

Note that panorama_type, pitch and roll will be wrong if this is a 3D panorama because Naver has yet to update this endpoint.

Parameters:

panoid (str) – The pano ID.

language (str) – (optional) Language of description and title fields; accepted values are ko (Korean), en (English), ja (Japanese) and zh (Simplified Chinese).

neighbors (bool) – (optional) Whether an additional network request is made to fetch nearby panoramas. Defaults to True.

historical (bool) – (optional) Whether an additional network request is made to fetch metadata of historical panoramas. Defaults to True.

depth (bool) – (optional) Whether an additional network request is made to fetch the depth map. Defaults to False.

session (Session | None) – (optional) A requests session.

Returns:

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

Return type:

NaverPanorama | None

Usage sample:
from streetlevel import naver

pano = naver.find_panorama_by_id("hQ46n55JstD9C-tGdzZz2g")
print(pano.lat, pano.lon)
print(pano.date)
print(pano.heading)
async find_panorama_by_id_async(panoid, session, language='en', neighbors=True, historical=True, depth=False)

Parameters:

panoid (str)

session (ClientSession)

language (str)

neighbors (bool)

historical (bool)

depth (bool)

Return type:

NaverPanorama | None

Usage sample:
from streetlevel import naver
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await naver.find_panorama_by_id_async("hQ46n55JstD9C-tGdzZz2g", session)
    print(pano.lat, pano.lon)
    print(pano.date)
    print(pano.heading)
get_depth(panoid, session=None)

Fetches the legacy depth map of a panorama.

Parameters:

panoid (str) – The pano ID.

session (Session | None) – (optional) A requests session.

Returns:

The depth map of the faces in the order front, right, back, left, top, bottom.

Return type:

ndarray

async get_depth_async(panoid, session)

Parameters:

panoid (str)

session (ClientSession)

Return type:

ndarray

get_historical(panoid, session=None)

Fetches older panoramas at the location of the given panorama.

Parameters:

panoid (str) – The pano ID. For reasons unbeknownst to mankind, only panoramas older than the given one are returned, so to retrieve all available dates at a location, the ID of the most recent panorama must be used. This is the timeline_id returned by find_panorama_by_id.

session (Session | None) – (optional) A requests session.

Returns:

A list of NaverPanorama objects.

Return type:

List[NaverPanorama]

async get_historical_async(panoid, session)

Parameters:

panoid (str)

session (ClientSession)

Return type:

List[NaverPanorama]

get_neighbors(panoid, session=None)

Fetches neighbors of a panorama.

Parameters:

panoid (str) – The pano ID.

session (Session | None) – (optional) A requests session.

Returns:

A Neighbors object.

Return type:

Neighbors

async get_neighbors_async(panoid, session)

Parameters:

panoid (str)

session (ClientSession)

Return type:

Neighbors

Downloading panoramas

get_panorama(pano, zoom=2, equirect=False, stitching_method=CubemapStitchingMethod.ROW)

Downloads a panorama and returns it as PIL image.

Parameters:

pano (NaverPanorama) – The panorama.

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

equirect – (optional) Whether the panorama should be downloaded in equirectangular projection instead of a cubemap. Only available for 3D imagery. Defaults to False.

stitching_method (CubemapStitchingMethod) – (optional) Whether and how the faces of the cubemap are stitched into one image when downloading as cubemap. Defaults to ROW.

Returns:

A PIL image or a list of six PIL images depending on equirect and stitching_method.

Return type:

List[Image] | Image

async get_panorama_async(pano, session, zoom=2, equirect=False, stitching_method=CubemapStitchingMethod.ROW)

Parameters:

pano (NaverPanorama)

session (ClientSession)

zoom (int)

stitching_method (CubemapStitchingMethod)

Return type:

List[Image] | Image

download_panorama(pano, path, zoom=2, equirect=False, stitching_method=CubemapStitchingMethod.ROW, pil_args=None)

Downloads a panorama to a file. If the chosen format is JPEG, Exif and XMP GPano metadata are included.

Parameters:

pano (NaverPanorama) – The panorama.

path (str) – Output path.

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

equirect – (optional) Whether the panorama should be downloaded in equirectangular projection instead of a cubemap. Only available for 3D imagery. Defaults to False.

stitching_method (CubemapStitchingMethod) – (optional) Whether and how the faces of the cubemap are stitched into one image when downloading as cubemap. Defaults to ROW.

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 naver

pano = naver.find_panorama_by_id("hQ46n55JstD9C-tGdzZz2g")
naver.download_panorama(pano, f"{pano.id}.jpg")
async download_panorama_async(pano, path, session, zoom=2, equirect=False, stitching_method=CubemapStitchingMethod.ROW, pil_args=None)

Parameters:

pano (NaverPanorama)

path (str)

session (ClientSession)

zoom (int)

stitching_method (CubemapStitchingMethod)

pil_args (dict | None)

Return type:

None

Usage sample:
from streetlevel import naver
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await naver.find_panorama_by_id_async("hQ46n55JstD9C-tGdzZz2g", session)
    await naver.download_panorama_async(pano, f"{pano.id}.jpg", session)
get_model(panoid, session=None)

Fetches the 3D model of the panorama. Only available if the panorama type is MESH_EQUIRECT.

Parameters:

panoid (str) – The pano ID.

session (Session | None) – (optional) A requests session.

Returns:

The vertices and faces of the model, or None if this panorama does not have a 3D model.

Return type:

Model | None

async get_model_async(panoid, session)

Parameters:

panoid (str)

session (ClientSession)

Data classes and Enums

class Model(vertices, faces)

The vertices and faces of a 3D model used for 3D panoramas in Naver Map.

(The UV map is not provided by the server, and I haven’t been able to fully work out how to generate it, so it’s not available yet. Sorry.)

Parameters:

vertices (ndarray)

faces (ndarray)

faces: ndarray

vertices: ndarray

class NaverPanorama(id, lat, lon, heading=None, altitude=None, pitch=None, roll=None, max_zoom=None, neighbors=None, links=None, historical=None, timeline_id=None, date=None, is_latest=None, description=None, title=None, depth=None, has_equirect=None, panorama_type=None, overlay=None)

Metadata of a Naver Street View panorama.

ID, latitude and longitude are always present. The availability of other metadata depends on which function was called and what was returned by the API.

Parameters:

id (str)

lat (float)

lon (float)

heading (float)

altitude (float)

pitch (float)

roll (float)

max_zoom (int)

neighbors (Neighbors)

links (List[Link])

historical (List[NaverPanorama])

timeline_id (str)

date (datetime)

is_latest (bool)

description (str)

title (str)

depth (ndarray)

has_equirect (bool)

panorama_type (PanoramaType)

overlay (Overlay | None)

altitude: float = None

Altitude of the camera above sea level, in meters.

date: datetime = None

Capture date and time of the panorama in UTC.

depth: ndarray = None

The legacy depth maps of the cubemap faces.

description: str = None

The description field, which typically contains the neighborhood and city.

has_equirect: bool = None

If True, this panorama can be fetched as either in equirectangular projection or as a cubemap. If False, only a cubemap is available.

heading: float = None

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

historical: List[NaverPanorama] = None

A list of panoramas with a different date at the same location. Only available if the panorama was retrieved by find_panorama_by_id.

id: str

The pano ID.

is_latest: bool = None

Whether this is the most recent panorama at its location.

lat: float

Latitude of the panorama’s location.

links: List[Link] = None

The panoramas which the white dots in the pre-3D client link to. This appears to be unused in the new client.

lon: float

Longitude of the panorama’s location.

max_zoom: int = None

Highest zoom level available for this panorama.

neighbors: Neighbors = None

A list of nearby panoramas.

overlay: Overlay | None = None

Curiously, in non-3D imagery, Naver masks their car twice: once with an image of a car baked into the panorama, and additionally with an image of the road beneath it (like Google and Apple), which is served as a separate file and overlaid on the panorama in the client. This is the URL to that secondary overlay.

(Only available for non-3D car footage.)

panorama_type: PanoramaType = None

The panorama type. Most identifiers are taken directly from the source.

permalink(heading=0.0, pitch=10.0, fov=80.0, map_zoom=17.0, radians=False)

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 10°.

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

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 (NaverPanorama)

Returns:

A Naver Map URL which will open this panorama.

Return type:

str

pitch: float = None

Pitch offset for upright correction of the panorama, in radians. Only available if has_equirect is True; the field is set to 0 otherwise.

roll: float = None

Roll offset for upright correction of the panorama, in radians. Only available if has_equirect is True; the field is set to 0 otherwise.

property tile_size: Size

Naver panoramas in equirectangular format are broken up into a grid of tiles. This returns the size of one tile.

timeline_id: str = None

The pano ID that must be given to the API to retrieve the full list of historical panoramas, which is also the ID of the most recent panorama at this location. If an earlier ID is used, only panoramas up to that panorama’s capture date are returned.

title: str = None

The title field, which typically contains the street name.

class Neighbors(street, other)

Nearby panoramas.

Parameters:

street (List[NaverPanorama])

other (List[NaverPanorama])

other: List[NaverPanorama]

Nearby aerial or underwater panoramas.

street: List[NaverPanorama]

Nearby panoramas taken at street level.

class Overlay(source, mask)

URLs to the images from which the overlay hiding the mapping car is created.

Parameters:

source (str)

mask (str)

mask: str

URL to the mask.

source: str

URL to the texture.

class PanoramaType(value)

The panorama type. Most identifiers are taken directly from the source.

ALL = 0

AIR = 1

DRONE = 2

CAR = 3

BICYCLE = 4

MUSEUM = 5

PENSION = 7

PENSION_FRONT = 8

INDOOR = 10

INDOOR_HIGH = 11

UNDERWATER = 12

TREKKER = 13

MESH_EQUIRECT = 15

An Apple-like panorama which can be fetched in equirectangular projection and for which a 3D mesh is available.

INDOOR_3D = 100

Miscellaneous

build_permalink(id, heading=0.0, pitch=10.0, fov=80.0, map_zoom=17.0, radians=False)

Creates a permalink to the given panorama.

Parameters:

id (str) – The pano ID.

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

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

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

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 Naver Map URL which will open the given panorama.

Return type:

str