스트리트 뷰 이미지 메타데이터

소개

Street View Static API 메타데이터 요청은 스트리트 뷰 파노라마에 관한 데이터를 제공합니다. 메타데이터를 사용하면 특정 위치에서 스트리트 뷰 이미지를 사용할 수 있는지 확인할 수 있을 뿐만 아니라 위도 및 경도 좌표, 파노라마 ID, 사진을 찍은 날짜, 이미지의 저작권 정보에 프로그래밍 방식으로 액세스할 수 있습니다. 이 메타데이터에 액세스하면 애플리케이션의 오류 동작을 맞춤설정할 수 있습니다.

Street View Static API 메타데이터 요청은 무료로 사용할 수 있습니다. 메타데이터를 요청할 때 할당량이 소모되지 않습니다. Street View Static API를 사용하여 이미지를 로드할 때만 할당량이 사용됩니다.

스트리트 뷰 이미지 메타데이터를 요청할 때 파노라마 이미지의 정확도는 50미터입니다.

이미지 메타데이터 액세스

스트리트 뷰 이미지 메타데이터 요청은 다음 형식의 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 새로고침을 참고하세요.

또한:

  • keysignature: 요청을 인증하는 데 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가 삭제되었으며 새로고침해야 합니다.

  1. 필요할 때 새로고침할 수 있도록 파노라마 ID를 가져올 때 사용한 위치 주소 또는 위도 및 경도 좌표를 저장합니다.

  2. 파노라마 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" 일반적으로 쿼리 매개변수 (주소, 위도 및 경도 좌표 또는 구성요소)가 누락되었음을 나타냅니다.
"UNKNOWN_ERROR" 서버 오류로 인해 요청을 처리할 수 없음을 나타냅니다. 이 문제는 대개 일시적인 문제입니다. 다시 시도하면 요청이 성공할 수도 있습니다.

추가 정보

Street View Static API 또는 기타 Google Maps API 제품에 대한 자세한 내용은 지도 API 지원 페이지를 참고하세요.