스트리트 뷰 타일

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

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

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

스트리트 뷰 타일을 함께 연결하려면 뷰어가 필요합니다. 예: 스트리트 뷰 맞춤 파노라마 뷰어

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

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

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

3. 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 목록입니다. 링크가 있는 제목도 포함됩니다. 예를 들어 방향이 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	45°
4	22.5°
5	11.25°

스트리트 뷰 타일 응답

성공적인 스트리트 뷰 타일 요청은 createSession 응답에 지정한 형식과 크기의 이미지를 반환합니다.

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

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

저작권 정보

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