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

소개

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가 변경될 수 있습니다.

또한:

  • keysignature: 요청을 인증하는 데 필요한 API 키입니다. 일부 경우에는 디지털 서명이 필요하며 항상 권장됩니다. 자세한 내용은 키 및 서명 가져오기를 참고하세요.

필수 매개변수만 포함된 메타데이터 요청은 다음과 같이 표시됩니다.

https://maps.googleapis.com/maps/api/streetview/metadata?location=<STRING>&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

또는 다음과 같이 만드세요.

https://maps.googleapis.com/maps/api/streetview/metadata?pano=<STRING>&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

메타데이터 요청의 선택적 매개변수

메타데이터 요청에 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가 제공된 경우 발생할 수 있습니다.
"NOT_FOUND" location 매개변수에 제공된 주소 문자열을 찾을 수 없음을 나타냅니다. 이 상태는 제공된 주소가 존재하지 않을 때 발생할 수 있습니다.
"OVER_QUERY_LIMIT" 이 API의 일일 할당량 또는 초당 할당량을 초과했음을 나타냅니다.
"REQUEST_DENIED" 요청이 거부되었음을 나타냅니다. 이 문제는 요청을 승인하지 않았거나 API 키가 포함된 Google Cloud Console 프로젝트에서 Street View Static API가 활성화되지 않은 경우에 발생할 수 있습니다.
"INVALID_REQUEST" 일반적으로 쿼리 매개변수 (주소, latlng 또는 구성요소)가 누락되었음을 나타냅니다.
"UNKNOWN_ERROR" 서버 오류로 인해 요청을 처리할 수 없음을 나타냅니다. 이는 대개 일시적인 상태입니다. 다시 시도하면 요청이 성공할 수도 있습니다.

추가 정보

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