스트리트 뷰 타일

유럽 경제 지역 (EEA) 개발자

스트리트 뷰 타일 예시

스트리트 뷰 타일은 거리 수준에서 촬영한 파노라마 이미지를 포함한다는 점을 제외하면 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를 전달하면 지도 타일 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
파노라마의 주소에 관한 세부정보가 포함된 구조화된 지오코드입니다. 자세한 내용은 지오코딩 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 필드를 참조할 수 있습니다. 자세한 내용은 데이터 출처 표시를 참고하세요.