스트리트 뷰 타일은
거리 수준에서 촬영한 파노라마 이미지를
포함한다는 점을 제외하면
2D 타일과 유사합니다. 스트리트 뷰를 통해 전 세계의 명소를 탐험하고, 경이로운 자연을 감상하고, 박물관, 경기장, 식당, 소규모 업체 등의 내부를 둘러볼 수 있습니다.
이 API 엔드포인트를 사용하면 다음에 액세스할 수 있습니다.
- Google 지도 스트리트 뷰 타일
- 스트리트 뷰 메타데이터
- 스트리트 뷰 썸네일
거리 수준에서 촬영한 이미지 타일을 연결하여 실제 파노라마 효과를 만들 수 있습니다. 또한 위치 집합 (예: 경로)에 대해 최대 100개의 파노라마 ID를 쿼리하고 카메라 위치에 대한 더 심층적인 메타데이터를 가져올 수 있습니다.
스트리트 뷰 타일을 병합하려면 뷰어가 필요합니다. 스트리트 뷰 맞춤 파노라마 뷰어 등을 예로 들 수 있습니다.
API 키가 있으면 다음 단계를 수행하여 스트리트 뷰 이미지에 액세스할 수 있습니다.
세션 토큰을 가져옵니다.
mapType값을streetview로 설정해야 합니다.세션 토큰을 사용하여 하나 이상의 지리적 위치의 파노라마 식별자 (panoId)를 가져옵니다.
panoId 검색 응답의 파노라마 식별자를 사용하여 다음을 가져옵니다.
스트리트 뷰 메타데이터가 포함됩니다. 좌표 집합과 반경을 전달하여 스트리트 뷰 메타데이터를 가져올 수도 있습니다.
스트리트 뷰 메서드
다음 네 가지 메서드 중 하나를 호출하여 스트리트 뷰 이미지와 메타데이터에 액세스할 수 있습니다.
| 메서드 | 설명 |
|---|---|
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 |
지정된 파노라마에 대한 자세한 정보를 제공합니다. 세부정보에는 관련 주소와 인접한 파노라마로 연결되는 링크가 포함됩니다. |
스트리트 뷰 panoId 검색
좌표 (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
locationslocations배열은 하나 이상의 좌표 값 집합을 포함해야 하지만 더 많이 포함할 수도 있습니다(최대 100개).radiusradius값 (미터 단위로 측정됨)은 파노라마를 검색할 지정된 위치 주변의 원의 반경을 정의합니다. 기본값은 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입니다. 기본값은 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는 확대/축소 수준이고,
x 및 y는
원하는 스트리트 뷰 타일의
타일 좌표입니다. 스트리트 뷰 파노라마의 확대/축소 수준은 [0,5] 범위여야 하며, 0은 가장 넓은 시야를 나타냅니다.
| 확대/축소 수준 | 대략적인 시야 |
|---|---|
| 0 | 360° |
| 1 | 180° |
| 2 | 90° |
| 3 | 7° |
| 4 | 22.5° |
| 5 | 11.25° |
스트리트 뷰 타일 응답
스트리트 뷰 타일 요청이 성공하면 createSession 응답에 지정한 형식 및 크기의 이미지가 반환됩니다.
확대/축소 수준이 0일 때 전체 파노라마는 크기가 tileWidthxtileHeight인 타일로 크기가 조정됩니다. 파노라마는 x차원이 더 크므로
타일의 y 차원에는 빈 공간이 포함됩니다.
확대/축소 수준 5에서는 원본 크기 파노라마가 사용되고 타일로 분할됩니다.
저작권 정보
모든 스트리트 뷰 파노라마에 저작권 정보를 표시해야 합니다. 표시할 문자열은 파노라마마다 다를 수 있습니다. 저작권 정보를 가져오려면 스트리트 뷰 메타데이터를 요청해야 합니다. 그런 다음 응답의 copyright 필드를 참조할 수 있습니다. 자세한 내용은 데이터 저작자 표시를 참고하세요.