스트리트 뷰 타일

스트리트 뷰 예시스트리트 뷰 타일은 거리 수준에서 촬영한 파노라마 이미지를 포함한다는 점을 제외하면 2D 타일과 유사합니다. 스트리트 뷰를 통해 세계의 명소를 탐색하고, 경이로운 자연을 둘러보며, 박물관, 경기장, 식당, 작은 상점 등의 내부에도 들어가 보세요. 이 API 엔드포인트를 사용하면 다음에 액세스할 수 있습니다.

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

지상에서 촬영한 이미지 타일을 이어 붙여 실제 파노라마 효과를 만들 수 있습니다. 또한 경로와 같은 일련의 위치에 대해 최대 100개의 파노라마 ID를 쿼리하고 카메라 위치에 관한 자세한 메타데이터를 가져올 수 있습니다.

스트리트 뷰 타일을 이어붙이는 작업은 보기 권한 사용자가 해야 합니다. 예를 들어 스트리트 뷰 맞춤 파노라마 뷰어를 들 수 있습니다.

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

  1. 세션 토큰을 가져옵니다. mapType 값을 streetview로 설정해야 합니다.

  2. 세션 토큰을 사용하여 하나 이상의 지리적 위치의 파노라마 식별자(panoId)를 가져옵니다.

  3. panoId 검색 응답의 파노라마 식별자를 사용하여 다음을 가져옵니다.

    1. 스트리트 뷰 메타데이터 좌표 집합과 반경을 전달하여 스트리트 뷰 메타데이터를 가져올 수도 있습니다.

    2. 스트리트 뷰 썸네일.

    3. 스트리트 뷰 타일.

스트리트 뷰 메서드

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

메서드 설명
https://tile.googleapis.com/v1/streetview/tiles 개별 스트리트 뷰 타일을 반환합니다. 스트리트 뷰 타일은 512픽셀(최대 13,312픽셀)의 6가지 확대/축소 수준에서 가져올 수 있습니다.
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 지정된 파노라마에 대한 자세한 정보를 제공합니다. 세부정보에는 관련 주소와 인접한 파노라마 링크가 포함됩니다.

좌표(lat, lng)를 panoIds 메서드에 전달하여 하나 이상의 지리적 위치의 파노라마 식별자를 찾을 수 있습니다. 요청 본문은 다음 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에서 해당 파노라마의 메타데이터를 반환합니다.

  • 하지만 latlng를 전달하면 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 목록입니다. 링크가 있는 제목도 포함됩니다. 예를 들어, 기수 방향이 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입니다. 기본값은 s 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는 확대/축소 수준이고 xy는 원하는 스트리트 뷰 타일의 타일 좌표입니다. 스트리트 뷰 파노라마의 확대/축소 수준은 [0,5] 범위여야 하며, 0은 가장 넓은 시야를 나타냅니다.

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

스트리트 뷰 타일 응답

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

타일 요청 성공 결과

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

확대/축소 수준 0

확대/축소 수준 5에서는 원본 크기 파노라마가 사용되고 타일로 분할됩니다.

모든 스트리트 뷰 파노라마에는 저작권 정보를 표시해야 합니다. 표시할 문자열은 파노라마마다 다를 수 있습니다. 저작권 정보를 가져오려면 스트리트 뷰 메타데이터를 요청해야 합니다. 그런 다음 응답의 copyright 필드를 참조할 수 있습니다. 자세한 내용은 데이터 저작자 표시를 참고하세요.