소개
Street View Static API 메타데이터 요청은 스트리트 뷰 파노라마에 대한 데이터를 제공합니다. 메타데이터를 사용하면 특정 위치에서 스트리트 뷰 이미지를 사용할 수 있는지, 위도와 경도 좌표, 파노라마 ID, 사진 촬영 날짜 및 이미지의 저작권 정보에 프로그래매틱 방식으로 액세스할 수 있습니다. 이 메타데이터에 액세스하면 애플리케이션에서 오류 동작을 맞춤설정할 수 있습니다.
Street View Static API 메타데이터 요청은 무료로 사용할 수 있습니다. 메타데이터를 요청할 때 할당량이 소모되지 않습니다. Street View Static API를 사용하여 이미지를 로드할 때만 할당량이 소모됩니다.
스트리트 뷰 이미지 메타데이터를 요청할 때 파노라마 이미지의 정확도는 50m입니다.
이미지 메타데이터 액세스
스트리트 뷰 이미지 메타데이터 요청은 다음 형식의 HTTP URL입니다.
https://maps.googleapis.com/maps/api/streetview/metadata?parameters
URL 표준 형식과 마찬가지로, 모든 매개변수는 앰퍼샌드(&) 문자를 사용하여 구분합니다.
메타데이터 요청의 필수 매개변수
메타데이터 요청은 다음 매개변수만 필요하지만 Street View Static API 이미지 요청과 동일한 URL 매개변수를 받습니다.
다음 중 하나를 수행합니다.
location: 텍스트 문자열 (예:Chagrin Falls, OH) 또는 쉼표로 구분된 위도 및 경도 좌표 쌍 (40.457375,-80.009353)일 수 있습니다.
또는
pano: 특정 파노라마 ID입니다. 파노라마는 시간이 지남에 따라 ID가 변경될 수 있으므로 이 ID를 유지하지 마세요. 대신 파노라마 ID를 새로고침할 수 있도록 위치 주소 또는 위도 및 경도 좌표를 저장합니다. 자세한 내용은 삭제된 파노라마 ID 새로고침을 참고하세요.
또한:
key및signature: 요청을 인증하려면 API 키가 필요합니다. 경우에 따라 디지털 서명도 필요하며 항상 권장됩니다. 자세한 내용은 키 및 서명 가져오기를 참고하세요.
필수 매개변수만 있는 메타데이터 요청은 다음과 같습니다.
https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=
또는 다음과 같이 할 수 있습니다.
https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=
삭제된 파노라마 ID 새로고침
파노라마 ID를 검색하려고 했는데 ZERO_RESULTS 또는 값이 없으면 파노라마 ID가 삭제되었으므로 새로고침해야 합니다.
필요한 경우 새로고침할 수 있도록 파노라마 ID를 가져오는 데 사용한 위치 주소 또는 위도와 경도 좌표를 저장합니다.
파노라마 ID가 변경된 것을 감지하면 원래 위치 주소 또는 위도와 경도 좌표를 사용하여 해당 위치에서 가장 가까운 파노라마를 다시 검색하고 새 파노라마 ID를 가져옵니다.
메타데이터 요청의 선택적 매개변수
메타데이터 요청에 size, heading, fov, pitch 파라미터를 포함할 수 있습니다. 이 매개변수는 파노라마에 대한 데이터 또는 찾을 수 있는 파노라마에 영향을 미치지 않습니다.
API를 사용하면 특정 이미지 요청과 관련된 메타데이터 요청을 훨씬 쉽게 생성할 수 있도록 이미지 요청과 동일한 매개변수를 포함할 수 있지만, 메타데이터 요청의 경우 API는 선택적 매개변수와 해당 값을 무시합니다. 이러한 매개변수 사용에 관한 자세한 내용은 Street View Static API 개발자 가이드를 참고하세요.
응답 형식
메타데이터 응답은 JSON 형식으로만 반환됩니다.
예
예시 1: 파노라마가 발견됨
다음 URL은 동일한 파노라마의 메타데이터 및 이미지를 요청합니다.
메타데이터 요청 및 응답
https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
{
"copyright" : "© 2017 Google",
"date" : "2016-05",
"location" : {
"lat" : 48.85783227207914,
"lng" : 2.295226175151347
},
"pano_id" : "tu510ie_z4ptBZYo2BGEJg",
"status" : "OK"
}
누락된 이미지가 예상되는 이미지 요청 및 응답
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
예 2: 파노라마를 찾을 수 없음
다음 URL은 지정된 위치 또는 그 근처에서 찾을 수 없는 파노라마에 대한 메타데이터 및 이미지를 요청합니다.
메타데이터 요청 및 응답
https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
{
"status" : "ZERO_RESULTS"
}
이미지 요청 및 응답
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
상태 코드
메타데이터 응답 객체 내의 status 필드는 요청의 상태를 포함하며, 스트리트 뷰 요청이 작동하지 않는 문제를 해결하는 데 도움이 되는 디버깅 정보를 포함할 수 있습니다. status 필드에는 다음 값이 포함될 수 있습니다.
| 상태 | 설명 |
|---|---|
"OK" |
오류가 발생하지 않았음을 나타냅니다. 파노라마를 찾고 메타데이터를 반환합니다. |
"ZERO_RESULTS" |
제공된 위치 근처에서 파노라마를 찾을 수 없음을 나타냅니다. 이 응답은 존재하지 않거나 유효하지 않은 파노라마 ID를 제공하는 경우 발생할 수 있습니다. [삭제된 파노라마 ID 새로고침](#refresh-pano)을 참고하세요. |
"NOT_FOUND" |
location 매개변수에 제공된 주소 문자열을 찾을 수 없음을 나타냅니다. 이 메시지는 제공된 주소가 존재하지 않을 때 발생할 수 있습니다. |
"OVER_QUERY_LIMIT" |
이 API에 대한 일일 할당량 또는 초당 할당량을 초과했음을 나타냅니다. |
"REQUEST_DENIED" |
요청이 거부되었음을 나타냅니다. 요청을 승인하지 않았거나 API 키가 포함된 Google Cloud 콘솔 프로젝트에서 Street View Static API가 활성화되지 않은 경우 이 메시지가 표시될 수 있습니다. |
"INVALID_REQUEST" |
일반적으로 쿼리 매개변수 (address, 위도 및 경도 좌표 또는 구성요소)가 누락되었음을 나타냅니다. |
"UNKNOWN_ERROR" |
서버 오류로 인해 요청을 처리할 수 없음을 나타냅니다. 이 문제는 종종 일시적인 문제입니다. 다시 시도하면 요청이 성공할 수도 있습니다. |
추가 정보
Street View Static API 또는 다른 Google Maps API 제품 사용에 관한 자세한 내용은 Maps API 지원 페이지를 참고하세요.