streetlevel.kakao: Kakao Road View

Finding panoramas

find_panoramas(lat, lon, radius=35, limit=50, session=None)

Searches for panoramas within a radius around a point.

Parameters:

lat (float) – Latitude of the center point.

lon (float) – Longitude of the center point.

radius (int) – (optional) Search radius in meters, max. 100. Defaults to 35, which is the value used by the KakaoMap client when fetching neighboring panoramas.

limit (int) – (optional) Number of results to return, max. 100. Defaults to 50, which is the value used by the KakaoMap client when fetching neighboring panoramas.

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

Returns:

A list of KakaoPanorama objects.

Return type:

List[KakaoPanorama]

Usage sample:
from streetlevel import kakao

panos = kakao.find_panoramas(37.4481486, 126.4509719)
print(panos[0].lat, panos[0].lon)
print(panos[0].id)
print(panos[0].date)
async find_panoramas_async(lat, lon, session, radius=35, limit=50)

Parameters:

lat (float)

lon (float)

session (ClientSession)

radius (int)

limit (int)

Return type:

List[KakaoPanorama]

Usage sample:
from streetlevel import kakao
from aiohttp import ClientSession

async with ClientSession() as session:
    panos = await kakao.find_panoramas_async(37.4481486, 126.4509719, session)
    print(panos[0].lat, panos[0].lon)
    print(panos[0].id)
    print(panos[0].date)
find_panorama_by_id(panoid, neighbors=True, session=None)

Fetches metadata of a specific panorama.

This call only appears to work for the most recent coverage at a location. IDs of older panoramas will return nothing even though they exist.

Parameters:

panoid (int) – The pano ID.

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

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

Returns:

A KakaoPanorama object if a panorama with this ID was found, or None.

Return type:

KakaoPanorama | None

Usage sample:
from streetlevel import kakao

pano = kakao.find_panorama_by_id(1168949345)
print(pano.lat, pano.lon)
print(pano.date)
print(pano.address)
async find_panorama_by_id_async(panoid, session, neighbors=True)

Parameters:

panoid (int)

session (ClientSession)

neighbors (bool)

Return type:

KakaoPanorama | None

Usage sample:
from streetlevel import kakao
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await kakao.find_panorama_by_id_async(1168949345, session)
    print(pano.lat, pano.lon)
    print(pano.date)
    print(pano.address)

Downloading panoramas

get_panorama(pano, zoom=2)

Downloads a panorama and returns it as PIL image.

Parameters:

pano (KakaoPanorama) – The panorama to download.

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

Returns:

A PIL image containing the panorama.

Return type:

Image

async get_panorama_async(pano, session, zoom=2)

Parameters:

pano (KakaoPanorama)

session (ClientSession)

zoom (int)

Return type:

Image

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

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

Parameters:

pano (KakaoPanorama) – The panorama to download.

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.

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 kakao

pano = kakao.find_panorama_by_id(1168949345)
kakao.download_panorama(pano, f"{pano.id}.jpg")
async download_panorama_async(pano, path, session, zoom=2, pil_args=None)

Parameters:

pano (KakaoPanorama)

path (str)

session (ClientSession)

zoom (int)

pil_args (dict | None)

Return type:

None

Usage sample:
from streetlevel import kakao
from aiohttp import ClientSession

async with ClientSession() as session:
    pano = await kakao.find_panorama_by_id_async(1168949345, session)
    await kakao.download_panorama(pano, f"{pano.id}.jpg")
get_depthmap(pano, session=None)

Downloads the depth map of a panorama and returns it as PIL image.

Parameters:

pano (KakaoPanorama) – The panorama.

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

Returns:

The depth map as PIL Image.

Return type:

Image

async get_depthmap_async(pano, session)

Parameters:

pano (KakaoPanorama)

session (ClientSession)

Return type:

Image

download_depthmap(pano, path, session=None)

Downloads the depth map of a panorama to a PNG file.

Parameters:

pano (KakaoPanorama) – The panorama.

path (str) – Output path.

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

Return type:

None

async download_depthmap_async(pano, path, session)

Parameters:

pano (KakaoPanorama)

path (str)

session (ClientSession)

Return type:

None

Data classes and enums

class KakaoPanorama(id, lat, lon, heading=None, wcongx=None, wcongy=None, image_path=None, neighbors=None, links=None, historical=None, date=None, street_name=None, address=None, street_type=None, panorama_type=None)

Metadata of a Kakao Road 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 (int)

lat (float)

lon (float)

heading (float)

wcongx (float)

wcongy (float)

image_path (str)

neighbors (List[KakaoPanorama])

links (List[Link])

historical (List[KakaoPanorama])

date (datetime)

street_name (str)

address (str)

street_type (str)

panorama_type (PanoramaType)

address: str = None

The address of the location as shown in the top-left corner in the panorama viewer.

date: datetime = None

Capture date and time of the panorama in UTC.

heading: float = None

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

historical: List[KakaoPanorama] = 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: int

The pano ID.

image_path: str = None

Part of the panorama tile URL.

property is_car: bool

Whether the panorama was taken by a car.

lat: float

Latitude of the panorama’s location.

links: List[Link] = None

The panoramas which the white arrows in the client link to.

lon: float

Longitude of the panorama’s location.

neighbors: List[KakaoPanorama] = None

A list of nearby panoramas.

panorama_type: PanoramaType = None

The panorama type and/or the camera the panorama was taken with. Identifiers are taken directly from the source.

permalink(heading=0.0, pitch=0.0, radians=False)

Creates a permalink to a panorama at this location.

The link will only work as expected for the most recent coverage at a location – it does not appear to be possible to directly link to older panoramas.

Parameters:

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

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

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

self (KakaoPanorama)

Returns:

A KakaoMap URL.

Return type:

str

street_name: str = None

The street name as overlaid on the road in the panorama viewer.

street_type: str = None

The street type (in Korean), e.g. “이면도로” (side road).

wcongx: float = None

X coordinate of the panorama’s location in the WCongnamul coordinate system.

wcongy: float = None

Y coordinate of the panorama’s location in the WCongnamul coordinate system.

class PanoramaType(value)

The panorama type and/or the camera the panorama was taken with. Identifiers are taken directly from the source.

PANOZIP = 100

ROTATOR = 101

CAR = 102

SKY = 103

NAVER_CAR = 200

INSTA360 = 201

INSTA_TITAN = 202

SEA = 203

SDMG_OFFICE = 204

Miscellaneous

build_permalink(id=None, wcongx=None, wcongy=None, heading=0.0, pitch=0.0, radians=False)

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

When linking by ID, the link will only work as expected for the most recent coverage at a location – it does not appear to be possible to directly link to older panoramas.

Parameters:

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

wcongx (float | None) – (optional) X coordinate of the panorama’s location in the WCongnamul coordinate system.

wcongy (float | None) – (optional) Y coordinate of the panorama’s location in the WCongnamul coordinate system.

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

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

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

Returns:

A KakaoMap URL which will open the given panorama.

Return type:

str