새로운 지도 스타일 지정 기능이 곧 Google Maps Platform에 도입될 예정입니다. 이번 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트가 추가되었으며 지도 환경 및 사용성이 개선되었습니다. 모든 지도 스타일은 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 이전에 선택한 방법에 대한 자세한 내용은 Google Maps Platform의 새 지도 스타일을 참고하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

스트리트 뷰 타일

스트리트 뷰의 예 스트리트 뷰 타일은 거리 수준에서 찍은 파노라마 이미지를 포함한다는 점을 제외하면 2D 타일과 유사합니다. 스트리트 뷰를 통해 전 세계의 명소를 탐험하고, 경이로운 자연을 감상하고, 박물관, 경기장, 식당, 소규모 업체 등의 내부를 살펴볼 수 있습니다. 이 API 엔드포인트를 사용하면 다음에 액세스할 수 있습니다.

Google 지도 스트리트 뷰 타일
스트리트 뷰 메타데이터
스트리트 뷰 썸네일

거리 수준에서 찍은 이미지 타일을 함께 연결하여 실제 파노라마 효과를 만들 수 있습니다. 또한 위치 집합 (예: 경로)에 대해 최대 100개의 파노라마 ID를 쿼리하고 카메라 위치에 대한 심층적인 메타데이터를 가져올 수 있습니다.

뷰어가 스트리트 뷰 타일을 함께 연결해야 합니다. 예를 들어 스트리트 뷰 맞춤 파노라마 뷰어를 사용할 수 있습니다.

API 키가 있으면 다음 단계를 따라 스트리트 뷰 이미지에 액세스할 수 있습니다.

세션 토큰을 가져옵니다. mapType의 값을 streetview로 설정해야 합니다.
세션 토큰을 사용하여 하나 이상의 지리적 위치의 파노라마 식별자 (panoId)를 가져옵니다.
panoId 검색 응답의 파노라마 식별자를 사용하여 다음을 가져옵니다.
1. 스트리트 뷰 메타데이터 좌표 집합과 반경을 전달하여 스트리트 뷰 메타데이터를 가져올 수도 있습니다.
2. 스트리트 뷰 썸네일.
3. 스트리트 뷰 타일.

스트리트 뷰 메서드

다음 4가지 메서드 중 하나를 호출하여 스트리트 뷰 이미지와 메타데이터에 액세스할 수 있습니다.

메서드	설명
`https://tile.googleapis.com/v1/streetview/tiles`	개별 스트리트 뷰 타일을 반환합니다. 스트리트 뷰 타일은 6가지 확대/축소 수준(512픽셀에서 최대 13,312픽셀)으로 가져올 수 있습니다.
`https://tile.googleapis.com/v1/streetview/panoIds`	최대 100개의 위치를 일괄 검색할 수 있습니다. 이미지가 있는 모든 위치의 파노라마 ID를 반환합니다.
`https://tile.googleapis.com/v1/streetview/thumbnail`	스트리트 뷰 장면의 썸네일 JPEG 이미지를 반환합니다. 제목, 피치, 크기, 시야를 제공할 수 있습니다. 최소 크기는 16x16 픽셀입니다. 최대 크기는 250x600픽셀입니다.
`https://tile.googleapis.com/v1/streetview/metadata`	지정된 파노라마에 대한 자세한 정보를 제공합니다. 세부정보에는 관련 주소와 인접한 파노라마 사진에 대한 링크가 포함됩니다.

스트리트 뷰 panoId 검색

panoIds 메서드에 좌표 (lat, lng)를 전달하여 하나 이상의 지리적 위치에 대한 파노라마 식별자를 찾을 수 있습니다. 요청 본문은 다음 JSON 코드 예시와 같이 locations 배열과 radius(선택사항)가 포함된 JSON 객체입니다.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations: locations 배열은 좌표 값 집합을 하나 이상 포함해야 하지만 최대 100개까지 더 포함할 수 있습니다.
radius: radius 값 (미터로 측정됨)은 파노라마를 검색할 지정된 위치를 둘러싼 원의 반경을 정의합니다. 기본값은 50미터입니다.

