의견 보내기
스트리트 뷰 이미지 메타데이터
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
소개
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 참고 : 메타데이터 요청에는 https:// 프로토콜이 필요합니다.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=< YOUR_SIGNATURE > 또는 다음과 같이
https://maps.googleapis.com/maps/api/streetview/metadata?pano=& key=YOUR_API_KEY & signature=< YOUR_SIGNATURE > 삭제된 파노라마 ID 새로고침
파노라마 ID를 검색하려고 하는데 ZERO_RESULTS 또는 값이 없는 경우 파노라마 ID가 삭제된 것이므로 새로고침해야 합니다.
필요할 때 새로고침할 수 있도록 파노라마 ID를 가져오는 데 사용한 위치 주소 또는 위도 및 경도 좌표를 저장합니다.
파노라마 ID가 변경된 것을 감지하면 원래 위치 주소 또는 위도 및 경도 좌표를 사용하여 해당 위치에 가장 가까운 파노라마를 다시 검색하고 새 파노라마 ID를 가져옵니다.
참고: 스트리트 뷰 이미지는 주기적으로 새로고침되며 사진은 매번 약간 다른 위치에서 촬영될 수 있으므로 이미지 또는 파노라마 ID가 업데이트되면 특정 파노라마 ID가 다른 파노라마로 스냅될 수 있습니다. 메타데이터 요청에 size, heading, fov, pitch 파라미터를 포함할 수 있습니다. 이러한 매개변수는 파노라마에 관한 데이터나 발견된 파노라마에 영향을 미치지 않습니다.
API를 사용하면 이미지 요청 과 동일한 매개변수를 포함하여 특정 이미지 요청과 관련된 메타데이터 요청을 쉽게 구성할 수 있지만 메타데이터 요청의 경우 API는 선택적 매개변수와 해당 값을 무시합니다. 이러한 매개변수 사용에 관한 자세한 내용은 스트리트 뷰 정적 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 제품 사용에 대한 자세한 내용은 Maps API 지원 페이지 를 참고하세요.
의견 보내기
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스 에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스 에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책 을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
의견을 전달하고 싶나요?
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-29(UTC)"],[[["\u003cp\u003eThe Street View Static API metadata request provides data about Street View panoramas, such as location, date, and panorama ID, without consuming quota.\u003c/p\u003e\n"],["\u003cp\u003eYou need to provide either a \u003ccode\u003elocation\u003c/code\u003e (address or coordinates) or a \u003ccode\u003epano\u003c/code\u003e ID along with your API key to make a metadata request.\u003c/p\u003e\n"],["\u003cp\u003eThe response is in JSON format and includes the status of the request (e.g., \u003ccode\u003eOK\u003c/code\u003e, \u003ccode\u003eZERO_RESULTS\u003c/code\u003e, \u003ccode\u003eNOT_FOUND\u003c/code\u003e).\u003c/p\u003e\n"],["\u003cp\u003ePanorama IDs can change over time, so it's recommended to save the location information to refresh the ID when necessary.\u003c/p\u003e\n"],["\u003cp\u003eWhile optional parameters like \u003ccode\u003esize\u003c/code\u003e, \u003ccode\u003eheading\u003c/code\u003e, \u003ccode\u003efov\u003c/code\u003e, and \u003ccode\u003epitch\u003c/code\u003e are accepted, they do not affect the returned metadata.\u003c/p\u003e\n"]]],["The Street View Static API metadata requests provide panorama data, including location coordinates, panorama ID, photo date, and copyright. These requests are free and don't consume quotas. To access metadata, send an HTTP URL request with required parameters: either a `location` (address or coordinates) or `pano` (panorama ID), plus an API `key` and `signature`. If a panorama ID returns `ZERO_RESULTS`, refresh it using the original location. The response, in JSON, includes a `status` field indicating success or failure.\n"],null,["# Street View Image Metadata\n\nIntroduction\n------------\n\nThe Street View Static API metadata requests provide data about Street\nView panoramas. Using the metadata, you can find out if a Street View image\nis available at a given location, as well as getting programmatic access to\nthe latitude and longitude coordinates, the panorama ID, the date the photo was\ntaken, and the copyright information for the image. Accessing this\nmetadata lets you customize error behavior in your application.\n| **Note:** The value of the date field can vary:\n|\n| - The date field can have a different granularity for different panoramas. For example, the date field for some panoramas contains a year and month, while for others it contains just the year.\n| - The date field is omitted if no data is available.\n\nStreet View Static API metadata requests are available at no\ncharge. No quota is consumed when you request metadata.\n[Quota is only consumed](/maps/documentation/streetview/usage-limits) when you load an image using the\n[Street View Static API](/maps/documentation/streetview/overview).\n\nWhen making Street View imagery metadata requests, the panorama imagery\nis accurate to 50 meters.\n\nAccess the imagery metadata\n---------------------------\n\nA Street View image metadata request is an HTTP URL of the following form: \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview/metadata?parameters\n```\n| **Note** : the **https://** protocol is required for metadata requests.\n\nAs is standard in URLs, all parameters are separated using the ampersand\n(\\&) character.\n\n### Required parameters for metadata requests\n\nThe metadata requests accept the\n[same URL parameters](/maps/documentation/streetview/overview#url_parameters)\nas the Street View Static API imagery requests, although only\nthe following parameters are required:\n\nEither:\n\n- `location` --- can be either a text string (such as `Chagrin Falls, OH`) or a comma-separated pair of latitude and longitude coordinates (`40.457375,-80.009353`).\n\nOr:\n\n- `pano` --- a specific panorama ID. Panoramas may change IDs over time, so don't persist this ID. Instead, save the location address or latitude and longitude coordinates so you can refresh the panorama ID. For details, see [Refresh deleted panorama IDs](#refresh-pano).\n\nAs well as:\n\n- `key` and `signature` --- the API key is required to authenticate the request. The digital signature is also required in certain instances, and always recommended. For more information, see [Get a Key and Signature](/maps/documentation/streetview/get-api-key).\n\nYour metadata request, with only required parameters, looks like this: \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=\u003cYOUR_SIGNATURE\u003e\n```\n\nor like this: \n\n```html\nhttps://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=\u003cYOUR_SIGNATURE\u003e\n```\n\n### Refresh deleted panorama IDs\n\nIf you attempt to retrieve a panorama ID and get either `ZERO_RESULTS` or\nno value, then the panorama ID has been deleted and needs to be refreshed.\n\n1. Save the location address or latitude and longitude coordinates you used to\n get a panorama ID so you can refresh when needed.\n\n2. When you detect that a panorama ID has changed, use the original location\n address or latitude and longitude coordinates to search again for the nearest\n panoramas to that location and get a new panorama ID.\n\n| **Note:** Because Street View imagery is periodically refreshed, and photographs may be taken from slightly different positions each time, a given panorama ID may snap to a different panorama when imagery or the panorama ID is updated.\n\n### Optional parameters for metadata requests\n\nYou can include the following parameters in your metadata request: `size`,\n`heading`, `fov`, and `pitch`. Note that these parameters don't influence\nthe data about the panorama, or which panorama is found.\nThe API allows the inclusion of the same parameters as the\n[imagery request](/maps/documentation/streetview/overview#url_parameters)\nto make it easier to construct a metadata request related to a specific imagery\nrequest, but for metadata requests, the API ignores the optional parameters and\ntheir values. For information about using these parameters, see the\n[Street View Static API developer's guide](/maps/documentation/streetview/overview#url_parameters).\n\nResponse format\n---------------\n\nMetadata responses are returned in JSON format only.\n\nExamples\n--------\n\n#### Example 1: Panorama found\n\nThe following URLs successfully request the metadata and image of the same\npanorama.\n\nMetadata request and response \n\n```html\nhttps://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\n``` \n\n```scdoc\n{\n \"copyright\" : \"© 2017 Google\",\n \"date\" : \"2016-05\",\n \"location\" : {\n \"lat\" : 48.85783227207914,\n \"lng\" : 2.295226175151347\n },\n \"pano_id\" : \"tu510ie_z4ptBZYo2BGEJg\",\n \"status\" : \"OK\"\n}\n```\n\nImagery request and response, where the missing image is expected. \n\n```html\nhttps://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\n```\n\n#### Example 2: Panorama not found\n\nThe following URLs request the metadata and image for a panorama that\ncouldn't be found at or near the specified location.\n\n**Metadata request and response** \n\n```html\nhttps://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\n``` \n\n```scdoc\n{\n \"status\" : \"ZERO_RESULTS\"\n}\n```\n\n**Imagery request and response** \n\n```html\nhttps://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\n```\n\nStatus codes\n------------\n\nThe `status` field within the metadata response object contains the status of\nthe request, and may contain debugging information to help you troubleshoot\nwhy the Street View request is not working. The `status` field may contain\nthe following values:\n\n| Status | Description |\n|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `\"OK\"` | Indicates that no errors occurred; a panorama is found and metadata is returned. |\n| `\"ZERO_RESULTS\"` | Indicates that no panorama could be found near the provided location. This response can occur if you provide a non-existent or invalid panorama ID. See \\[Refresh deleted panorama IDs\\](#refresh-pano). |\n| `\"NOT_FOUND\"` | Indicates that the address string provided in the `location` parameter couldn't be found. This message may occur if a non-existent address is given. |\n| `\"OVER_QUERY_LIMIT\"` | Indicates that you have exceeded your daily quota or per-second quota for this API. |\n| `\"REQUEST_DENIED\"` | Indicates that your request was denied. This message may occur if you did not [authorize](/maps/documentation/streetview/get-api-key) your request, or if the Street View Static API is not activated in the Google Cloud console project containing your API key. |\n| `\"INVALID_REQUEST\"` | Generally indicates that the query parameters (address, latitude and longitude coordinates, or components) are missing. |\n| `\"UNKNOWN_ERROR\"` | Indicates that the request couldn't be processed due to a server error. This issue is often temporary. The request may succeed if you try again. |\n\nMore information\n----------------\n\nFor more information on using the Street View Static API, or\nother Google Maps API products, be sure to check out the Maps API\n[Support page](/maps/support)."]]
