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.

Parameters:

panoid (str) – The pano ID.

language (str) – (optional) Language of description and title fields; accepted values are ko (Korean) and en (English).

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 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, 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.

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

Returns:

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

Return type:

List[Image] | Image

async get_panorama_async(pano, session, zoom=2, 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, stitching_method=CubemapStitchingMethod.ROW, pil_args=None)

Downloads a panorama to a file.

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.

stitching_method (CubemapStitchingMethod) – (optional) Whether and how the faces of the cubemap are stitched into one image. 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, 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)

Data classes and Enums

class NaverPanorama(id, lat, lon, heading=None, elevation=None, camera_height=None, max_zoom=None, neighbors=None, links=None, historical=None, timeline_id=None, date=None, is_latest=None, description=None, title=None, depth=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)

elevation (float)

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

panorama_type (PanoramaType)

overlay (Overlay)

camera_height: float = None

Height of the camera in meters above ground.

date: datetime = None

Capture date and time of the panorama in UTC.

depth: ndarray = None

The depth maps of the faces.

description: str = None

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

elevation: float = None

Elevation at the capture location in meters.

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 client link to.

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

Curiously, 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 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

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.

AIR = 1

CAR = 3

BICYCLE = 4

INSIDE = 5

INTERIOR = 7

JIMMY_JIB = 8

INDOOR = 10

TREKKER = 13

UNDERWATER = 12

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