PanoId 응답

Map Tiles API는 각 위치에서 가장 가까운 파노라마를 찾은 후 파노라마 ID를 반환합니다. 성공적인 panoIds 요청은 panoIds 배열을 포함하는 JSON 객체를 반환합니다. 배열에는 요청한 순서대로 파노라마 ID 목록이 포함됩니다. Map Tiles API에서 요청한 위치의 파노라마를 찾을 수 없는 경우 배열의 해당 위치에 빈 문자열이 반환됩니다. 예시는 다음 JSON 코드를 참조하세요.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

panoIds를 사용하여 다음 작업을 할 수 있습니다.

스트리트 뷰 메타데이터 요청
스트리트 뷰 썸네일 요청
스트리트 뷰 타일 요청

스트리트 뷰 메타데이터

스트리트 뷰 메타데이터 요청은 파노라마에 대한 정보를 검색합니다. 스트리트 뷰 메타데이터 요청은 HTTPS GET 요청입니다. 다음 두 가지 방법 중 하나로 파노라마에 관한 정보를 검색할 수 있습니다.

pano_id를 전달하면 Map Tiles API가 파노라마의 메타데이터를 반환합니다.
그러나 lat 및 lng를 전달하면 Map Tiles API가 지정된 검색 반경 내에서 가장 가까운 파노라마의 메타데이터를 반환합니다.

좌표 집합 및 반경 전달

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

파노라마 ID는 일시적이므로 초기 스트리트 뷰 메타데이터 요청에 좌표 집합과 radius 값을 전달하는 것이 좋습니다. 예를 보려면 다음 코드 스니펫을 참고하세요.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

스트리트 뷰 이미지의 panoId 전달

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

메타데이터 응답

다음 JSON 코드는 일반적인 메타데이터 응답의 예입니다.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

다음 목록에는 응답 본문의 필드 정의가 포함되어 있습니다.

panoId: 이 파노라마의 고유 ID입니다. 단일 사용자 세션보다 오래 유효한 파노라마 ID에 의존해서는 안 됩니다.
lat, lng: 파노라마의 좌표 (위도 및 경도)입니다. 이 값은 요청에서 전달한 좌표와 다를 수 있습니다. 위치가 가장 가까운 파노라마에 맞춰지기 때문입니다.
imageHeight, imageWidth: 연결한 파노라마 이미지의 크기입니다.
tileHeight, tileWidth: 단일 파노라마 타일의 크기입니다.
heading: 북쪽에서 시계 방향으로 도 단위로 측정된 나침반의 방위입니다. 방향은 [0,360] 범위 내에서 반환되며 0은 정북을 나타냅니다.
tilt: 파노라마의 남극에서 수평선까지 측정된 파노라마의 기울기입니다. 반환된 값은 [0, 180] 범위 내에 있습니다. 값이 90도이면 수평선이 이미 파노라마의 적도를 따라 정렬되었음을 나타냅니다.
roll: 수평선을 수평 맞추기 위해 파노라마에 적용된 시선을 기준으로 시계 방향으로 회전합니다. 반환된 값은 [0, 360] 범위 내에 있습니다.
imageryType: 이미지 유형을 나타냅니다. 유효한 값은 indoor, outdoor입니다.
date: 이미지를 촬영한 날짜입니다. 일부 이미지에 날짜 데이터가 없습니다. 하지만 가능한 경우 이 필드에는 연도 (YYYY)와 월(MM)의 조합이 포함됩니다. 예: 2023년 5월 또는 2024년
copyright: 스트리트 뷰 이미지와 함께 저작자로 표시해야 하는 저작권 텍스트입니다.
reportProblemLink: 사용자가 이 스트리트 뷰 타일의 문제를 신고하는 데 사용할 수 있는 하이퍼링크입니다. 이 하이퍼링크는 이미지의 오른쪽 하단에 표시해야 하며 '이미지의 문제 신고'와 같은 링크 텍스트를 포함해야 합니다.
addressComponent: 파노라마의 주소에 대한 세부정보가 포함된 구조화된 지오코드입니다. 자세한 내용은 Geocoding API 문서의 지오코딩 요청 및 응답을 참고하세요.
links: 이 파노라마 ID에 연결된 파노라마 ID 목록입니다. 링크가 있는 제목도 포함됩니다. 예를 들어 방향이 180°이면 연결된 파노라마는 현재 파노라마의 정남입니다. 파노라마 ID는 임시적이므로 단일 사용자 세션에서 이 ID를 이용해서는 안 됩니다.

