스트리트 뷰 타일

스트리트 뷰 예시스트리트 뷰 타일은 거리 수준에서 촬영된 파노라마 이미지가 포함된다는 점을 제외하고는 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는 해당 파노라마의 메타데이터를 반환합니다.

  • 하지만 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-05 또는 2024
copyright
스트리트 뷰 이미지와 함께 저작자 표시로 표시해야 하는 저작권 텍스트입니다.
reportProblemLink
사용자가 이 스트리트 뷰 카드의 문제를 신고하는 데 사용할 수 있는 하이퍼링크입니다. 이 하이퍼링크는 이미지의 오른쪽 하단에 표시해야 하며 '이 이미지 관련 문제 신고'와 같은 링크 텍스트를 포함해야 합니다.
addressComponent
파노라마 주소에 관한 세부정보가 포함된 구조화된 지오코드입니다. 자세한 내용은 Geocoding API 문서의 지오코딩 요청 및 응답을 참고하세요.
links
이 파노라마에 연결된 파노라마 ID 목록입니다. 링크가 있는 제목도 포함됩니다. 예를 들어, 기수 방향이 180°이면 링크된 파노라마는 현재 파노라마의 정남입니다. 파노라마 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 응답에 지정한 형식 및 크기의 이미지를 반환합니다.

타일 요청 성공의 결과

확대/축소 수준 0에서 전체 파노라마는 tileWidth x tileHeight 크기의 타일로 조정됩니다. 파노라마는 x 치수보다 크기 때문에 타일의 y 치수에 빈 공간이 포함됩니다.

확대/축소 수준 0

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

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