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

소개

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 새로고침을 참고하세요.

또한:

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

추가 정보

Street View Static API 또는 다른 Google Maps API 제품 사용에 관한 자세한 내용은 Maps API 지원 페이지를 참고하세요.