스트리트 뷰 썸네일

thumbnail 형식으로 스트리트 뷰 이미지를 요청할 수 있습니다. 썸네일은 사용자가 정의한 크기, 방향, 피치, 시야각이 포함된 타일이 아닌 이미지입니다. 썸네일 이미지는 타일보다 해상도가 낮고 파일 크기가 더 작습니다. 다음 코드 프로토타입과 같이 thumbnail 엔드포인트에 GET 요청을 전송하여 썸네일을 요청합니다.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

캐나다 휘슬러에서 촬영한 스트리트 뷰 이미지의 썸네일을 다운로드하는 다음 코드 예를 살펴보겠습니다.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

필수 매개변수

panoId: 원하는 썸네일의 고유 ID입니다. panoIds 엔드포인트 또는 metadata 엔드포인트에서 파노라마 ID 값을 가져올 수 있습니다. 두 엔드포인트 모두 지리 좌표를 사용하고 적절한 panoId을 반환합니다.
session: 유효한 세션 토큰입니다.
key: API 키입니다.

선택적 매개변수

height: 썸네일의 높이를 픽셀 단위로 지정하며 범위는 16~250픽셀입니다. 높이를 지정하지 않으면 높이는 최대 허용 값인 250픽셀로 기본 설정됩니다. 범위를 벗어난 값을 지정하면 썸네일이 가장 가까운 유효한 값에 맞춰집니다.
width: 썸네일의 너비를 픽셀 단위로 지정하며 범위는 16~600픽셀입니다. 너비를 지정하지 않으면 너비는 기본적으로 최대 허용 값인 600픽셀로 설정됩니다. 범위를 벗어난 값을 지정하면 썸네일이 가장 가까운 유효한 값에 맞춰집니다.
pitch: 세로축을 따르는 카메라의 각도를 지정합니다. 유효한 값의 범위는 -90~90 (포함)입니다. 기본값은 0입니다.
yaw: 가로축을 따라 카메라의 방향을 지정합니다. 유효한 값의 범위는 -360~360 (포함)입니다. 기본값은 0입니다.
fov: 가로 시야각을 도 단위로 표현하며 최댓값은 120입니다. 고정된 크기의 표시 영역을 다루는 경우 설정된 크기의 스트리트 뷰 이미지와 마찬가지로 시야는 확대/축소를 나타냅니다. 값이 작을수록 확대/축소 수준이 높아집니다. 기본값은 90입니다.

스트리트 뷰 이미지 타일

panoId가 있으면 스트리트 뷰 이미지 타일을 요청할 수 있습니다. 타일 요청은 HTTPS GET 요청입니다. 다음 예를 참고하세요.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

이 코드 예에서 z는 확대/축소 수준이고 x 및 y는 원하는 스트리트 뷰 타일의 타일 좌표입니다. 스트리트 뷰 파노라마의 확대/축소 수준은 [0,5] 범위여야 하며 0은 가장 넓은 시야를 나타냅니다.

확대/축소 수준	대략적인 시야
0	360°
1	180°
2	90°
3	7°
4	22.5°
5	11.25°

스트리트 뷰 타일 응답

스트리트 뷰 타일 요청이 성공하면 createSession 응답에 지정한 형식 및 크기의 이미지가 반환됩니다.

성공적인 Tile 요청의 결과

확대/축소 수준이 0이면 전체 파노라마가 tileWidthxtileHeight 크기의 타일로 크기가 조절됩니다. 파노라마는 x 차원이 더 크기 때문에 타일의 y 차원에는 빈 공간이 포함됩니다.

확대/축소 수준 0

확대/축소 수준 5에서는 전체 크기 파노라마가 사용되고 타일로 나뉩니다.